6 Invoking an Asynchronous Web Service

6.2.1 partnerLinkTypes for Asynchronous Services

The following sections in the Web service's LoanService.wsdl file enable it to work with BPEL processes:

• portType Section of the LoanService.wsdl File

• partnerLinkType Section of the LoanService.wsdl File

portType Section of the LoanService.wsdl File

The portType section of the LoanService.wsdl file defines the ports to be used for the asynchronous service.

Asynchronous services have two port types. Each port type performs a one-way operation: one port type initiates the asynchronous process and the other calls back the client with the asynchronous response. In this example, the portType LoanService receives the client's loan application request and the portType LoanServiceCallback 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 LoanService.wsdl File

The partnerLinkType section of the LoanService.wsdl file defines the following characteristics of the conversation between the BPEL process and the loan application approver Web service:

• The role (operation) played by each

• The portType provided by each for receiving messages within the context of the conversation

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

In this conversation, 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.

<!-- the LoanService partnerLinkType binds the service and
         requestor portType into an asynchronous conversation.
         -->
    <plnk:partnerLinkType name="LoanService">
        <plnk:role name="LoanServiceProvider">
            <plnk:portType name="tns:LoanService"/>
        </plnk:role>
        <plnk:role name="LoanServiceRequester">
            <plnk:portType name="tns:LoanServiceCallback"/>
        </plnk:role>
    </plnk:partnerLinkType>

Two port types are combined into this single asynchronous BPEL process: 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, there are two operations to perform: initiate in the invoke activity and onResult in the receive activity.

6.2.2 Calling the Service from BPEL

To call the service from BPEL, you need the following files to define how the process interfaces with the Web service:

• Partner Links Section in the .bpel File

• Deployment Descriptor File

Partner Links Section in the .bpel File

View the partnerLinks section of the LoanBroker.bpel file. 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.

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

    <partnerLink name="LoanService"
             partnerLinkType="services:LoanService"
             myRole="LoanServiceRequester"
             partnerRole="LoanServiceProvider"/>
  </partnerLinks>

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.

Deployment Descriptor File

Open the bpel.xml deployment descriptor file of samples\tutorials\105.AsyncCompositeLoanBroker. The loan application approver Web service appears. This properties id information is added to the file when you create a second partner link type.

<?xml version="1.0"?>
<bpel-process id="LoanBroker" src="LoanBroker.bpel"
 wsdlLocation="LoanBroker.wsdl">
   <properties id="LoanService">
      <property name="wsdlLocation">
 http://hslattertest-pc:9700/orabpel/default/UnitedLoan/UnitedLoan?wsdl</property>
   </properties>

6.2.3 How the Invoke and Receive Activities Work

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

• An invoke activity invokes a synchronous Web service (as discussed in Chapter 5, "Invoking a Synchronous Web Service") 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 is waiting, it is dehydrated, or compressed and stored, until the callback message arrives.

  <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 WS-Addressing (described in "WS-Addressing"). Because multiple processes may be waiting for service callbacks, Oracle BPEL Server must know which BPEL process instance is waiting for a callback message from the loan application approver Web service. The correlation ID enables Oracle BPEL Server to correlate the response with the appropriate requesting instance.

Using the createInstance Attribute to Start a New Instance

You may have noticed a createInstance attribute in the initial receive activity of the sequence section of the LoanBroker.bpel file. In this initial receive activity, the createInstance element is set to yes. This starts a new instance of the BPEL process. 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.

The source code for the createInstance attribute appears as follows:

    <!-- receive input from requestor -->
    <receive name="receiveInput" partnerLink="client"
             portType="tns:LoanBroker"
             operation="initiate" variable="input"
             createInstance="yes"/>

6.2.4 Managing Multiple Active BPEL Process Instances Using Correlation Methods

Because there can be many active instances at any given point in time, Oracle BPEL Server must be able to direct Web service responses to the correct BPEL process instance. You can use the following correlation methods to identify asynchronous messages to ensure that asynchronous callbacks locate the appropriate client:

• WS-Addressing

• Using Correlation Sets to Coordinate Asynchronous Message Body Contents

6.2.4.1 WS-Addressing

Web Services Addressing (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. WS-Addressing uses simple object access protocol (SOAP) headers for asynchronous message correlation. Messages are independent of the transport or application used. provides an overview.

Figure 6-2 Callback with WS-Addressing Headers

Description of "Figure 6-2 Callback with WS-Addressing Headers"

Figure 6-2 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 "Using TCP Tunnelling 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.

• Conversation ID: Use TCP tunneling to view SOAP messages exchanged between the BPEL process 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 flow communicates.

  You insert a software listener between your BPEL process flow and the Web service. Your BPEL process 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.

Using TCP Tunnelling 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 with Web services and BPEL processes when you want to see the exact SOAP messages exchanged between the flow and Web services.

To monitor the SOAP messages, insert a software listener in 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, as well as displaying 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 Oracle BPEL 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/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.

If you are a JDeveloper BPEL Designer user, you can also use the built-in Packet Monitor to see SOAP messages for both synchronous and asynchronous services.

See Also: The following documentation, which is accessible from http://www.oracle.com/technology/bpel: Web Services Addressing (WS-Addressing) Specification for complete details about WS-Addressing BPEL-TN001: TCP Tunneling the Oracle BPEL Process Manager for instructions on using TCP tunneling to view SOAP messages

6.2.5 Using the Reply Activity to Send Messages in Response to a Receive Activity

The reply activity enables the business process to send a message in reply to a message that was received through a receive activity. The combination of a receive and a reply forms a request-response operation on the WSDL portType for the process.

  <reply partnerLink="ncname" portType="qname" operation="ncname"
         variable="ncname"? faultName="qname"?
         standard-attributes>
    standard-elements
    <correlations>?
       <correlation set="ncname" initiate="yes|no"?>+
    </correlations>
  </reply>

6.2.6 Using Dehydration Points to Maintain 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 can create a dehydration point. 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 reliability and scalability. You can also use it to support clustering and failover.

You insert this point between the invoke activity and receive activity. Figure 6-1 shows an example of a dehydration point in the loan application approver Web service.

6.3.1 Step 1: Adding a Partner Link for an Asynchronous Service

These instructions describe how to create a partner link named LoanService for the loan application approver Web service.

1. Double-click LoanBroker.bpel in the Applications Navigator.

2. In the diagram view, right-click either side of the BPEL process (under Partner Links).

3. Select Create Partner Link from the menu.

   The Create Partner Link window appears.

4. Enter the following details to create a second partner type and select the loan application approver Web service:

   • Name: Enter a name for the partner link.

   • WSDL File: Enter the name of the WSDL file to use. Click the Browse WSDL Files from Local File System or WSIL Browser icon above this field to locate the correct WSDL.

   • Partner Link Type: Refers to the external service with which the BPEL process is to interface. Select from the list.

   • My Role: Refers to role of the BPEL process in this interaction, for example, requester. Select from the list.

   • Partner Role: Refers to the role of the external source, for example, provider. Select from the list.

     
     Description of the illustration async1.gif
     
     

5. Click OK.

   A new partner link for the loan application approver Web service (United Loan) appears in the Partner Links area of the .bpel file's diagram view.

   
   

   See Also: "partnerLinkTypes for Asynchronous Services" for conceptual details about partner links "PartnerLink Activity"

   
   

6.3.2 Step 2: Adding an Invoke Activity

Follow these instructions to create an invoke activity and a global input variable named request. This activity initiates asynchronous BPEL process 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.

1. Drag an invoke activity from the Component Palette to beneath the receive activity.

   
   Description of the illustration async3.gif
   
   

2. In the .bpel file's diagram view, right-click either side of the BPEL process and select Variables from the menu.

   The Variables window appears.

3. Select Variables and right-click, then select Create Variable.

   
   Description of the illustration async5.gif
   
   

   The Create Variable dialog box appears.

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

   • Simple 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 (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 flashlight icon to display the Type Chooser window. From here, expand the Message Types navigation window to select Message Types, then Partner Links, then Loan Service, then United Loan, then Message Types, then LoanServiceRequest Message.

   • Element: This option lets you select an XML schema element of the project schema file or project WSDL file of the current BPEL process, or of a partner link.

   
   Description of the illustration async6.gif
   
   

5. Click OK, then click Close.

6. Double-click the invoke activity to display the Invoke window.

7. In the Invoke window, select the LoanService partner link from the Partner Link list and initiate from the Operation list.

8. Select the input variable you created in Step 4, by clicking the second icon to the right of the Variable field.

   The Variable Chooser window 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 and the global input variable are created.

   
   

   See Also: "How the Invoke and Receive Activities Work" for conceptual details about the invoke activity "Invoke Activity"

   
   

9. Click OK.

6.3.3 Step 3: 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.

1. From the Component Palette, drag a receive activity to the location right after the invoke activity you created in "Step 2: Adding an Invoke Activity".

2. Create a variable to hold the receive information by invoking the Create Variable window, as you did in Step 2 through Step 5, starting.

   
   Description of the illustration createglobvar2.gif
   
   

3. Double-click the receive activity and in the Receive window, change its name to receive_invoke.

4. Select LoanService from the Partner Link list and onResult from the Operation list. Do not select the Create Instance check box.

5. Select the variable you created in Step 2 through Step 5, starting.

6. Click OK.

   The receive activity and the output variable are created. Because the initial receive activity in the LoanBroker.bpel file created the initial BPEL process instance, a second instance does not need to be created.

   
   

   See Also: "Receive Activity"

   
   

6.3.4 Step 4: 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.

6.4.1 Step 1: Creating a Project

1. Right-click your workspace in the Applications Navigator section of the designer window.

2. Select New Project.

3. Double-click BPEL Process Project in the Items window to display the BPEL Process Project window.

4. Enter an appropriate name in the BPEL Process Name field (for this example, MyCorrelationSet is used).

5. Select Asynchronous BPEL Process from the Template list.

6. Click OK.

6.4.2 Step 2: Configuring Partner Links and File Adapter Services

You now create three partner links that use the adapter services.

This section contains these topics:

• Creating an Initial Partner Link and File Adapter Service

  You create an initial partner link with an adapter service for reading a loan application.

• Creating a Second Partner Link and File Adapter Service

  You create a second partner link with an adapter service for reading an application response.

• Creating a Third Partner Link and File Adapter Service

  You create a third partner link with an adapter service for reading a customer response.

6.4.3 Step 3: Creating Three Receive Activities

You now create three receive activities; one for each partner link. The receive activities specify the partner link from which to receive information.

This section contains the following topics:

• Creating an Initial Receive Activity

• Creating a Second Receive Activity

• Creating a Third Receive Activity

6.4.4 Step 4: Creating Correlation Sets

You now create correlation sets. A set of correlation tokens is a set of properties shared by all messages in the correlated group.

This section contains the following topics:

• Creating an Initial Correlation Set

• Creating a Second Correlation Set

6.4.5 Step 5: Associating Correlation Sets with Receive Activities

You now associate the correlation sets with the receive activities. You perform the following correlation set tasks:

• For the first correlated group, the first and second receive activities are correlated with the CorrelationSet1 correlation set.

• For the second correlated group, the second and third receive activities are correlated with the CorrelationSet2 correlation set.

This section contains the following topics:

• Associating the First Correlation Set with a Receive Activity

• Associating the Second Correlation Set with a Receive Activity

• Associating the Third Correlation Set with a Receive Activity

6.4.6 Step 6: Creating Property Aliases

Property aliases enable you to map a global property to a field in a specific message part. This enables the property name to become an alias for the message part and location. The alias can be used in XPath expressions.

This section contains the following topics:

• Creating Property Aliases for NameCorr

• Creating Property Aliases for IDCorr

6.4.7 Step 7: Reviewing WSDL File Content

The NameCorr and IDCorr correlation set properties are defined in the MyCorrelationSet_Properties.wsdl file in the Applications Navigator of JDeveloper BPEL Designer:

<definitions
     name="properties"
     targetNamespace="http://xmlns.oracle.com/MyCorrelationSet/correlationset"
     xmlns="http://schemas.xmlsoap.org/wsdl/"
     xmlns:bpws="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
     xmlns:plnk="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"
     xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <bpws:property name="NameCorr" type="xsd:string"/>
    <bpws:property name="IDCorr" type="xsd:double"/>
</definitions>

The property aliases are defined in the MyCorrelationSet.wsdl file:

<bpws:propertyAlias propertyName="ns1:NameCorr"
 messageType="ns3:LoanAppl_msg"
 part="LoanAppl" query="/ns2:LoanAppl/ns2:Name"/>

<bpws:propertyAlias propertyName="ns1:NameCorr" 
 messageType="ns5:LoanAppResponse_msg" 
 part="LoanAppResponse" query="/ns4:LoanAppResponse/ns4:APR"/>

<bpws:propertyAlias propertyName="ns1:IDCorr" 
 messageType="ns5:LoanAppResponse_msg" 
 part="LoanAppResponse" query="/ns4:LoanAppResponse/ns4:APR"/>

<bpws:propertyAlias propertyName="ns1:IDCorr" 
 messageType="ns7:CustResponse_msg" 
 part="CustResponse" query="/ns6:CustResponse/ns6:APR"/>

Because the BPEL process is not created as a Web services provider in this example, the MyCorrelationSet.wsdl file is not referenced in the BPEL process. Therefore, you must import the MyCorrelationSet.wsdl file inside the FirstReceive.wsdl file to reference the correlation sets:

<import namespace="http://xmlns.oracle.com/MyCorrelationSet" location="MyCorrelationSet.wsdl"/>