bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

BPM - Workshop Interoperability Sample

Overview

The WebLogic Integration BPM - Workshop sample shows how Web services and workflows can invoke one another by exchanging XML documents. The sample demonstrates two scenarios:

- A workflow invokes a Web service with XML and later receives XML from the Web service.

- A Web service invokes a workflow with XML and later receives XML from the workflow.

The sample also demonstrates two message formats:

- Simple Object Access Protocol (SOAP) using Hypertext Transfer Protocol protocol (HTTP). The exchanges can be conversational or include asynchronous replies.

- Raw XML using HTTP. The message exchanges are non-conversational.

Note: The BPM - Workshop sample runs only on Window systems.

This section contains information on the following topics:

- Interoperation Scenario

- How the Sample Demonstrates the Scenario

Interoperation Scenario

Figure 1-1 shows how a workflow can invoke a Web service with an XML message and then some time later receive an XML message from that Web service.

Figure 1-1 Workflow Invokes Web Service with XML and Later Receives XML from the Web Service

The workflow invokes the Web service with an XML document by passing in an XML message over SOAP-HTTP or HTTP-XML. The Web service then begins processing business logic. At some point during or after the processing, the Web service sends a message containing an XML document back to the workflow.

This scenario features an asynchronous Web service because the workflow is free to perform its processing after instantiating the Web service. The workflow can then later solicit the response from the Web service. Note that each instance of the Web service must send the XML result back to the workflow instance that invoked it.

Note: The Web service methods in the XML over HTTP sample are, strictly speaking, synchronous. This is due to a feature in WebLogic Workshop where the JWS methods that support XML-only bindings over HTTP do not support void return values. Subsequently, it is not possible to have asynchronous XML/HTTP only methods in a Workshop JWS. The sample handles this limitation by having the JWS return dummy integers as return values.

How the Scenario is Implemented

An intermediary Web service is employed to decouple the workflow from the protocol and message format of the target Web service, as shown in Figure 1-2.

Figure 1-2 Workflow Invokes a Web Service with XML and Later Receives XML from the Web Service

The intermediary Web service ensures that the reply XML received from the target Web service comes from the identical Web service instance that it invoked by sending the original XML message. The intermediary must also ensure that it conveys the XML result from the target Web service back to the exact workflow instance that passed it the original XML document.

The workflow requires a mechanism for transmitting its raw XML to the intermediary Web service and receiving an XML response from the intermediary Web service at a later time. Note that both of these XML transmissions must be guaranteed to take place between the same intermediary Web service instance and workflow instance. The intermediary Web service also frees up the workflows from having to support a SOAP/XML over HTTP interface. The workflows act as JMS producers and consumers leaving the Web services to handle the SOAP/XML message format translation.

How the Sample Demonstrates the Scenario

As previously mentioned, the sample demonstrates that a workflow can generate an XML document containing purchase order information. In the sample, the SendPO workflow uses an XML document to trigger the ProcessPO workflow. The ProcessPO workflow eventually returns a result XML document to the SendPO workflow after it completes processing the purchase order information.

Figure 1-3 shows the interoperability process for the SOAP over HTTP sample. Table 1-1 describes the process in detail.

Figure 1-4 shows the interoperability process for the XML over HTTP sample. Table 1-2 describes the process in detail.

Figure 1-3 Workflow - Workshop Interaction—SOAP

Note: Each step is described in Table 1-1.

As shown in Figure 1-3, the ProcessPO workflow is invoked by the SendPO workflow. The Process PO Web service is deployed as means of invoking the ProcessPO workflow and retrieving its response XML asynchronously. This allows the SendPO workflow to effectively act as a client of the Process PO Web service when it invokes the ProcessPO workflow and receives its result. For this to be feasible, the Process PO Web service must be reachable via HTTP from the WebLogic Integration instance that executes the SendPO workflow.

The Send PO Web service handles the details of invoking the Process PO Web service and receiving a result. When the Send PO Web service has the result XML, it conveys it to the SendPO workflow. The SendPO and ProcessPO workflows use the Send PO and Process PO Web services as a means of communicating XML documents to each other asynchronously over HTTP.

Table 1-1 SOAP Over HTTP Sample Scenario Steps

Step | Description
--- | ---
1 | The SendPO workflow posts the XML document containing the purchase order on the JMS queue dedicated for Web services (jws.queue). The XML document also includes the SendPO workflow instance ID. When the SendPO Web service returns a response (step 11), it assigns that instance ID to the JMS property WLPIInstanceIDs. This ensures the following: The SendPO workflow instance that sent the purchase order is the same workflow instance that receives the response. The response will be received even if the SendPO workflow event node Get PO Ack has not yet been activated by the time the response arrives.
2 | The Send PO Web service purchase method has a parameter that maps to the purchase order XML document. Additionally, this method handles the XML message that arrived on jws.queue. Note: The receive queue of a JMS control cannot be used to receive unsolicited messages. For more information, see the WebLogic Workshop online help—>Guide to Building JMS Control: Using Java Message Service Queues and Topics from Your Web Service—>Messaging Scenarios Not Supported by the JMS Control.
3 | The Send PO Web service sends the purchase order document to the Process PO Web service. The Send PO Web service uses a service control created using the Process PO jws file. The SendPO Web service and the Process PO Web service exchange SOAP formatted XML messages over HTTP. SOAP message exchanges allow the SendPO Web service and the Process PO Web service to reside on different machines, which allows remote communication between the SendPO workflow and the ProcessPO workflow. The SOAP message exchange between the Send PO Web service and the Process PO Web service is conversational, and to ensure request/response correlation between the two Web services, it carries the SOAP message conversation ID in the SOAP header. This sample can also run on a single machine.
4 | The Process PO Web service uses a JMS control to place the purchase order XML document on the BPM Event Queue, which is monitored by the ProcessPO workflow. The JMS message contains the SOAP conversation ID in its JMSCorrelationID header field to ensure that the JMS reply message returns to the Process PO Web service instance that sent the outgoing message.
5 | The ProcessPO workflow retrieves the XML message from the BPM Event Queue and begins processing.
6 | The ProcessPO assigns a task to a WLI Worklist user that requests the user to accept the purchase order.
7 | The user executes the task, accepting the purchase order.
8 | The ProcessPO workflow places a purchase order acknowledgement XML message on the BPM Response Queue. The acknowledgement message contains the SOAP message conversation ID in its header field JMSCorrelationID to ensure that only the intended instance of the Process PO Web service receives this message.
9 | The Process PO Web service has a JMS control that retrieves the purchase order acknowledgement XML message from the BPM Response Queue.
10 | The Process PO Web service invokes its callback method to forward the purchase order acknowledgement message to the SendPO Web service. As previously mentioned, either SOAP over HTTP is used for communication between the Web services.
11 | The callback for the service control uses a JMS control to place the purchase order acknowledgement XML message on the BPM Event Queue.
12 | The SendPO workflow retrieves the purchase order acknowledgement XML message from the BPM Event Queue. The Get PO Ack event node is triggered by the receipt of an addressed message containing the workflow instance ID of the Send PO Workflow in the message header. This ensures that the workflow instance that had sent out the purchase order document has its event node triggered on the receipt of an PO acknowledgement message.
13 | The SendPO workflow assigns a task to a WebLogic Integration Worklist user, which requests the user to accept the purchase order acknowledgment.
14 | The user executes the task, accepting the purchase order acknowledgement.

Figure 1-4 Workflow - Workshop Interaction—XML

Note: Each step is described in Table 1-2.

As shown in Figure 1-4, the ProcessPO workflow is invoked by the SendPO workflow. The Process PO Web service is deployed as means of invoking the ProcessPO workflow and retrieving its response XML asynchronously. This allows the SendPO workflow to effectively act as a client of the Process PO Web service when it invokes the ProcessPO workflow and receives its result. For this to be feasible, the Process PO Web service must be reachable via HTTP from the WebLogic Integration instance that executes the SendPO workflow.

The Send PO Web service handles the details of invoking the Process PO Web service and receiving a result. When the Send PO Web service has the result XML, it conveys it to the SendPO workflow. The SendPO and ProcessPO workflows use the Send PO and Process PO Web services as a means of communicating XML documents to each other asynchronously over HTTP.

Table 1-2 XML Over HTTP Sample Scenario Steps

Step | Description
--- | ---
1 | The SendPO workflow posts the XML document containing the purchase order on the JMS queue dedicated for Web services (jws.queue). The XML document also includes the SendPO workflow instance ID. When the SendPO Web service returns the PO Ack response (step 11), the message payload carries the Send PO workflow instance ID. The Send PO workflow instance's Get PO Ack event node looks for an event key containing the instance ID in the message payload. Note: Notice that this form of request response correlation is different from the SOAP sample, where the Send PO workflow's Get PO Ack event node is triggered by the receipt of an addressed message.
2 | The Send PO Web service sendXMLEvent method has a parameter that maps to the purchase order XML document. Additionally, this method handles the XML message that arrived on jws.queue. Note: The receive queue of a JMS control cannot be used to receive unsolicited messages. For more information, see the WebLogic Workshop online help—>Guide to Building JMS Control: Using Java Message Service Queues and Topics from Your Web Service—>Messaging Scenarios Not Supported by the JMS Control.
3 | The Send PO Web service sends the purchase order XML document to the Process PO Web service by calling the Process PO Web service's onXMLEvent method. The Send PO Web service uses a service control created using the Process PO Web service's jws file (WLW2BPM.jws). The Send PO Web service and the Process PO Web service exchange raw XML messages over HTTP. Note: Notice that this contrasts with the SOAP sample, where the two Web services communicated with each other using SOAP messages.
4 | The Process PO Web service uses a JMS control to place the purchase order XML document on the BPM Event Queue, which is monitored by the ProcessPO workflow. Note the message payload carries the instance ID of the Send PO workflow.
5 | The ProcessPO workflow retrieves the XML message from the BPM Event Queue and begins processing.
6 | The ProcessPO assigns a task to a WebLogic Integration Worklist user that requests the user to accept the purchase order.
7 | The user executes the task, accepting the purchase order.
8 | The ProcessPO workflow places a purchase order acknowledgement XML message on a Workshop JMS Queue (jws.queue). The message header carries the information identifying the Process PO Web service method (sendPOAck in WLW2BPM.jws) that will be invoked when the message is received on the JMS queue.
9 10 | The sendPOAck method in the Process PO Web service invokes the sendPOAck method of the Send PO Web service through the Service control defined for the Send PO Web service (BPM2WLWControl.ctrl). As previously mentioned, the message exchange between the Process PO Web service and the Send PO Web service is in raw XML format over HTTP.
11 | The Send PO Web service uses a JMS control to place the purchase order acknowledgement XML message on the BPM Event Queue. The acknowledgement message carries the instance ID of the Send PO workflow in the message payload.
12 | The SendPO workflow retrieves the purchase order acknowledgement XML message from the BPM Event Queue. The Get PO Ack event node uses an event key value expression to accept only the message that contains the workflow instance ID which is the same as its own.
13 | The SendPO workflow assigns a task to a WebLogic Integration Worklist user that requests the user to accept the purchase order acknowledgment.
14 | The user executes the task, accepting the purchase order acknowledgement.

Why Only One Instance of WebLogic Integration

The sample runs on one instance of WebLogic Integration. In actuality the SendPO workflow and Send PO Web service can be deployed on one instance and the Process PO Web service and ProcessPO workflow can be deployed on another instance, as long as the two instances can reach one another over HTTP.

So that the sample can be run a step at a time, the WebLogic Integration Swing Worklist client is used to get input from a user at two intervals during the sample. The Worklist interaction serves only to break the running of the sample into sections that the user can watch execute one at a time.