Working with Business Messages

 

The following sections explain how to use the B2B integration plug-in to construct and manipulate the contents of business messages that are exchanged among business partners:

• About Working with Business Messages

• Defining Workflow Variables for Business Messages

• Simple Message Manipulation

• Complex Message Manipulation

 

---

About Working with Business Messages

A business message is the basic unit of communication exchanged by trading partners in a conversation. A business message consists of the following:

• One or more business documents, which represent the XML-based payload part of a business message. The payload is the business content of a business message.

• Optionally, one or more attachments, which represent additional XML or nonXML payload parts of a business message.

The B2B integration plug-in provides two methods to either create or extract the contents from business messages:

• Simple message manipulation is supported by the Compose Business Message and Extract Business Message Parts actions. These two actions provide a means to manipulate the contents of business messages nonprogrammatically. In the current release of WebLogic Integration, the Compose Business Message and Extract Business Message Parts actions are supported for XOCP messages only.

• Complex message manipulation is supported by the Manipulate Business Message action. This action starts a user-written application that implements the MessageManipulator interface from the Message Manipulator API (package com.bea.b2b.wlpi). This interface enables you to create and manipulate complex messages. In the current release of WebLogic Integration, the Manipulate Business Message action is supported for XOCP messages only.

 

---

Defining Workflow Variables for Business Messages

At run time, a business message is stored in a workflow variable (of type Java Object) when it is ready to be sent or when it has been received. When a business message is ready to be sent, the application code associated with the action that composes the business message constructs the business message and returns it in this variable to the workflow instance. When a business message has been received, the workflow node associated with any of three actions (Compose Business Message, Extract Business Message Parts, or Manipulate Business Message) obtains this variable from the workflow instance and uses it to process the incoming business message.

Note: In WebLogic Integration, XOCP business messages are not stored in workflow variables of type XML Document.

In the Studio, you must define the Java Object variables used to store business messages before you define any actions that refer to them, as described in About Using Workflow Variables.

For each workflow template definition, you can define a separate variable for each business message that the workflow sends or receives, or you can define a single object variable to contain all your message exchanges.

To define a variable for a business document in the Studio:

1. In the folder tree, right-click Variables under the appropriate workflow template definition. Select New Variable to display the Variable Properties dialog box.

   Figure 4-1 Variable Properties Dialog Box

   
    

2. Specify a unique name for this variable.

3. Select the Java Object variable type.

4. Click OK.

 

---

Simple Message Manipulation

The B2B integration plug-in provides two actions that you can use for simple message manipulation:

• Compose Business Message—for creating a business message that you can subsequently send via the Send Business Message Action

• Extract Business Message Parts—for extracting the components of a business message for further processing, which you typically do after your workflow has received a business message

The primary ease-of-use feature provided by these two actions is that they provide a means to manipulate business messages entirely nonprogrammatically. The sections that follow explain how to use these two workflow actions.

Creating Business Messages

You can define the Compose Business Message action on any node in a collaborative workflow—start, task, decision, event, or done. You must explicitly add the Compose Business Message action to the workflow template definition. At run time, this action adds one or more XML documents and one or more attachments to a business message envelope, specified as variables in the Compose Business Message dialog box, which gives you an easy means to create a message that you can subsequently send via the Send Business Message action.

For overview information about the composition of a business message, refer to either of the following:

• Conversations and Business Messages

• "Supporting Business Protocols" in Overview in Introducing B2B Integration.

Defining the Compose Business Message Action

To define the Compose Business Message action for a workflow in the Studio:

1. In any dialog box where you can specify an action (such as the Task, Decision, Event, or Start Properties dialog box), click Add to display the Add Action dialog box.

   Figure 4-2 Add Action Dialog Box

   
    

2. Click the Integration Actions folder to expand it.

   Figure 4-3 Add Action Dialog Box with Integration Actions

   
    

3. Click the B2B Integration folder to expand it.

4. Select Compose Business Message.

5. Click OK to display the Compose Business Message dialog box.

   Figure 4-4 Compose Business Message Dialog Box

   
    

6. Complete the following fields in the Compose Business Message dialog box.

   Table 4-1 Fields in the Compose Business Message Dialog Box

   Field	Description
   Output Variable	The workflow variable of type Java object that holds the business message being composed.
   Part Number	The ID for each component in the business message being composed. Each entry in the Parts Assignment table must have a unique ID, and it must be a positive integer. To assign an ID: Click in the appropriate cell under the Part Number column. Enter the part ID.
   Part Type	Identifies the type of message part: XML business document, or attachment. XML documents must be defined with the workflow variable of type XML. Attachments must be defined with binary type. To choose a part type: Click in the appropriate cell under the Part column. Select the part type from the drop-down list that is displayed.
   Source	Identifies the workflow variable containing the filename of the associated part type. If the part type is XML, the source should be an XML variable containing the filename of the XML business document. If the part type is binary, the source should be a String variable containing the filename of the attachment. To choose a source file: Click in the appropriate cell under the Source column. Click the down-arrow that is displayed along the right edge of the cell. Select the variable name containing the name of the file that holds the appropriate message part.
   Text	Optional descriptive text.

   
    

7. To insert a message part between two parts that are already specified:

   1. Right-click the row where you want to make the insertion.

   2. Choose Insert. A blank row is created above the row on which you clicked.

8. To delete an entry in the Parts Assignments table of the Compose Business Message dialog box:

   1. Click the row specifying the message part you want to delete.

   2. Right-click and choose Delete.

9. When you have finished specifying the Compose Business Message dialog box, click OK.

Extracting Information from Business Messages

You can define the Extract Business Message Parts action on any node in a collaborative workflow—start, task, decision, event, or done. You must explicitly add the Extract Business Message Parts action to the workflow template definition. At run time, this action extracts the XML document(s) and attachment(s) to a business message envelope, specified as variables in the Extract Business Message Parts dialog box, which gives you an easy means to obtain the contents of a business message that has been received.

For overview information about the composition of a business message, refer to either of the following:

• Conversations and Business Messages

• "Supporting Business Protocols" in Overview in Introducing B2B Integration.

Defining the Extract Business Message Parts Action

To define the Extract Business Message Parts action for a workflow in the Studio:

1. In any dialog box where you can specify an action (such as the Task, Decision, Event, or Start Properties dialog box), click Add to display the Add Action dialog box.

   Figure 4-5 Add Action Dialog Box

   
    

2. Click the Integration Actions folder to expand it.

   Figure 4-6 Add Action Dialog Box with Integration Actions

   
    

3. Click the B2B Integration folder to expand it.

4. Select Extract Business Message Parts.

5. Click OK to display the Extract Business Message Parts dialog box.

   Figure 4-7 Extract Business Message Parts Dialog Box

   
    

6. Complete the following fields in the Extract Business Message Parts dialog box.

   Table 4-2 Fields in the Extract Business Message Parts Dialog Box

   Field	Description
   Input Variable	The workflow variable of type Java object that holds the business message from which the parts are being extracted.
   Part Number	The ID for each component to be extracted from the business message. Note the following: Each entry you specify in the Parts Assignment table must have a unique ID, it must be a positive integer, and it must correspond to the ID of the message part you want to extract from the business message. You do not need to extract every message part in the business message, only the parts in which you are interested. To assign an ID: Click in the appropriate cell under the Part Number column. Enter the part ID.
   Part Type	Identifies the type of message part being extracted: XML business document or attachment. XML documents must be defined with the workflow variable of type XML. Attachments must be defined with the binary type. To choose a part type: Click in the appropriate cell under the Part column. Select the part type from the drop-down list that is displayed.
   Destination	Identifies the workflow variable containing the filename of the associated part type. If the part type is XML, the destination should be an XML variable containing the filename of the XML business document. If the part type is binary, the destination should be a String variable containing the filename of the attachment. To choose a destination file: Click in the appropriate cell under the Destination column. Click the down-arrow that is displayed along the right edge of the cell. Select the variable name containing the name of the file that will hold the extracted message part.
   Text	Optional descriptive text.

   
    

7. To insert a message part between two parts that are already specified:

   1. Right-click the row where you want to make your insertion.

   2. Choose Insert. A blank row is created above the one on which you clicked.

8. To delete an entry in the Parts Assignments table of the Extract Business Message Parts dialog box:

   1. Click in the ID cell of the message part you want to delete.

   2. Right-click and choose Delete.

9. Click OK.

 

---

Complex Message Manipulation

You must perform the following tasks before you can create or extract the content of business messages via a Java application that implements the MessageManipulator interface:

• Create the workflow variables that will be used to hold the contents of the business messages that are created or manipulated, as explained in Defining Workflow Variables for Business Messages.

• Define the Manipulate Business Message action on the appropriate node in the workflow, as explained in Defining the Manipulate Business Message Action

• Write the Java application to process the business message by implementing the com.bea.b2b.wlpi.MessageManipulator interface and using the manipulate method on that object, as explained in Writing the Application to Manipulate Business Messages.

The sections that follow explain how to define the Manipulate Business Message action and to write the Java application.

Defining the Manipulate Business Message Action

At run time, the Manipulate Business Message action is invoked to manipulate a business message. If the workflow is sending a business message (such as a request), the Manipulate Business Message action runs the associated application code to create the business message and save it in an output variable that is sent subsequently in a Send Business Message action. If the workflow is receiving a business message (such as a reply), the Manipulate Business Message action captures the incoming business message in an input variable and passes it on to the associated application code for processing.

The Manipulate Business Message action can be associated with any of the following nodes: task, decision, event, and start. You must explicitly add the Manipulate Business Message action to the workflow template definition.

Adding a Manipulate Business Message Action

To define the Manipulate Business Message action for a workflow in the Studio:

1. In any dialog box where you can specify an action (such as the Task, Decision, Event, or Start Properties dialog box), click Add to display the Add Action dialog box.

   Figure 4-8 Add Action Dialog Box

   
    

2. Click the Integration Actions folder to expand it.

   Figure 4-9 Add Action Dialog Box with Integration Actions

   
    

3. Click the B2B Integration folder to expand it.

4. Select Manipulate Business Message.

5. Click OK to display the Manipulate Business Message dialog box.

   Figure 4-10 Manipulate Business Message Dialog Box

   
    

6. Select values for the following fields in the Manipulate Business Message dialog box.

   Table 4-3 Fields in the Manipulate Business Message Dialog Box

   Field	Description
   Manipulator Class Name	Name of a Java class that implements the com.bea.b2b.wlpi.MessageManipulator interface. For more information, see Writing the Application to Manipulate Business Messages. (Required)
   Input Variable	Name of a workflow variable that contains an existing business message, such as a message that has been received through a Receive Business Message action. The contents of this variable are passed, as the in parameter, to the manipulate operation in the specified Java class that implements the com.bea.b2b.wlpi.MessageManipulator interface. If no variable name is specified, the value of the in parameter is null. The specified variable must correspond to an existing workflow variable of type Java Object. For more information, see About Using Workflow Variables.
   Output Variable	Name of a workflow variable that contains the business message returned by the manipulate operation in the specified Java class that implements the com.bea.b2b.wlpi.MessageManipulator interface. The specified variable must correspond to an existing workflow variable of type Java Object. For more information, see About Using Workflow Variables. If no variable name is specified, then the return value of the manipulate operation is ignored.
   Notes	Optional descriptive text.

   
    

   When specifying variables for the input or output fields, follow these guidelines:

   • If the action receives a business message that you want to manipulate, then you must specify a value for the input variable field.

   • If the action sends a business message, then you must specify a value for the output variable field.

   • If you want to construct a business message to send, you can use a message manipulator with an output field that specifies the business message object.

7. Click OK to save your changes.

Example of a Manipulate Business Message Action

For example, suppose you specify the following settings in the Manipulate Business Message dialog box.

Table 4-4 Sample Settings in the Manipulate Business Message Dialog Box

Field	Description
Manipulator Class Name	examples.wlpiverifier.ProcessRequest
Input Variable	requestMsg
Output Variable	replyMsg

 

At run time, when the WebLogic Integration process engine executes the action with the specified settings, the following events occur:

1. An object of class examples.wlpiverifier.ProcessRequest is created using reflection and the default constructor.

2. The value of the in parameter (requestMsg) is retrieved.

3. The manipulate operation is invoked on the object.

4. The return value of the manipulate operation is stored in the workflow output variable (replyMsg).

Writing the Application to Manipulate Business Messages

You write a Java application that uses workflow variables and Java code to manipulate business messages that are exchanged between trading partners. The Manipulate Business Message action invokes this application to create a business message to either send or process a business message that has been received. This Java application implements the com.bea.b2b.wlpi.MessageManipulator interface. Such an application is referred to generically as a message manipulator.

For more information about defining the message manipulator class and input and output variables for the Manipulate Business Message action, see Defining the Manipulate Business Message Action. For more information about the com.bea.b2b.wlpi.MessageManipulator interface, see the BEA WebLogic Integration Javadoc.

Message Manipulator Features

Message manipulators can implement the following operations for processing business messages:

• Create business messages before sending them. (See Steps for Writing the Application that Implements the MessageManipulator Interface to Create a Business Message.) A workflow must send messages to participate in conversations.

  • At run time, the Manipulate Business Message action is invoked. The Manipulate Business Message action invokes the Java application to create a business message, based on the contents of other workflow variables, and returns the business message for storage in a variable. For more information, see Defining the Manipulate Business Message Action.

  • The Send Business Message action retrieves this variable and sends the business message. For more information, see Defining the Workflow to Send Business Messages.

• Process business messages after receiving them. (See Steps for Writing the Application that Implements the MessageManipulator Interface to Process the Contents of a Received Business Message.) After a business message has been received, an invoked business message manipulator extracts the contents of the message and stores any required message parts in workflow variables for use by other actions.

• Replace specific components in a received business message and send the message.

• Perform custom message extraction operations.

MessageManipulator Interface

To process business messages that are exchanged between roles in a conversation, workflow applications use Java classes that implement the com.bea.b2b.wlpi.MessageManipulator interface. This interface contains a single operation, manipulate, with the following signature:

XOCPMessage manipulate(WorkflowInstance instance, XOCPMessage in) throws WLPIException;

When calling the manipulate operation, a workflow specifies the following parameters.

Table 4-5 Parameters in the Manipulate Operation

Parameter	Description
instance	Current workflow instance, which can be used to get or set variables. For more information, see Defining the Manipulate Business Message Action.
in	XOCP message stored in the workflow variable specified as an input variable in the associated Manipulate Business Message action. If no input variable is specified in the Manipulate Business Message action or if the variable is empty, then null is passed.

 

The manipulate operation returns an XOCP message generated by the message manipulator. At run time, this XOCP message is stored in the output variable specified in the associated Manipulate Business Message action. If this output variable is not specified, then the return value is ignored.

Public Default Constructor

Classes that implement the message manipulator interface must have a public default constructor (a constructor without arguments). The process engine uses Java reflection to create objects of that class and therefore invokes the default constructor.

Steps for Writing the Application that Implements the MessageManipulator Interface to Create a Business Message

The ChannelMasterMessageFactoryII class shown in this section is an example of a message manipulator that constructs a business message. It is called by the Manipulate Business Message action that occurs in the workflow. It returns a reply message (xocpmsg variable) that is passed back to the workflow as the business message to send.

Step 1: Import the Necessary Packages

The following listing shows the packages that the ChannelMasterMessageFactoryII class imports, including the XOCP messaging objects that are used to create the XOCP message.

Listing 4-1 Importing the Necessary Packages

package wlcsamples.channelmaster;

import java.io.*;

import org.apache.xerces.dom.*;
import org.w3c.dom.*;

import com.bea.eci.logging.*;
import com.bea.b2b.wlpi.MessageManipulator;
import com.bea.b2b.wlpi.WorkflowInstance;
import com.bea.b2b.wlpi.WLPIException;

import com.bea.b2b.protocol.conversation.ConversationType;
import com.bea.b2b.enabler.*;
import com.bea.b2b.enabler.xocp.*;
import com.bea.b2b.protocol.messaging.*;
import com.bea.b2b.protocol.xocp.conversation.local.*;
import com.bea.b2b.protocol.xocp.messaging.*;

Step 2: Implement the MessageManipulator Interface

The following listing shows the ChannelMasterMessageFactoryII class declaration that implements the MessageManipulator interface.

Listing 4-2 Implementing the MessageManipulator Interface

public class ChannelMasterMessageFactoryII implements MessageManipulator

Step 3: Include a Default Constructor

The following listing shows the default constructor used for the ChannelMasterMessageFactoryII class.

Listing 4-3 Implementing a Default Constructor

public ChannelMasterMessageFactoryII(){}; 

Step 4: Include an Invocation to the Manipulate Method

The code in the following listing invokes the manipulate method, which retrieves the current workflow instance object, as well as the incoming business message.

Listing 4-4 Invoking the manipulate Method

public XOCPMessage manipulate(WorkflowInstance instance,
                                        XOCPMessage in)
    throws WLPIException{

Step 5: Get Input Variables from the Workflow Instance

The code in the following listing uses the getVariable method to obtain values from the current workflow instance to be used for creating the business message.

Listing 4-5 Getting the Input Variables

String content = (String) instance.getVariable(MESSAGE_CONTENT_VAR); 

Step 6: Create the Business Message

The code in the following listing does the following:

1. Creates the DOM object that represents the XML data used for composing the XML document.

2. Creates the XML document object using the DTD named temp-xml-transporter.dtd.

3. Creates each XML element for the XML document.

4. Creates an XOCP message, adding the XML document to it.

   Listing 4-6 Creating the XML Document

   DOMImplementationImpl domi = new DOMImplementationImpl(); 
   DocumentType dType = 
     domi.createDocumentType( "temp-xml-transporter", 
       "temp-xml-transporter", "temp-xml-transporter.dtd" ); 
   
   org.w3c.dom.Document rq = new DocumentImpl(dType);    
   Element root = rq.createElement("temp-xml-transporter");
   rq.appendChild(root);
         
   Element elementContent = rq.createElement("content");
   Text t1 = rq.createTextNode(content);
   elementContent.appendChild(t1);
   root.appendChild(elementContent);
   
   XOCPMessage xocpmsg = new XOCPMessage(""); 
   xocpmsg.addPayloadPart(new BusinessDocument(rq));

Step 7: Return the Request Message

The code in the following listing returns the request message in the variable xocpmsg (of type XOCPMessage). The return value is then assigned to an output variable (of type Java Object) in the workflow in preparation for sending the business message.

Listing 4-7 Returning the Request Message

return xocpmsg;

Steps for Writing the Application that Implements the MessageManipulator Interface to Process the Contents of a Received Business Message

The ChannelMasterMessageExtractorII class described in this section is an example of a message manipulator that receives and processes a business message. It is called by the Manipulate Business Message action associated with the Start event (defined as a Business Message start event) that is triggered when the initial business message is received from the conversation initiator workflow. It returns a reply message (replyMsg variable) that is passed back to the workflow as the business message to send.

Step 1: Import the Necessary Packages

The code in the following listing shows the packages that the ChannelMasterMessageExtractorII class imports, including the XOCP messaging objects that are used to create the XOCP business message.

Listing 4-8 Importing the Necessary Packages

package wlcsamples.channelmaster;

import java.io.*;

import org.apache.xerces.dom.*;
import org.w3c.dom.*;

import com.bea.eci.logging.*;
import com.bea.b2b.wlpi.MessageManipulator;
import com.bea.b2b.wlpi.WorkflowInstance;
import com.bea.b2b.wlpi.WLPIException;

import com.bea.b2b.protocol.conversation.ConversationType;
import com.bea.b2b.enabler.*;
import com.bea.b2b.enabler.xocp.*;
import com.bea.b2b.protocol.messaging.*;
import com.bea.b2b.protocol.xocp.conversation.local.*;
import com.bea.b2b.protocol.xocp.messaging.*;

Step 2: Implement the MessageManipulator Interface

The following listing shows the ChannelMasterMessageExtractorII class declaration that implements the MessageManipulator interface.

Listing 4-9 Implementing the MessageManipulator Interface

public class ChannelMasterMessageExtractorII implements MessageManipulator

Step 3: Include a Default Constructor

The following listing shows the default constructor used for the ChannelMasterMessageExtractorII class.

Listing 4-10 Implementing a Default Constructor

public ChannelMasterMessageExtractorII(){};

Step 4: Invoke the Manipulate Method

The code in the following listing invokes the manipulate method, which retrieves the current workflow instance object, as well as the incoming business message (request).

Listing 4-11 Invoking the manipulate Method

public XOCPMessage manipulate(WorkflowInstance instance,
                                        XOCPMessage in)
    throws WLPIException{

Step 5: Process the Request Message

The code in the following listing does the following:

1. Extracts the payload components from the business message.

2. For each payload part, extracts a DOM document.

3. Uses the DOM API on the DOM object to extract the XML content.

   Listing 4-12 Processing the Request Message

   PayloadPart[] payload = in.getPayloadParts();
   Document rq = null;
   
   if (payload != null && payload.length > 0){		// 
     BusinessDocument bd = (BusinessDocument)payload[0];
     rq = bd.getDocument();
     if (rq == null)
       throw new WLPIException("Did not get a reply document");        
   }
   Element root = rq.getDocumentElement();
   debug(root.toString());
         
   String name = root.getNodeName();
   if (!name.equals("temp-xml-transporter")) {
     throw new WLPIException(
       debug("Did not get temp-xml-transporter, found " + name));
   }
   if (!root.hasChildNodes()){
     throw new WLPIException(
       debug("No child nodes in temp-xml-transporter"));
   }
   Node childContent = root.getFirstChild();
   if (childContent == null){
     throw new WLPIException(
       debug("No child nodes inside temp-xml-transporter"));
   }
   String content = ((Text)childContent.getFirstChild()).getData(); debug("Content is " + content);