Using Workflows with ebXML

This section describes how you design and manage ebXML business processes using workflows, and it provides the steps you must take to start the exchange of ebXML business messages between trading partners. It includes the following topics:

• ebXML Business Messages

• Participating in an ebXML Conversation

• ebXML Sample Application

• ebXML Sample Application

 

---

ebXML Business Messages

A business message is the basic unit of communication between trading partners. Business messages are exchanged as part of a conversation. The roles in a conversation are implemented by workflows, which choreograph the exchange of business messages.

An ebXML business message contains one XML business document and zero or more attachments. An ebXML message is a communication protocol-independent MIME/Multipart message envelope, referred to as a message package. All message packages are structured in compliance with the SOAP Messages with Attachments specification.

The following figure represents the structure of a business message exchanged in a conversation based on the ebXML business protocol.

Figure 3-1 ebXML Business Message

 

The message package shown in the preceding figure illustrates the following logical MIME parts:

• Header Container—Logical container in which one SOAP 1.1-compliant message is stored. This SOAP message is an XML document; its root element is the SOAP Envelope, which, in turn, contains the following elements:

  • SOAP Header—ebXML-specific header elements. The SOAP Header is a generic mechanism for adding features to a SOAP message.

  • SOAP Body—Container for message service handler control data and information related to the payload parts of the message.

• Payload Container—Zero or more MIME parts containing application-level payloads. Payloads are not file-type-specific; they may contain XML or binary data.

 

---

Participating in an ebXML Conversation

A conversation is a series of business message exchanges between trading partners that is predefined by a conversation definition. A fundamental step in defining a conversation is creating the workflows that execute the roles in the conversation. A conversation definition that references the ebXML business protocol always contains two roles: initiator and participant. Each workflow template associated with an ebXML conversation performs only one of the two roles.

An ebXML plug-in extends the functionality of the WebLogic Integration Studio and process engine to allow you to design and execute the workflows that implement the roles in an ebXML conversation. Workflows are business processes. ebXML-based business processes can be designed as public or private processes.

Note: The information in this section is based on the assumption that the reader is familiar with the WebLogic Integration Studio. A detailed discussion of how to use the Studio is beyond the scope of this section. For information about starting and using the Studio, see Using the WebLogic Integration Studio and Learning to Use BPM with WebLogic Integration.

The following figure represents a simple ebXML Query Price and Availability (QPA) conversation that contains two roles, initiator and participant, and a high-level, hypothetical workflow for each role. Each trading partner implements one workflow for its role in the conversation. Each role has its own set of tasks required to send and receive the right ebXML messages at the right time.

Figure 3-2 Sample ebXML Conversation

 

The preceding figure illustrates the exchange of ebXML messages between trading partners in a conversation:

• One trading partner workflow, represented on the left in the preceding figure, starts the ebXML conversation by sending the first message.

• One trading partner workflow, represented on the right in the preceding figure, participates in the conversation by sending an ebXML message in response to the message it receives.

Key components of the ebXML conversation are described in the following sections:

• Starting an ebXML Conversation

• Sending an ebXML Message

• Receiving an ebXML Message

• Ending an ebXML Conversation

Starting an ebXML Conversation

Each trading partner in an ebXML conversation is assigned to one of two roles: initiator or participant. An ebXML conversation is started when a workflow sends an ebXML message in a new conversation. (For details, see Sending a Message in a New Conversation.)

The workflow that sends the first message in a conversation can be started in any of four ways:

• Timed—The workflow is started at an exact date and time that you specify.

• Manual—The workflow is started from the WebLogic Integration Worklist, meaning that it is started by a Worklist user.

• Called—The workflow is started by being called from another workflow.

• Event—The workflow is started when an XML document arrives on a JMS queue. (This event must not be an event that occurs as a result of the receipt of an ebXML business message.)

Sending an ebXML Message

A workflow task can send an ebXML message by invoking an ebXML action called Send ebXML Message. To add this action to a task node in a workflow:

1. In the Studio, right-click a definition in the list of template definitions, and select Open.

   The specified workflow template is displayed in the Studio.

2. Right-click the task node, and select Properties from the shortcut menu.

   The Task Properties dialog box is displayed.

3. Click Add to display the Add Action dialog box.

4. Choose ebXML Actions—>Send ebXML Message.

5. Click OK to display the Send ebXML Message dialog box, as shown in the following figure.

   Figure 3-3 Send ebXML Message Dialog Box

   
    

WebLogic Integration supports two modes for sending ebXML messages. Which mode is used depends on the circumstances under which the message is sent: the first message in a given conversation is sent in New Conversation mode; subsequent (response) messages are sent in Related Conversation mode.

For example, two ebXML messages are sent in the sample ebXML conversation illustrated in Figure  3-2. The first message (PriceAndAvailabilityQuote) is sent from the initiator workflow to the participant workflow; the second (PriceAndAvailabilityResponse), from the participant workflow to the initiator workflow.

The type of information required in the Send ebXML Message dialog box depends on which message type you select:

• Sending a Message in a New Conversation

• Sending a Message in a Related Conversation

Sending a Message in a New Conversation

In the case of PriceAndAvailabilityQuote, the first ebXML message in our sample conversation, select New Conversation in the Send ebXML dialog box, as shown in Figure  3-3, and then specify the following information:

• Conversation Name—Select the ebXML-based conversation from the drop-down list to specify the conversation in which the message is sent. The conversation definition is stored in your WebLogic Integration repository. (For information about configuring a conversation definition, see ebXML Business Messages.)

• Sender Business ID—Specify a business ID for the sender of the message. This is a unique value that identifies the trading partner sending the ebXML message. The value can be a static value or a value that is dynamically evaluated via the expression builder.

  Note: We recommend that you do not define business IDs as static values. Instead use a variable or an XPath expression to evaluate a business ID at runtime. In this way, your workflows can be used by multiple trading partners.

• Recipient Business ID—Specify a business ID for the recipient of the message. This is a unique value that identifies the trading partner receiving the ebXML message. The value can be a static value or a value that is dynamically evaluated via the expression builder. (See the Note for the previous bullet.)

• Envelope Variable—Specify a variable which will contain the ebXML message header (the SOAP envelope) after the composed ebXML message is sent. You can retrieve information, such as the message ID or conversation ID, from this variable in order to trace the status of the message.

• Message Payload data—Specify zero or more payloads. For each payload, specify a type (XML or ebXML binary) and an associated variable.

Sending a Message in a Related Conversation

In the case of PriceAndAvailabilityResponse (our sample ebXML message), which is sent by the participant workflow to the initiator workflow in response to the PriceAndAvailabilityQuote ebXML message, select Related Conversation in the Send ebXML dialog box, which is shown in Figure  3-3.

When you select Related Conversation in the Send ebXML dialog box, the Conversation Name, Sender Business ID, and Recipient Business ID fields are not available for you to write. These attributes are set once for a given conversation; that is, when the first ebXML message is sent in a new conversation. (For details, see Sending a Message in a New Conversation in the preceding section.) You do not need to specify the Conversation Name, Sender Business ID, and Recipient Business ID when you send a message in a related conversation because the system obtains these attributes from the previous ebXML message exchange. (For details, see Receiving an ebXML Message.)

However, in the Message Payload fields, you must specify the payload type (XML or ebXML binary) and associated variables for zero or more payloads.

Receiving an ebXML Message

WebLogic Integration supports two methods of receiving ebXML messages in workflows: Start nodes and Event nodes. Which node is used depends on the circumstances under which the message is received:

• A workflow for a trading partner in an ebXML-based conversation can be triggered by receiving an ebXML message from the workflow that initiates the conversation. This initial ebXML message triggers the start node of the participant workflow, which is defined as an ebXML Message start. The participant workflow in our sample conversation, illustrated in Figure  3-2, is an example of a workflow triggered in this way.

• Any ebXML workflow (the workflow for either the initiator role or the participant role) can wait at an event node for an ebXML message, such as a reply to a request. In our sample conversation, illustrated in Figure  3-2, the Wait for Response node in the initiator workflow is an example of such an event node.

Start Nodes

A workflow for a trading partner in an ebXML-based conversation can be started when it receives an ebXML message from another trading partner. The Studio provides an ebXML-specific option in the Start node to design these workflows.

To specify an ebXML event at the Start node in a workflow (for example, the Start node for the participant workflow illustrated in Figure  3-2):

1. Right-click the Start node, and then select Properties from the shortcut menu.

   The Start Properties dialog box is displayed.

   Figure 3-4 Start Properties Dialog Box

   
    

2. Select the Event option and, in the drop-down list, select EBXML Message.

3. In the Message Envelope fields, from the appropriate drop-down list, select:

   • The conversation to which an incoming message applies

   • A variable in which to store the message envelope

4. In the Message Payload field, select a type (XML or ebXML binary) for zero or more message attachments, and an associated variable in which to store the data for each attachment.

   Note: Each row in the Message Payload field represents an attachment in the associated ebXML message. When an ebXML message includes multiple attachments, the order of the rows in this field represents the order of the attachments in the message. If you leave a row in the Message Payload field empty, the corresponding attachment in the ebXML message is ignored when the message is received.

5. Click OK to save your settings and close the dialog box.

Event Nodes

A workflow can contain events designed to be triggered when an ebXML message is received for a particular instance of the workflow. An event that waits to receive an ebXML message must be defined as type ebXML Event. Such an event is triggered at run time when the appropriate ebXML message is received in the conversation.

To define an event that waits to receive an ebXML message:

1. Right-click the Event node, and then select Properties from the shortcut menu.

   The Event Properties dialog box is displayed.

   Figure 3-5 Event Properties Dialog Box

   
    

2. Select EBXML Event from the Type drop-down list.

3. From the drop-down list in the Envelope Variable field, select a variable in which to store the message envelope.

4. In the Message Payload field, select a type (XML or ebXML binary) for zero or more message attachments, and an associated variable in which to store the data for each attachment.

Note: Each row in the Message Payload field represents an attachment in the associated ebXML message. When an ebXML message includes multiple attachments, the order of the rows in this field represents the order of the attachments in the message. If you leave a row in the Message Payload field empty, the corresponding attachment in the ebXML message is ignored when the message is received.

5. Click OK to save your settings and close the dialog box.

Ending an ebXML Conversation

An ebXML-based conversation ends when the exchange of ebXML messages is complete for both trading partners.

Contrast this behavior to the XOCP business protocol. WebLogic Integration supports an XOCP conversation management service, meaning that the workflow responsible for initiating the conversation also ends the conversation and sends an end-of-conversation message to each workflow in the conversation. (For details, see Ending Collaborative Workflows in Creating Workflows for B2B Integration.)

In the case of an XOCP conversation, to define a conversation termination property, you must select the Custom option on the Done node in the workflow that initiated the conversation. Do not select this option for ebXML-based conversations: to the contrary, you should ensure that in workflows for ebXML conversations, the Custom option for Done nodes is not selected.

 

---

ebXML Sample Application

An ebXML sample application is provided in the SAMPLES_HOME\integration\samples\ebxml directory, where SAMPLES_HOME represents the WebLogic Platform samples directory. This sample demonstrates two workflows: one designed for the role of initiator; the other, for the role of participant in a Query Price and Availability (QPA) conversation. Both workflows are designed and used to manage an ebXML-based business process between two trading partners, each of which deploys WebLogic Integration. For information about this sample, including instructions for running it, see ebXML Sample in Running the B2B Integration Samples.

As additional ebXML samples become available, they will be posted on the BEA dev2dev Online site at the following URL:

http://dev2dev.bea.com