bea.com | products | dev2dev | support | askBEA
 Download Docs   Site Map   Glossary 
Search
e-docs > WebLogic Platform > WebLogic Integration > B2B Topics > Creating Workflows > Working with Business Messages

Creating Workflows

 Previous Next Contents Index View as PDF  

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:

Note: The features described in this chapter are based on the XOCP business protocol, which is deprecated as of this release of WebLogic Integration. For information about working with RosettaNet business messages, see Implementing RosettaNet for B2B Integration. For information about working with ebXML business messages, see Implementing ebXML for B2B Integration. For information about the business protocol that is replacing XOCP, see the BEA WebLogic Integration Release Notes.

 

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:

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

 

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 (Deprecated)

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

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:

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:

      1. Click in the appropriate cell under the Part Number column.

      2. Enter the part ID.

    Part Type

    Identifies the type of message part: XML business document, or attachment.

    To choose a part type:

      1. Click in the appropriate cell under the Part column.

      2. 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.

    To choose a source file:

      1. Click in the appropriate cell under the Source column.

      2. Click the down-arrow that is displayed along the right edge of the cell.

      3. 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:

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:

    To assign an ID:

      1. Click in the appropriate cell under the Part Number column.

      2. Enter the part ID.

    Part Type

    Identifies the type of message part being extracted: XML business document or attachment.

    To choose a part type:

      1. Click in the appropriate cell under the Part column.

      2. 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.

    To choose a destination file:

      1. Click in the appropriate cell under the Destination column.

      2. Click the down-arrow that is displayed along the right edge of the cell.

      3. 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 (Deprecated)

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:

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:

  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:

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);

 

Back to Top Previous Next