Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite
11g Release 1 (

Part Number E10224-15
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Feedback page
Contact Us

Go to previous page
Go to next page
PDF · Mobi · ePub

8 Invoking an Asynchronous Web Service from a BPEL Process

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:

8.1 Introduction to Invoking an Asynchronous Web Service

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

  1. An assign activity prepares the loan application.

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

  3. The loan processor web service then sends the correct response to the receive activity, which has been tracked by the correlation ID.

  4. An assign activity reads the loan application offer.

The remaining sections in this chapter provide specific details about the asynchronous functionality.

8.2 Invoking an Asynchronous Web Service

This section provides an overview of the tasks for adding asynchronous functionality to a BPEL process service component.

8.2.1 How to Invoke an Asynchronous Web Service

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 Adding a Partner Link for an Asynchronous Service

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.

To add a partner link for an asynchronous service:

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

  2. Follow the instructions in the dialog to create a BPEL process service component.

  3. Click OK when complete.

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

  5. In the Component Palette, expand BPEL Constructs.

  6. Drag a Partner Link icon into the right Partner Links swimlane.

    The Create Partner Link dialog appears.

  7. Enter the following details to create a partner link and select the loan application approver web service:

    • Name

      Enter a name for the partner link (for this example, LoanService is entered).

    • Process

      Displays the BPEL process service component name (for this example, LoanBroker appears).

    • WSDL URL

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

    • Partner Role

      Refers to the role of the external source, for example, provider. Select from the list (for this example, LoanServiceProvider is selected).

    • My Role

      Refers to the role of the BPEL process service component in this interaction. Select from the list (for this example, LoanServiceRequester is selected).

  8. Click OK.

    A new partner link for the loan application approver web service (United Loan) appears in the swimlane of the designer. Adding an Invoke Activity

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.

To add an invoke activity:

  1. In the Component Palette, expand BPEL Constructs.

  2. Drag an Invoke activity to beneath the Receive activity.

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

  4. Right-click Variables and select Expand All Child Nodes.

  5. In the second Variables folder in the tree, right-click and select Create Variable.

    The Create Variable dialog appears.

  6. Enter the variable name and select Message Type from the options provided:

    • Type

      This option lets you select an XML schema simple type (for example, string, boolean, and so on).

    • Message Type

      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.

    • Element

      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.

    Figure 8-1 Create Variable Dialog

    Description of Figure 8-1 follows
    Description of "Figure 8-1 Create Variable Dialog"

  7. Click OK.

  8. Double-click the invoke activity to display the Invoke dialog.

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

  10. 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, "Invoke and Receive Activities."

  11. Click OK. Adding a Receive Activity

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.

To add a receive activity:

  1. From the Component Palette, drag a Receive activity to the location right after the Invoke activity you created in Section, "Adding an Invoke Activity."

  2. Create a variable to hold the receive information by invoking the Create Variable dialog, as you did in Step 3 through Step 7 of Section, "Adding an Invoke Activity."

    Figure 8-2 shows the Create Variable dialog in BPEL 1.1.

    Figure 8-2 Create Variable Dialog

    Description of Figure 8-2 follows
    Description of "Figure 8-2 Create Variable Dialog"

    Not :

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

  3. Double-click the receive activity and change its name to receive_invoke.

  4. From the Partner Link list, select the partner link (for this example, LoanService is selected).

  5. From the Operation list, select onResult. Do not select the Create Instance checkbox.

  6. Select the variable you created in Step 3 through Step 7 of Section, "Adding an Invoke Activity."

  7. Click OK.

    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. Performing Additional Activities

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.

8.2.2 What Happens When You Invoke an Asynchronous Web Service

This section describes what happens when you invoke an asynchronous web service. portType Section of the WSDL File

The portType section of the WSDL file (in this example, for LoanService) defines the ports to be used for the asynchronous 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 portType LoanServiceCallback receives the client's loan application request and the portType LoanService asynchronously calls back the client with the loan offer response.

Example 8-1 portType Definition

<!-- portType implemented by the LoanService BPEL process -->
   <portType name="LoanService">
      <operation name="initiate">
         <input message="tns:LoanServiceRequestMessage"/>
<!-- portType implemented by the requester of LoanService BPEL process
for asynchronous callback purposes
   <portType name="LoanServiceCallback">
      <operation name="onResult">
         <input message="tns:LoanServiceResultMessage"/>
   </portType> partnerLinkType Section of the WSDL File

The 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

  • The portType provided for receiving messages within the conversation

Partner link types in asynchronous services have two roles: one for the web service provider and one for the client requester.

In the conversation shown in Example 8-2, the LoanServiceProvider role and LoanService portType are used for client request messages and the LoanServiceRequester role and LoanServiceCallback portType are used for asynchronously returning (calling back) response messages to the client.

Example 8-2 partnerLinkType Definition

<plnk:partnerLinkType name="LoanService">
        <plnk:role name="LoanServiceProvider">
            <plnk:portType name="client:LoanService"/>
        <plnk:role name="LoanServiceRequester">
            <plnk:portType name="client:LoanServiceCallback"/>

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 receive activity. Partner Links Section in the BPEL File

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

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.

Example 8-3 partnerLink Definition

<!-- This process invokes the asynchronous LoanService. -->

    <partnerLink name="LoanService"

The attribute myRole indicates the role of the client. The attribute partnerRole role indicates the role of the partner in this conversation. Each partnerLinkType has a myRole and partnerRole attribute in asynchronous processes. Composite Application File

In the composite.xml file, the loan application approver web service appears, as shown in Example 8-4.

Example 8-4 Loan Application Approver Web Service

<component name="LoanBroker">
    <implementation.bpel process="LoanBroker.bpel"/>

For more information, see Section, "Adding a Partner Link for an Asynchronous Service" for instructions on creating a partner link. Invoke and Receive Activities

View the variables and sequence sections. Two areas of particular interest concern the invoke and receive activities:

  • An 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.

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

  • A 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.

Example 8-5 Invoke and Receive Activities


    <variable name="request"
    <variable name="response"


    <!-- initialize the input of LoanService -->
    <!--  initiate the remote process -->
    <invoke name="invoke" partnerLink="LoanService"
        operation="initiate" inputVariable="request"/>

    <!--  receive the result of the remote process -->
    <receive name="receive_invoke" partnerLink="LoanService"
        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. createInstance Attribute for Starting a New 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 receive activity.

Example 8-6 shows the source code for the createInstance attribute:

Example 8-6 createInstance Attribute

<!-- receive input from requester -->
    <receive name="receiveInput" partnerLink="client"
             operation="initiate" variable="input"
             createInstance="yes"/> Dehydration Points for Maintaining Long-Running Asynchronous Processes

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." Multiple Runtime Endpoint Locations

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.

Example 8-7 Alternate Runtime Endpoint Location

<reference name="HeaderService ...>
< port="
<property name="endpointURI"> 

8.2.3 What You May Need to Know About Multiple Client Components Invoking a Composite

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.

8.2.4 What You May Need to Know About Limitations on BPEL 2.0 IMA Support

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 createInstance to 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 join.

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 yes

  • Process2 with receive2 followed by receive1, and only receive2 having createInstance set to yes.

The same also applies for any other combination of IMAs, such as a receive activity and pick activity, or two pick activities.

8.2.5 What Happens When You Specify a Conversation ID

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 bpelx:conversationId extension. bpelx:conversationId in BPEL 1.1

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-8 bpelx:conversationId Conversation ID in BPEL 1.1

<invoke ... bpelx:conversationId="$convId2">

<receive ... bpelx:conversationId="$convId2">

<onMessage... bpelx:conversationId="$convId2">
</onMessage> bpelx:conversationId in BPEL 2.0

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.

Example 8-9 bpelx:conversationId Conversation ID in BPEL 2.0

<invoke ...>

<receive ...>

<onMessage ...>

8.3 Creating a Dynamic Partner Link at Design Time for Use at Runtime

When you design a SOA composite application, you can face the following challenges:

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.

8.3.1 How To Create a Dynamic Partner Link at Design Time for Use at Runtime

To create a dynamic partner link at design time for use at runtime:

  1. Create a WSDL file that contains multiple services that use the same portType.

    <service name="AmericanLoan">
     <port name="LoanServicePort" binding="tns:LoanServiceBinding">
      <soap:address location="http://localhost:9700/orabpel/default/AmericanLoan"/>
    <service name="AlliedLoan">
     <port name="LoanServicePort" binding="tns:LoanServiceBinding">
      <soap:address location="http://localhost:9700/orabpel/default/AlliedLoan"/>
    <service name="AcmeLoan">
     <port name="LoanServicePort" binding="tns:LoanServiceBinding">
      <soap:address location="http://localhost:9700/orabpel/default/AcmeLoan"/>
  2. Drag a Web Service binding component into the External References swim lane of the SOA Composite Editor.

    The Create Web Service dialog appears.

  3. 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=""
        < port=


    • Adding the 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 location attribute.

  4. Double-click the BPEL process to enter Oracle BPEL Designer.

  5. Drag an Assign activity into the designer.

  6. Click the Copy Rules tab.

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

    Figure 8-3 XML Fragment Icon

    Description of Figure 8-3 follows
    Description of "Figure 8-3 XML Fragment Icon"

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

  9. Assign an XML fragment containing the endpoint reference to the partner link, and click OK. Figure 8-4 provides details.

    Figure 8-4 XML Fragment Dialog in BPEL 1.1

    Description of Figure 8-4 follows
    Description of "Figure 8-4 XML Fragment Dialog in BPEL 1.1"

    When complete, the BPEL file contains one of the services defined in the WSDL.

       <to partnerLink="LoanService"/>

8.4 Using WS-Addressing in an Asynchronous Service

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 Callback with WS-Addressing Headers

Description of Figure 8-5 follows
Description of "Figure 8-5 Callback with WS-Addressing Headers"

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, "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:

8.4.1 How to Use WS-Addressing in an Asynchronous Service

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 .bpel and .wsdl files to use WS-Addressing. Using TCP Tunneling to See Messages Exchanged Between Programs

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. Setting Up a TCP Listener for Synchronous Services

Follow these steps to set up a TCP listener for synchronous services initiated by an Oracle BPEL Process Manager process:

  1. Visit the following URL for instructions on how to download and install Axis TCP Monitor (tcpmon)
  2. Visit the following URL for instructions on how to use tcpmon:
  3. Place axis.jar in your class path.

  4. Start tcpmon:

    C:\...\> java org.apache.axis.utils.tcpmon localport remoteHost
  5. In the composite.xml file, add the endpointURI property under for your flow to override the endpoint of the service.

  6. From the operating system command prompt, compile and deploy the process with ant.

    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. Setting Up a TCP Listener for Asynchronous Services

Follow these steps to set up a TCP listener to display the SOAP messages for callbacks from asynchronous services:

  1. Start a TCP listener to listen on a port and to send the Oracle BPEL Process Manager port.

    1. Open Oracle Enterprise Manager Fusion Middleware Control.

    2. From the SOA Infrastructure menu, select SOA Administration > Common Properties.

    3. Specify the value for Callback Server URL. This URL is sent by the server as part of the asynchronous callback address to the invoker.

  2. From the SOA Infrastructure menu, select Administration > System MBean Browser.

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

  4. Follow these steps to set this property on a composite application. This action enables it to apply to all bindings in the composite application.

    1. Click your composite.

    2. Ensure the Attributes tab is selected.

    3. In the Name column, click Properties.

    4. Click the Add icon.

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

    6. In the name field, enter oracle.webservices.local.optimization.

    7. In the value field, enter false.

    8. In the many field, enter false.

    9. Click Apply, and then click Return.

    10. In the Name column on the Operations tab, click save.

    11. Click Invoke to execute the operation.

    12. Click Return or click a node in the System MBean Browser pane.


      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.

  5. Follow these steps to set this property on a specific binding.

    1. Expand your composite application. and drill down to the specific SCAComposite.SCAReference.SCABinding folder.

    2. Click WSBinding.

    3. Perform steps 4b through 4l.

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