This chapter describes how to invoke an asynchronous web service from a BPEL process. It demonstrates how to set up the components necessary to perform an asynchronous invocation and how these components are coded. It also describes how to create a dynamic partner link at runtime and use WS-Addressing.
This chapter includes the following sections:
Asynchronous messaging styles are useful for environments in which a service, such as a loan processor, can take a long time to process a client request. Asynchronous services also provide a more reliable fault-tolerant and scalable architecture than synchronous services.
This section introduces asynchronous web service invocation with a company called United Loan. United Loan publishes an asynchronous web service that processes a client's loan application request and then returns a loan offer. This use case discusses how to integrate a BPEL process service component with this asynchronous loan application approver web service.
This use case illustrates the key design concepts for requesting information from an asynchronous service, and then receiving the response. The asynchronous United Loan service in this example is another BPEL process service component. However, the same BPEL call can interact with any properly designed web service. The target web service WSDL file contains the information necessary to request and receive the necessary information.
For the asynchronous web service, the following actions take place (in order of priority):
An assign activity prepares the loan application.
An invoke activity initiates the loan request. The contents of this request are put into a request variable. This request variable is sent to the asynchronous loan processor web service.
When the loan request is initiated, a correlation ID unique to the client and partner link initiating the request is also sent to the loan processor web service. The correlation ID ensures that the correct loan offer response is returned to the corresponding loan application requester.
The loan processor web service then sends the correct response to the receive activity, which has been tracked by the correlation ID.
An assign activity reads the loan application offer.
The remaining sections in this chapter provide specific details about the asynchronous functionality.
You perform the following steps to asynchronously invoke a web service:
Add a partner link
Add an invoke activity
Add a receive activity
Create assign activities
These instructions describe how to create a partner link in a BPEL process (for this example, named LoanService) for the loan application approver web service.
In the SOA Composite Editor, drag a BPEL process from the Service Components section of the Component Palette into the designer.
The Create BPEL Process dialog appears.
Follow the instructions in the dialog to create a BPEL process service component.
Click OK when complete.
In the SOA composite application in the SOA Composite Editor, double-click the BPEL process service component (for this example, the component is named LoanBroker).
The Oracle BPEL Designer appears.
In the Component Palette, expand BPEL Constructs.
Drag a Partner Link icon into the right Partner Links swimlane.
The Create Partner Link dialog appears.
Enter the following details to create a partner link and select the loan application approver web service:
Enter a name for the partner link (for this example,
LoanService is entered).
Displays the BPEL process service component name (for this example,
Enter the name of the Web Services Description Language (WSDL) file to use. Click the SOA Resource Lookup icon above this field to locate the correct WSDL.
Partner Link Type
Refers to the external service with which the BPEL process service component is to interface. Select from the list (for this example,
LoanService is selected).
Refers to the role of the external source, for example, provider. Select from the list (for this example,
LoanServiceProvider is selected).
Refers to the role of the BPEL process service component in this interaction. Select from the list (for this example,
LoanServiceRequester is selected).
A new partner link for the loan application approver web service (United Loan) appears in the swimlane of the designer.
Follow these instructions to create an invoke activity and a global input variable named
request. This activity initiates the asynchronous BPEL process service component activity with the loan application approver web service (United Loan). The loan application approver web service uses the
request input variable to receive the loan request from the client.
In the Component Palette, expand BPEL Constructs.
Drag an Invoke activity to beneath the Receive activity.
Go to the Structure window. While this example describes variable creation from the Structure window, you can also create variables by clicking the Add icons to the right of the Input and Output fields of the Invoke dialog.
Right-click Variables and select Expand All Child Nodes.
In the second Variables folder in the tree, right-click and select Create Variable.
The Create Variable dialog appears.
This option lets you select an XML schema simple type (for example, string, boolean, and so on).
This option enables you to select a WSDL message file definition of a partner link or of the project WSDL file of the current BPEL process service component (for example, a response message or a request message). You can specify variables associated with message types as input or output variables for invoke, receive, or reply activities.
To display the message type, select the Message Type option, and then select its Browse icon to display the Type Chooser dialog. From here, expand the Message Types tree to make your selection. For this example, Message Types > Partner Links > Loan Service > LoanService.wsdl > Message Types > LoanServiceRequestMessage is selected.
This option lets you select an XML schema element of the project schema file or project WSDL file of the current BPEL process service component, or of a partner link.
Figure 8-1 shows the Create Variable dialog.
Double-click the invoke activity to display the Invoke dialog.
In the Invoke dialog, select the partner link from the Partner Link list (for this example, LoanService is selected) and initiate from the Operation list.
To the right of the Input field, click the second icon and select the input variable you created in Step 6.
The Variable Chooser dialog appears, where you can select the variable.
There is no output variable specified because the output variable is returned in the receive operation. The invoke activity is created.
For more information about the invoke activity, see Section 220.127.116.11, "Invoke and Receive Activities."
Follow these steps to create a receive activity and a global output variable named
response. This activity waits for the loan application approver web service's callback operation. The loan application approver web service uses this output variable to send the loan offer result to the client.
From the Component Palette, drag a Receive activity to the location right after the Invoke activity you created in Section 18.104.22.168, "Adding an Invoke Activity."
Figure 8-2 shows the Create Variable dialog in BPEL 1.1.
In BPEL projects that support version 2.0 of the BPEL specification, the Create Variable dialog includes an Initialize tab that enables you to initialize the variable type inline (for example, as a variable, expression, literal, partner link, or property). For more information, see Section 6.5.2, "Initializing Variables with an Inline from-spec in BPEL 2.0."
Double-click the receive activity and change its name to
From the Partner Link list, select the partner link (for this example, LoanService is selected).
From the Operation list, select onResult. Do not select the Create Instance checkbox.
The receive activity and the output variable are created. Because the initial receive activity in the BPEL file (for this example, LoanBroker.bpel) created the initial BPEL process service component instance, a second instance does not need to be created.
In addition to the asynchronous-specific tasks, you must perform the following tasks.
Create an initial assign activity for data manipulation in front of the invoke activity that copies the client's input variable loan application request document payload into the loan application approver web service's request variable payload.
Create a second assign activity for data manipulation after the receive activity that copies the loan application approver web service's response variable loan application results payload into the output variable for the client to receive.
This section describes what happens when you invoke an asynchronous web service.
Asynchronous services have two port types. Each port type performs a one-way operation. In this example, one port type responds to the asynchronous process and the other calls back the client with the asynchronous response. In the example shown in Example 8-1, the
LoanServiceCallback receives the client's loan application request and the
LoanService asynchronously calls back the client with the loan offer response.
<!-- portType implemented by the LoanService BPEL process --> <portType name="LoanService"> <operation name="initiate"> <input message="tns:LoanServiceRequestMessage"/> </operation> </portType> <!-- portType implemented by the requester of LoanService BPEL process for asynchronous callback purposes --> <portType name="LoanServiceCallback"> <operation name="onResult"> <input message="tns:LoanServiceResultMessage"/> </operation> </portType>
partnerLinkType section of the WSDL file (in this example, for
LoanService) defines the following characteristics of the BPEL process service component:
The role (operation) played
portType provided for receiving messages within the conversation
In the conversation shown in Example 8-2, the
LoanServiceProvider role and
portType are used for client request messages and the
LoanServiceRequester role and
portType are used for asynchronously returning (calling back) response messages to the client.
<plnk:partnerLinkType name="LoanService"> <plnk:role name="LoanServiceProvider"> <plnk:portType name="client:LoanService"/> </plnk:role> <plnk:role name="LoanServiceRequester"> <plnk:portType name="client:LoanServiceCallback"/> </plnk:role> </plnk:partnerLinkType>
Two port types are combined into this single asynchronous BPEL process service component:
portType="services:LoanService" of the
invoke activity and
portType="services:LoanServiceCallback" of the
receive activity. Port types are essentially a collection of operations to be performed. For this BPEL process service component, there are two operations to perform:
initiate in the
invoke activity and
onResult in the
To call the service from BPEL, you use the BPEL file to define how the process interfaces with the web service. View the
partnerLinks section. The services with which a process interacts are designed as partner links. Each partner link is characterized by a
Each partner link is named. This name is used for all service interactions through that partner link. This is critical in correlating responses to different partner links for simultaneous requests of the same type.
Asynchronous processes use a second partner link for the callback to the client. In this example, the second partner link,
LoanService, is used by the loan application approver web service. Example 8-3 provides an example.
<!-- This process invokes the asynchronous LoanService. --> <partnerLink name="LoanService" partnerLinkType="services:LoanService" myRole="LoanServiceRequester" partnerRole="LoanServiceProvider"/> </partnerLinks>
myRole indicates the role of the client. The attribute
partnerRole role indicates the role of the partner in this conversation. Each
partnerLinkType has a
partnerRole attribute in asynchronous processes.
composite.xml file, the loan application approver web service appears, as shown in Example 8-4.
<component name="LoanBroker"> <implementation.bpel process="LoanBroker.bpel"/> </component>
For more information, see Section 22.214.171.124, "Adding a Partner Link for an Asynchronous Service" for instructions on creating a partner link.
invoke activity invokes a synchronous web service (as discussed in Chapter 7, "Invoking a Synchronous Web Service from a BPEL Process") or initiates an asynchronous service.
invoke activity includes the
request global input variable defined in the
variables section. The
request global input variable is used by the loan application approver web service. This variable contains the contents of the initial loan application request document.
receive activity that waits for the asynchronous callback from the loan application approver web service. The
receive activity includes the
response global output variable defined in the
variables section. This variable contains the loan offer response. The
receive activity asynchronously waits for a callback message from a service. While the BPEL process service component is waiting, it is dehydrated, or compressed and stored, until the callback message arrives.
Example 8-5 provides an example.
<variables> <variable name="request" messageType="services:LoanServiceRequestMessage"/> <variable name="response" messageType="services:LoanServiceResultMessage"/> </variables> <sequence> <!-- initialize the input of LoanService --> <assign> <!-- initiate the remote process --> <invoke name="invoke" partnerLink="LoanService" portType="services:LoanService" operation="initiate" inputVariable="request"/> <!-- receive the result of the remote process --> <receive name="receive_invoke" partnerLink="LoanService" portType="services:LoanServiceCallback" operation="onResult" variable="response"/>
When an asynchronous service is initiated with the
invoke activity, a correlation ID unique to the client request is also sent, using Web Services Addressing (WS-Addressing) (described in Section 8.4, "Using WS-Addressing in an Asynchronous Service"). Because multiple processes may be waiting for service callbacks, the server must know which BPEL process service component instance is waiting for a callback message from the loan application approver web service. The correlation ID enables the server to correlate the response with the appropriate requesting instance.
You may notice a
createInstance attribute in the initial
receive activity. In this initial
receive activity, the
createInstance element is set to
yes. This starts a new instance of the BPEL process service component. At least one instance startup is required for a conversation. For this reason, you set the
createInstance variable to
no in the second
Example 8-6 shows the source code for the
To automatically maintain long-running asynchronous processes and their current state information in a database while they wait for asynchronous callbacks, you use a database as a dehydration store. Storing the process in a database preserves the process and prevents any loss of state or reliability if a system shuts down or a network problem occurs. This feature increases both BPEL process service component reliability and scalability. You can also use it to support clustering and failover.
You insert this point between the invoke activity and receive activity. You can also explicitly specify a dehydration point with a dehydrate activity. For more information, see Section A.2.9, "Dehydrate Activity."
Oracle SOA Suite provides support for specifying multiple partner link endpoint locations. This capability is useful for failover purposes if the first endpoint is down. To provide an alternate partner link endpoint location, add the
location attribute to the
composite.xml file. Example 8-7 provides an example.
<reference name="HeaderService ...> <binding.ws port="http://services.otn.com/HelloWorldApp#wsdl.endpoint(client/ HelloWorldService_pt)" location="http://server:port/soa-infra/services/default/ HelloWorldService!1.0/client?WSDL"> <property name="endpointURI">http://jsmith.us.oracle.com:80/a.jsp @http://myhost.us.oracle.com:8888/soa-infra/services/HelloWorldApp/HelloWorld! 1.0*2007-10-22_14-33-04_195/client </property> </binding.ws> </reference>
If multiple client components invoke a SOA composite application by using its remote WSDL file, the callback response can only be retrieved by the original client calling the remote composite if it has a receive activity. When the original client does not have a receive activity and any of the subsequent clients calling the composite has a receive activity, the response message is lost. It goes into the recovery state of the original client process.
This is the expected behavior. This is because the composite being invoked cannot tell which client has a receive activity or if the client is indeed a BPEL process service component.
Receive activities are a type of inbound message activity (IMA). Other examples of IMAs are as follows:
onMessage branches of a scope activity (in BPEL 1.1) or a pick activity
onEvent branches of a scope activity in BPEL 2.0
The BPEL 2.0 specification allows multiple IMAs to work with each other or with other IMAs derived from extension activities. To provide for consistent runtime behavior, the BPEL 2.0 specification allows for correlation sets with the
initiate attribute set to
join.However, Oracle BPEL Process Manager's implementation of the BPEL 2.0 specification does not support this behavior. The only way to support multiple IMAs is by coding them as onMessage branches for a pick activity (that is, setting
yes).Oracle BPEL Process Manager also does not support other forms of multiple IMAs, such as a flow activity with two branches, each with a receive activity and with
createInstance set to
yes and correlation sets with
initiate set to
As a workaround, you must design two different BPEL processes with the two receive activities in alternating order, as follows:
Process1 with receive1 followed by receive2, and only receive1 having
createInstance set to
Process2 with receive2 followed by receive1, and only receive2 having
createInstance set to
The same also applies for any other combination of IMAs, such as a receive activity and pick activity, or two pick activities.
You can also enter an optional conversation ID value in the Conversation ID field of an invoke activity (and other activities such as a receive activity and the onMessage branch of a pick or scope activity).
The conversation ID identifies a process instance during an asynchronous conversation. By default, the BPEL process service engine generates a unique ID for each conversation (which can span multiple invoke and receive activities), as specified by WSA addressing. If you want, you can specify your own value for the service engine to use. Conversation IDs are implemented with the
Example 8-8 provides an example of the
bpelx:conversationId extension in a BPEL project that supports BPEL version 1.1. The
bpelx:conversationId extension takes an XPath expression.
Example 8-9 provides an example of the
bpelx:conversationId extension in a BPEL project that supports BPEL version 2.0. The
bpelx:conversationId extension takes a BPEL 2.0 XPath expression.
When you design a SOA composite application, you can face the following challenges:
Service endpoints (addresses) may not be known at design time.
Endpoint references may need to change while the application is running.
The dynamic partner link feature enables you to dynamically assign an endpoint reference to a partner link for use at runtime in BPEL versions 1.1 and 2.0. The dynamic partner link provides conditions, similar to a switch activity, that are evaluated at runtime.
Create a WSDL file that contains multiple services that use the same
<service name="AmericanLoan"> <port name="LoanServicePort" binding="tns:LoanServiceBinding"> <soap:address location="http://localhost:9700/orabpel/default/AmericanLoan"/> </port> </service> <service name="AlliedLoan"> <port name="LoanServicePort" binding="tns:LoanServiceBinding"> <soap:address location="http://localhost:9700/orabpel/default/AlliedLoan"/> </port> </service> <service name="AcmeLoan"> <port name="LoanServicePort" binding="tns:LoanServiceBinding"> <soap:address location="http://localhost:9700/orabpel/default/AcmeLoan"/> </port> </service>
Drag a Web Service binding component into the External References swim lane of the SOA Composite Editor.
The Create Web Service dialog appears.
Define the web service, and click OK.
When complete, the reference binding component entry in the
composite.xml file that uses the WSDL looks as follows:
<reference name="loanService"> <interface.wsdl interface="http://services.otn.com#wsdl.interface(LoanService)" callbackInterface="http://services.otn.com#wsdl.interface(LoanServiceCallback)" /> <binding.ws port= "http://services.otn.com#wsdl.endpoint(AmericanLoan/LoanService_pt)"/> </reference>
binding.ws port setting is optional. This is because the port is overridden at runtime by properties passed from Oracle BPEL Process Manager.
If there is no
port setting, and there is no composite import of the concrete WSDL associated with this reference, you must specify the location of the concrete WSDL with a
Double-click the BPEL process to enter Oracle BPEL Designer.
Drag an Assign activity into the designer.
Click the Copy Rules tab.
Above the target partner link, select the XML Fragment icon, as shown in Figure 8-3. If you are using BPEL 2.0, drag the Literal icon.
Drag the XML Fragment icon to the target partner link.
The XML Fragment dialog for BPEL 1.1 appears. If you are using BPEL 2.0, the Literal dialog appears.
Assign an XML fragment containing the endpoint reference to the partner link, and click OK. Figure 8-4 provides details.
When complete, the BPEL file contains one of the services defined in the WSDL.
<copy> <from> <EndpointReference xmlns="http://schemas.xmlsoap.org/ws/2003/03/addressing"> <Address>http://myhost.us.oracle.com:9700/orabpel/default/AlliedLoan</Address> </EndpointReference> </from> <to partnerLink="LoanService"/> </copy>
Because there can be many active instances at any time, the server must be able to direct web service responses to the correct BPEL process service component instance. You can use WS-Addressing to identify asynchronous messages to ensure that asynchronous callbacks locate the appropriate client.
Figure 8-5 provides an overview of WS-Addressing. WS-Addressing uses Simple Object Access Protocol (SOAP) headers for asynchronous message correlation. Messages are independent of the transport or application used.
Figure 8-5 shows how messages are passed along with WS headers so that the response can be sent to the correct destination.
The example in this chapter uses WS-Addressing for correlation. To view the messages, you can use TCP tunneling, which is described in Section 126.96.36.199, "Using TCP Tunneling to See Messages Exchanged Between Programs."
WS-Addressing defines the following information typically provided by transport protocols and messaging systems. This information is processed independently of the transport or application:
Endpoint location (reply-to address)
The reply-to address specifies the location at which a BPEL client is listening for a callback message.
Use TCP tunneling to view SOAP messages exchanged between the BPEL process service component flow and the web service (including those containing the correlation ID). You can see the exact SOAP messages that are sent to, or received from, services with which a BPEL process service component flow communicates.
You insert a software listener between your BPEL process service component flow and the web service. Your BPEL process service component flow communicates with the listener (called a TCP tunnel). The listener forwards your messages to the web service, and also displays them. Responses from the web service are returned to the tunnel, which displays and forwards them back to the BPEL process service component.
WS-Addressing is a public specification and is the default correlation method supported by Oracle BPEL Process Manager. You do not need to edit the
.wsdl files to use WS-Addressing.
The messages that are exchanged between programs and services can be seen through TCP tunneling. This is particularly useful when you want to see the exact SOAP messages exchanged between the BPEL process service component flow and web services.
To monitor the SOAP messages, insert a software listener between your flow and the service. Your flow communicates with the listener (called a TCP tunnel) and the listener forwards your messages to the service, and displays them. Likewise, responses from the service are returned to the tunnel, which displays them and then forwards them back to the flow.
To see all the messages exchanged between the server and a web service, you need only a single TCP tunnel for synchronous services because all the pertinent messages are communicated in a single request and reply interaction with the service. For asynchronous services, you must set up two tunnels, one for the invocation of the service and another for the callback port of the flow.
Visit the following URL for instructions on how to download and install Axis TCP Monitor (
Visit the following URL for instructions on how to use
axis.jar in your class path.
C:\...\> java org.apache.axis.utils.tcpmon localport remoteHost port_on_which_remote_server_is_running
composite.xml file, add the
endpointURI property under
binding.ws for your flow to override the endpoint of the service.
From the operating system command prompt, compile and deploy the process with
The same technique can see SOAP messages passed to invoke a BPEL process service component as a web service from another tool kit such as Axis or .NET.
Start a TCP listener to listen on a port and to send the Oracle BPEL Process Manager port.
Open Oracle Enterprise Manager Fusion Middleware Control.
From the SOA Infrastructure menu, select SOA Administration > Common Properties.
Specify the value for Callback Server URL. This URL is sent by the server as part of the asynchronous callback address to the invoker.
From the SOA Infrastructure menu, select Administration > System MBean Browser.
Expand Application Defined MBeans > oracle.soa.config > Server : soa_server > SCAComposite.
where soa_server is the specific server instance name (for example, AdminServer).
All the SOA composite applications deployed on the server appear.
Click your composite.
In the Name column, click Properties.
Click the Add icon.
Expand the newly added Element_number (appears at the end of the list).
where number is the next sequential number beyond the last property. For example, if the property list contains twelve elements, adding a new property causes Element_13 to be displayed.
In the name field, enter
In the value field, enter
In the many field, enter
Click Apply, and then click Return.
Click Invoke to execute the operation.
After adding, deleting, or updating a property, you can click the Refresh cached tree data icon in the upper right corner of the System MBean Browser page to see the new data.
Initiate any flow that invokes asynchronous web services. You can combine this with the synchronous TCP tunneling configuration to send a service initiation request through your first TCP tunnel.
The callbacks from the asynchronous services are shown in the TCP listener.
If you are an Oracle JDeveloper user, you can also use the built-in Packet Monitor to see SOAP messages for both synchronous and asynchronous services.