Sending and Receiving Business Messages

The following sections describe how to send and receive business messages in a collaborative workflow:

• Defining the Workflow to Send Business Messages

• Defining the Workflow to Receive Business Messages

Notes: If you are implementing conversations and workflows based on the RosettaNet protocol, see Implementing RosettaNet for B2B Integration for instructions. These instructions are based on the RosettaNet 1.1 and 2.0 protocols.

The XOCP business protocol, which is supported by the B2B functionality described in this document, is deprecated as of this release of WebLogic Integration. For information about the business protocol that is replacing XOCP, see the BEA WebLogic Integration Release Notes.

 

---

Defining the Workflow to Send Business Messages

After you create a business message in the WebLogic Integration Studio by using the Compose Business Message or Manipulate Business Message action, you send the business message using the Send Business Message action. This section explains how to define a Send Business Message action in a collaborative workflow so it sends a business message to a trading partner.

To define a Send Business Message action:

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 5-1 Add Action Dialog Box

   
    

2. Click the Integration Actions folder to expand it.

   Figure 5-2 Add Action Dialog Box with Integration Actions

   
    

3. Click the B2B Integration folder to expand it.

4. Select Send Business Message. Then click OK to display the Send Business Message dialog box.

Which portion of the Send Business Message dialog box is displayed depends on the protocol with which the workflow template was configured. The following sections explain how to specify the contents of this dialog box for each of the protocols supported in the B2B integration plug-in.

Sending Business Messages Using the XOCP 1.1 Protocol (Deprecated)

When you select the Send Business Message action in the Actions dialog box for a workflow template configured with the XOCP 1.1 protocol, the following dialog box is displayed.

Figure 5-3 Send Business Message Dialog Box for XOCP Messages

 

The Send Business Message dialog box displays the following tabs:

• Message—Allows you to specify the input message variable, router expression contents, and the target role.

• Token—Allows you to specify message token information to workflow variables described in Assigning Message Token Information to Workflow Variables.

• QoS—Allows you to specify the quality of service at this Send Business Message action level, described in Defining the Quality of Service for Message Delivery for a Send Business Message Action (Deprecated).

Complete the following fields in the Send Business Message dialog box.

Table 5-1 Fields in the Send Business Message Dialog Box  

Field	Description
Input Message Variable	Name of a workflow variable of type Java Object that contains the business message to be sent.
Router Expression Content	Contents of the Router Expression field: a trading partner name, an XPath expression, or a variable name. Router expressions might be overridden by router expressions specified in the WebLogic Integration repository. For more information about routers, see Advanced Configuration Tasks in Administering B2B Integration. This selection box has the following values from which to choose: Trading Partner Name—The Router Expression field contains a single trading partner name. XPath Expression—The Router Expression field contains an XPath expression. Variable Name—The Router Expression field contains a workflow variable (of type String) with the contents of the Xpath expression. The variable is selected from a drop-down list and may have been assigned by the Receive Business Message event.
Router Expression	Router expression that is used when the message is sent. If Trading Partner name is selected, the message is sent to the specified trading partner. If XPath Expression is selected, the message is sent based on the specified XPath expression. If this field is blank, a null filter is used. For more information about router expressions, see Advanced Configuration Tasks in Administering B2B Integration.
Target Role	The role in the conversation to which the message is sent. Required field.
Use Collaboration QoS	If the workflow template is configured with the XOCP protocol, this check box appears, allowing you to specify whether to use the Quality of Service defined at the template level or at this Send Business Message action level: If the check box is selected, WebLogic Integration uses the QoS information defined at the workflow template definition level, as described in Defining the Quality of Service for XOCP Message Delivery in the Workflow Template (Deprecated). If the check box is not selected, WebLogic Integration uses the QoS information defined at this Send Business Message action level, as described in Defining the Quality of Service for Message Delivery for a Send Business Message Action (Deprecated).
Notes	Optional descriptive text.

 

Assigning Message Token Information to Workflow Variables

When a business message is sent by the B2B messaging service, a message token is returned as a Java object at the programming level. The message token provides information about the message, such as the message ID, conversation ID, send success/failure, the delivery status, and the number of recipient destinations after final selection (router and filter evaluations) by the B2B engine. Applications call the getVariable method to get access to this variable.

This variable can be defined as an output variable that gets processed after the workflow ends. A message token is represented by the com.bea.b2b.protocol.messaging.MessageToken class, which is described in the BEA WebLogic Integration Javadoc.

You can configure collaborative workflows to get access to the message token by assigning the token and its associated information to workflow variables. At run time, values are assigned to the workflow instance variables after the Send Business Message action has completed.

To assign a message token and related information to workflow variables:

1. Open the Send Business Message dialog box, as described in Defining the Workflow to Send Business Messages.

2. In the Send Business Message dialog box, click the Token tab.

   Figure 5-4 Token Tab

   
    

   Note: The available options in this dialog box depend on the selected Quality of Service settings, as described in Defining the Quality of Service for XOCP Message Delivery in the Workflow Template (Deprecated).

3. Complete the following fields in the Token tab.

   Table 5-2 Fields in the Token Tab  

   Field	Description
   Token Variable	Assigns the returned message token to a workflow variable of type Java Object. This object can then only be passed to a business operation for processing.
   Send Status	Indicates whether the message was sent successfully (true for success and false for failure). Assigns the value to a workflow variable of type Boolean that can be accessed by the workflow or passed to a business operation.
   Number of Initial Recipients	Number of recipients assigned by the B2B engine after the message has traversed the router. Assigns the value to a workflow variable of type Integer that can be accessed by the workflow or passed to a business operation. This field appears only if the QoS Messaging Confirmation setting is one of the following selections: Up to XOCP Hub—Delivery confirmation is required when a message reaches the intermediary (default). Select this option to provide basic delivery confirmation with maximum run-time performance. Up to XOCP Hub Router—Delivery confirmation is required when a message reaches the router in the intermediary. This option provides the list of trading partners selected by the router to receive the message. All Destinations—Delivery confirmation is required from all destinations. Select this option to provide the maximum delivery confirmation details. May affect run-time performance.
   Number of Actual Recipients	Actual number of recipients. Assigns the value to a workflow variable of type Integer that can be accessed by the workflow or passed to a business operation. This field is shown only if the QoS Messaging Confirmation setting is "To all destinations."
   Ack Elapsed Time (ms)	Time taken, in milliseconds, for acknowledgments to be sent by all recipients. The value in this field is assigned a workflow variable of type Long that can be accessed by the workflow or passed to a business operation. This field is shown only if the QoS Messaging Confirmation setting is "Confirm message delivery to all destinations."
   Notes	Optional descriptive text.

   
    

   If the business message was sent using the synchronous send delivery option, then the message token cannot be used to wait for acknowledgments. If it is used for this purpose, the method returns immediately.

Defining the Quality of Service for Message Delivery for a Send Business Message Action (Deprecated)

The Quality of Service (QoS) is a set of attributes that are defined for reliable business message publishing that uses the XOCP protocol. In the Studio, you can define the QoS at the following levels:

• At the template level, where the settings apply to all Send Business Message actions, unless the QoS is specifically overridden by the definition of the action. For more information, see Defining the Quality of Service for XOCP Message Delivery in the Workflow Template (Deprecated).

• At the Send Business Message action level, where the settings apply to the specific action only, but override the settings specified at the template level.

To define QoS at the Send Business Message level:

1. Make sure the Use Conversation QoS check box is unselected in the Send Business Message action dialog box.

2. In the Send Business Message dialog box, select the QoS tab.

   The QoS tab appears.

   Figure 5-5 QoS Tab in the Send Business Message Action Dialog Box

   
    

3. Complete the fields in the QoS tab as described in Table  2-3.

4. Click OK.

Note: The definitions specified here apply to this Send Message action only, not to all send actions within this conversation.

Sending RosettaNet Business Messages

As of Release 7.0 of WebLogic Integration, all business messages are transmitted asynchronously. Sending business messages asynchronously offers performance benefits: After a task node that sends a business message has completed execution, workflow processing can immediately pass to the next node, if desired. It is not necessary to suspend the execution of the workflow while awaiting the business message return status.

To design a workflow that sends a business message asychronously, you must define the following:

• A task node that sends the business message (as before)

• A task node that specifies a timeout value, or due date, for the HTTP status event

• An event node that receives an HTTP status event

If you have RosettaNet-based workflows created with earlier versions of WebLogic Integration, you must modify the way in which they send business messages. For complete details about migrating existing RosettaNet-based workflows to the current release of WebLogic Integration, see BEA WebLogic Integration Migration Guide.

For complete details about creating workflows based on the RosettaNet protocols, including instructions for sending business messages, see Implementing RosettaNet for B2B Integration.

The following sections explain how to send business messages in workflows configured with the RosettaNet 1.1 and 2.0 protocols:

• Specifying the Send Business Message Action Using the RosettaNet 2.0 Protocol

• Specifying the Send Business Message Action Using the RosettaNet 1.1 Protocol

• Defining a Task Node that Specifies the HTTP Status Event Timeout Value

• Defining an Event Node to Receive an HTTP Status Event

Specifying the Send Business Message Action Using the RosettaNet 2.0 Protocol

In the task node that sends a business message in a workflow template configured with the RosettaNet 2.0 protocol, select the Send Business Message action in the Actions dialog box. The following dialog box is displayed.

Figure 5-6 Send Business Message Dialog Box for RosettaNet 2.0 Messages

 

Complete the following fields in the Send Business Message dialog box.

Table 5-3 Buttons and Fields in the Send Business Message Dialog Box

Field	Description
Message Type	Specifies the type of RosettaNet 2.0 message to send. To send a business message, click Action.
Input Content Variable	Specifies the name of the workflow variable of type XML containing the XML data to represent the service content.
Input Attachment Descriptor Variable	Specifies the name of the workflow variable of type XML containing the XML data for describing the attachment to be sent as part of the RosettaNet message.
Notes	Optional descriptive text.

 

For more information about sending RosettaNet 2.0 messages, see Implementing RosettaNet for B2B Integration.

Specifying the Send Business Message Action Using the RosettaNet 1.1 Protocol

In the task node that sends a business message in a workflow template configured with the RosettaNet 1.1 protocol, select the Send Business Message action in the Actions dialog box. The following dialog box is displayed.

Figure 5-7 Send Business Message Dialog Box for RosettaNet 1.1 Messages

 

Complete the following fields in the Send Business Message dialog box.

Table 5-4 Buttons and Fields in the Send Business Message Dialog Box

Field	Description
Message Type	Specifies the type of RosettaNet 1.1 message to send. To send a business message, click Action.
Input Content Variable	Specifies the name of the workflow variable of type XML containing the XML data to represent the service content.
Input Attachment Descriptor Variable	Specifies the name of the workflow variable of type XML containing the XML data for describing the attachment to be sent as part of the RosettaNet message.
Notes	Optional descriptive text.

 

For more information about RosettaNet 1.1 messages, including a few examples, see Implementing RosettaNet for B2B Integration.

Defining a Task Node that Specifies the HTTP Status Event Timeout Value

To define a task node that specifies a timeout value for receiving an HTTP status event, complete the following steps:

1. In the Studio toolbar, click Create Task and then click a location in the workflow diagram near the task node that sends the business message.

2. Double-click the task node that was just created.

   The Task Properties dialog box is displayed.

   Figure 5-8 Task Properties Dialog Box

   
    

3. In the Task Name field, enter a descriptive task name.

4. Select the Created tab in the Actions section of the window, and click Add. The Add Action dialog box is displayed.

   Figure 5-9 Add Actions Dialog Box

   
    

5. Right-click the folder named Task Actions, and select Set Task Due Date. The Set Task Due Date dialog box is displayed.

   Figure 5-10 Set Task Due Date Dialog Box

   
    

6. From the menu at the top of the Set Task Due Date dialog box, select Wait for timeout.

7. In the lower half of the dialog box, select the Due Date tab. In the Set to expression field, enter an appropriate timeout value. In Figure  5-10, for example, the timeout value is set to two hours.

   For complete details about specifying task due dates, see "Setting a Task Due Date" in Defining Actions in Using the WebLogic Integration Studio.

8. Select the Overdue Actions tab, shown in the following figure.

   Figure 5-11 Overdue Actions Tab

   
    

9. Click Add. The Add Actions dialog box is displayed.

10. In the Add Actions dialog box, expand the Task Actions folder, and select Mark Task as Done, as shown in the following figure.

    Figure 5-12 Mark Task as Done

    
     

11. Click OK. The Mark Task as Done dialog box is displayed, as shown in the following figure.

    Figure 5-13 Mark Task as Done Dialog Box

    
     

12. Select the current task and click OK.

13. Click OK in the Set Task Due Date dialog box.

14. Click OK in the Task Properties dialog box.

15. Save the workflow.

Defining an Event Node to Receive an HTTP Status Event

To create an event node that receives an HTTP staus event, complete the following steps:

1. In the Studio toolbar, click Create Event and then click a location in the workflow diagram near the task node that sends the business message.

2. Double click the event node. The Event Properties dialog box is displayed.

   Figure 5-14 Event Properties Dialog Box

   
    

3. In the Event Properties dialog box, enter an appropriate name for the event, such as StatusEvent, in the Description field.

4. In the Type field, select the RosettaNet Status Event.

5. From the Output Status Variable drop-down list, select an appropriate variable in which to store the HTTP status value.

6. Select the Actions tab and click Add.

   The Add Action dialog box is displayed.

7. Right-click the folder named Task Actions, select Mark Task As Done, and click OK.

   The Mark Task as Done dialog box is displayed.

8. Select the task created in Defining an Event Node to Receive an HTTP Status Event and click OK.

9. Click OK in the Event Properties dialog box.

Connecting the Nodes Associated with the Send Business Message Task

After defining the nodes associated with the send business message task, you must connect them. The Studio provides two means to connect nodes in a workflow:

• From the Studio toolbar:

  1. Click the Connection button.

  2. Click the node from which you want to begin the connection, drag it to the node at which you want to end the connection, and then release the mouse button to make the connection.

• From the Properties dialog box for a particular node:

  1. Double-click the source node from which you want to draw the connection. The Properties dialog box for it is displayed.

  2. On the Next tab, select the target node; that is, the node to which you want to connect.

The following figure shows an example of how four nodes (T5, T8, C1 and E1) are associated with an asynchronous Send Business Message task in a RosettaNet-based workflow.

Figure 5-15 Send Business Message Workflow

 

After you define and connect the nodes associated with a Send Business Message task, you typically pass execution from the task node that specifies a timeout value to a decision node. The decision node typically evaluates the HTTP status, and then determines the flow of execution as appropriate.

 

---

Defining the Workflow to Receive Business Messages

A workflow can receive a business message in the following circumstances:

• When a conversation participant workflow is waiting for the initial business message sent by the conversation initiator workflow. The first business message triggers the start node of the conversation, which is defined as a Business Message start. For more information, see Defining the Start Node for a Conversation Participant Workflow.

• When a conversation initiator workflow or conversation participant workflow is waiting in an event node for another message, such as a reply to a request, as described in Defining Business Message Receive Events.

The following sections describe procedures for setting up your workflow to receive business messages for each of the protocols supported in the B2B integration plug-in.

Defining Business Message Receive Events

If a workflow waits to receive a business message, such as a reply to a request or a subsequent (not an initial) request, you must define a Business Message Receive event. This event is triggered at run time when the appropriate business message is received in the conversation.

To define a Business Message Receive event:

1. Display or add an event node as described in Defining Workflow Templates in Using the WebLogic Integration Studio.

2. Double-click the event shape or right-click it in the folder tree and select the Properties command to display the Event Properties dialog box.

   Figure 5-16 Event Properties Dialog Box

   
    

3. In the Description field, enter a meaningful name for the Receive Business Message event.

4. In the drop-down list labeled Type, select Collaboration event.

The display of the Event Properties dialog box is refreshed. Which contents are displayed depends upon the protocol with which the workflow template has been configured. The following sections explain how to define the Receive Business Event for each of the protocols supported by the B2B integration plug-in.

Defining a Business Message Receive Event for the XOCP 1.1 Protocol (Deprecated)

If the workflow template is configured with the XOCP 1.1 protocol, when you select the Conversation event type, the following Event Properties dialog box is refreshed with the following contents.

Figure 5-17 Event Properties Dialog Box for Defining a Receive XOCP Message Event

 

To configure a Business Message Receive event for an XOCP message, select values for the following fields in the Event Properties dialog box.

Table 5-5 Fields in the Event Properties Dialog Box  

Variable	Description
Event Type	Select Incoming Business Message to define the event to wait for an incoming business message. (Selecting a method of conversation termination is explained in Defining the End of Conversation Participant Workflows.)
Target Variable	Name of a target workflow variable (of type Java Object) in which to store the business message. Required field.
Router Expression	Name of a workflow variable (of type String) in which to store an XPath expression. The value represents the XPath expression used by the sender to send the message. This XPath expression can be used later, in a router expression, to publish a reply to the current message. Optional field.
Sender Name	Name of a workflow variable (of type String) in which to store the name of the Trading Partner that sent the message. If the Convert Sender's Name to XPath check box is selected, then this name is converted to an XPath expression.
XPath Conversion	If this check box is selected, the contents of the variable specified in the Sender's Name field are converted to an XPath expression suitable for use in the Send Business Message action. If it is not selected, the Sender's Name variable is used as the actual name of the sending Trading Partner.

 

At run time, when the business message is received, the event is triggered and the target variable is set to the business message that was just received. If a router variable is specified, it contains an XPath expression that can be used to reply to the sender. For more information, see Defining the Workflow to Send Business Messages.

Defining a Business Message Receive Event for the RosettaNet 2.0 Protocol

If the workflow template is configured with the RosettaNet 2.0 protocol, the display of the Event Properties dialog box is refreshed with the following contents when you choose the Conversation event type.

Figure 5-18 Event Properties Dialog Box for Defining a Receive RosettaNet 2.0 Message Event

 

To configure a Business Message Receive event for a RosettaNet 2.0 message, select values for the following fields in the Event Properties dialog box.

Table 5-6 Fields in the Event Properties Dialog Box  

Variable	Description
Content Variable	Name of a target workflow variable of type XML in which to store the RosettaNet 2.0 XML business document content.
Attachment Descriptor Variable	Name of a target workflow variable of type XML in which to store the RosettaNet 2.0 message attachment content.

 

At run time, when the business message is received, the event is triggered and the target variables are set to the business message that was just received. For more information about defining a business message receive event for workflow templates configured with the RosettaNet 2.0 protocol, including examples, see Implementing RosettaNet for B2B Integration.

Defining a Business Message Receive Event for the RosettaNet 1.1 Protocol

If the workflow template is configured with the RosettaNet 1.1 protocol, when you select the Conversation event type, the display of the Event Properties dialog box is refreshed with the following contents.

Figure 5-19 Event Properties Dialog Box for Defining a Receive RosettaNet 1.1 Message Event

 

To configure a Business Message Receive event for a RosettaNet 1.1 message, select the name of a target workflow variable of type XML in which to store the RosettaNet 1.1 XML business document content.

At run time, when the business message is received, the event is triggered and the target variables are set to the business message that was just received. For more information about defining a business message receive event for workflow templates configured with the RosettaNet 1.1 protocol, including examples, see Implementing RosettaNet for B2B Integration.