Skip Headers
Oracle® BPEL Process Manager Developer's Guide
10g Release 2 (10.1.2)
B14448-03
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

6 Invoking an Asynchronous Web Service

This chapter describes how to call an asynchronous Web service. Asynchronous messaging styles are very 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 chapter contains the following topics:

6.1 Use Case for Asynchronous Web Services

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 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. However, the same BPEL call can interact with any properly designed Web service. The target Web service's .wsdl file contains the information necessary to request and receive the desired information.

Figure 6-1 provides an overview of how this BPEL process works with the asynchronous loan processor Web service.

Figure 6-1 Asynchronous Service Invocation

Description of Figure 6-1  follows
Description of "Figure 6-1 Asynchronous Service Invocation"

For the asynchronous Web service, which is indicated within the dotted rectangle between the BPEL process's receive and reply activities, the following actions take place:

  1. An assign activity (prepare LoanApp) prepares the loan application.

  2. An invoke activity (initiate service) 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 inititiating 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 requestor.

  3. The loan processor Web service then sends the correct response to the receive activity (Wait for callback), which has been tracked by the correlation ID.

  4. An assign activity (Read offer) reads the loan application offer.

The remaining sections in this chapter provide specific details about the asynchronous functionality shown in Figure 6-1.


See Also:

The following sample files for examples of an asynchronous Web service that is not a BPEL process:
  • C:\orabpel\samples\interop\axis\BPELCallingAsyncAXIS (for Eclipse BPEL Designer)

  • Oracle_Home\integration\orabpel\samples\interop\axis\BPELCallingAsyncAXIS (for JDeveloper BPEL Designer)


6.2 Overview of Asynchronous Callback Concepts

This section examines how asynchronous functionality is defined in the loan application approver Web service's LoanService.wsdl file (the Web service to be called) and the client's LoanBroker.bpel file and bpel.xml deployment description file. It covers the following topics:


See Also:

The following files described in this chapter:

If you are using Eclipse BPEL Designer:

  • C:\orabpel\samples\utils\AsyncLoanService\LoanService.wsdl

  • C:\orabpel\samples\tutorials\105.AsyncCompositeLoanBroker\ LoanBroker.bpel

  • C:\orabpel\samples\tutorials\105.AsyncCompositeLoanBroker\bpel.xml

If you are using JDeveloper BPEL Designer:

  • Oracle_Home\integration\orabpel\samples\utils\AsyncLoanService\LoanService.wsdl

  • Oracle_Home\integration\orabpel\samples\tutorials\105.AsyncCompositeLoanBroker\LoanBroker.bpel

  • Oracle_Home\integration\orabpel\samples\tutorials\105.AsyncCompositeLoanBroker\bpel.xml


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

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

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.


See Also:

The following sections for instructions on creating invoke and receive activities:

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:

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  follows
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 BPEL process 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, 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 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.

6.2.4.1.1 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. Start your TCP listener to listen on a port such as 1234 and send on a port such as 9700 (port 9700 is the default after Oracle BPEL Process Manager for Developers installation). For example, you can use the TCP tunnel included with Apache Axis (bundled with Oracle BPEL Process Manager) by executing the following from the operating system command prompt:

    prompt> obsetenv
    prompt> java -classpath %OB_CLASSPATH% orabpel.apache.axis.utils.tcpmon 1234
     localhost 9700
    
    
  2. Add a location property in the bpel.xml deployment descriptor file for your flow to override the endpoint of the service. For example, to see the messages exchanged between the LoanFlow demo sample and the CreditRatingService that it calls, change the definition of the CreditRatingService location as shown below in the LoanFlow deployment descriptor in Oracle_Home\samples\demos\LoanDemo\LoanFlow\bpel.xml:

    <partnerLinkBinding name="creditRatingService">    <property name="wsdlLocation">       http://localhost:9700/orabpel/default/CreditRatingService/         CreditRatingService?wsdl    </property>    <property name="location">       http://localhost:1234/orabpel/default/CreditRatingService    </property></partnerLinkBinding>
    
    
  3. Compile and deploy the LoanDemo from the operating system command prompt:

    prompt> cd Oracle_Home\integration\orabpel\samples\demos\LoanDemo
    prompt> obant
    
    

    Note that while the CreditRatingService is also a BPEL process, the same technique can be used to see the SOAP messages passed to invoke a BPEL process as a Web service from another tool kit such as Axis or .NET.

6.2.4.1.2 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 such as 9710 and to send on the Oracle BPEL Process Manager port (9700 is the default after installation).

  2. Turn off the optimization of local SOAP calls performed by Oracle BPEL Process Manager to see the impact of changing the callback port:

    1. Click Manage BPEL Domain in the upper right of Oracle BPEL Console.

    2. Scroll down to the optSoapShortcut property.

    3. Change the value from true to false.

  3. Access Oracle BPEL Admin Console at:

    http://localhost:9700/BPELAdmin
    
    

    You can also access Oracle BPEL Admin Console by clicking Go to BPEL Admin at the bottom of the login page for Oracle BPEL Console.


    See Also:

    Oracle BPEL Process Manager Installation Guide for information about the initial Oracle BPEL Admin Console password

  4. Scroll down to the SoapServerUrl property on the Configuration tab.

  5. Change this property to http://localhost:9710.

  6. Click the Apply button.

  7. Restart Oracle BPEL Server to initialize these changes and initiate any flow that invokes asynchronous Web services (for example the LoanFlow demonstration). You can combine this with the synchronous TCP tunneling configuration to send the UnitedLoan service initiation request through your first TCP tunnel.

    The callbacks from the asynchronous services are shown in the TCP listener, such as the UnitedLoan service callback.

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:

  • Web Services Addressing (WS-Addressing) Specification for complete details about WS-Addressing, which is accessible from http://www.oracle.com/technology/bpel
  • Oracle_Home/integration/orabpel/samples/demos/LoanDemo for the LoanFlow demo used in this section


6.2.4.2 Using Correlation Sets to Coordinate Asynchronous Message Body Contents

Correlation sets are a BPEL mechanism that provides for the correlation of asynchronous messages based on message body contents. To use this method, define the correlation sets in your .bpel file. This method is designed for services that do not support WS-Addressing or for certain sophisticated conversation patterns, for example, when the conversation is in the form A > B > C > A instead of A > B > A.


See Also:

The following correlation set examples:
  • "Using Correlation Sets in an Asynchronous Service" for a tutorial on creating correlations sets in JDeveloper BPEL Designer

  • C:\orabpel\samples\tutorials\109.CorrelationSets (for Eclipse BPEL Designer)

  • Oracle_Home\integration\orabpel\samples\tutorials\109.CorrelationSets (for JDeveloper BPEL Designer)


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>

See Also:


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 Calling an Asynchronous Service

To add asynchronous functionality to a BPEL process, complete the tasks in this section:

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 async1.gif follows
      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:


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 async3.gif follows
    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 async5.gif follows
    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 async6.gif follows
    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:


  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 createglobvar2.gif follows
    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.

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.


See Also:

The following documentation for information on creating and defining an assign activity:

6.4 Using Correlation Sets in an Asynchronous Service

This tutorial describes how to use correlation sets in an asynchronous service with JDeveloper BPEL Designer. Correlation sets enable you to correlate asynchronous messages based on message body contents. You define correlation sets when interactions are not simple invoke-receive activities. This example illustrates how to use correlation sets for a process having three receive activities with no associated invoke activities.

This section contains the following topics:

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:

6.4.2.1 Creating an Initial Partner Link and File Adapter Service

  1. Drag and drop an initial PartnerLink activity onto the right side of the designer window anywhere beneath the header Partner Links.

  2. Enter FirstReceivePL in the Name field.

  3. Click the third icon at the top (the Define Adapter Service icon). This starts the Adapter Configuration Wizard.

    Description of adapter_service.gif follows
    Description of the illustration adapter_service.gif

  4. Click Next on the Welcome window.

  5. Select File Adapter on the Adapter Type window and click Next.

  6. Enter FirstReceive in the Service Name field on the Service Name window and click Next.

  7. Select Read File as the Operation Type on the Operation window and click Next. The Operation Name field is automatically filled in with Read.

  8. Select Directory Names are Specified as Physical Path.

  9. Click Browse next to the Directory for Incoming Files (physical path) field.

  10. Select a directory from which to read files (for this example, C:\files\receiveprocess\FirstInputDir is selected).

  11. Click Select.

  12. Click Next.

  13. Enter appropriate file filtering parameters in the File Filtering window.

  14. Click Next.

  15. Enter appropriate file polling parameters in the File Polling window.

  16. Click Next.

  17. Click Browse next to the Schema File URL field in the Messages window to display the Type Chooser window.

  18. Select an appropriate XSD schema file. For this example, Book1_4.xsd is the schema and LoanAppl is the schema element selected.

  19. Click OK.

    The Schema File URL field (Book1_4.xsd for this example) and the Schema Element field (LoanAppl for this example) are filled in.

  20. Click Next.

  21. Click Finish.

    You are returned to the Partner Link window. All other fields are automatically completed. The window looks as follows:

    Field Value
    Name FirstReceivePL
    WSDL File file:/c:OraBPEL/integration/jdev/jdev/mywork/myworkspace/MyCorrelationSet/FirstReceive.wsdl
    Partner Link Type Read_plt
    My Role Read_role
    Partner Role Leave unspecified.

  22. Click OK.

6.4.2.2 Creating a Second Partner Link and File Adapter Service

  1. Drag and drop a second PartnerLink activity below the FirstReceivePL partner link activity.

  2. Enter SecondReceivePL in the Name field.

  3. Click the third icon at the top (the Define Adapter Service icon).

  4. Click Next on the Welcome window.

  5. Select File Adapter in the Adapter Type window and click Next.

  6. Enter SecondFileRead in the Service Name field on the Service Name window and click Next. This name must be unique from the one you entered in Step 6.

  7. Select Read File as the Operation Type in the Operation window

  8. Change the name in the Operation Name field to Read1.

  9. Click Next.

  10. Select Directory Names are Specified as Physical Path.

  11. Click Browse next to the Directory for Incoming Files (physical path) field.

  12. Select a directory from which to read files (for this example, C:\files\receiveprocess\SecondInputDir is entered).

  13. Click Select.

  14. Click Next.

  15. Enter appropriate file filtering parameters in the File Filtering window.

  16. Click Next.

  17. Enter appropriate file polling parameters in the File Polling window.

  18. Click Next.

  19. Click Browse next to the Schema File URL field in the Messages window to display the Type Chooser window.

  20. Select an appropriate XSD schema file. For this example, Book1_5.xsd is the schema and LoanAppResponse is the schema element selected.

  21. Click OK.

    The Schema File URL field (Book1_5.xsd for this example) and the Schema Element field (LoanAppResponse for this example) are filled in.

  22. Click Next.

  23. Click Finish.

    You are returned to the Partner Link window. All other fields are automatically completed. The window looks as follows:

    Field Value
    Name SecondReceivePL
    WSDL File file:/c:OraBPEL/integration/jdev/jdev/mywork/myworkspace/MyCorrelationSet/SecondFileRead.wsdl
    Partner Link Type Read1_plt
    My Role Read1_role
    Partner Role Leave unspecified.

  24. Click OK.

6.4.2.3 Creating a Third Partner Link and File Adapter Service

  1. Drag and drop a third PartnerLink activity below the SecondReceivePL partner link activity.

  2. Enter ThirdReceivePL in the Name field.

  3. Click the third icon at the top (the Define Adapter Service icon).

  4. Click Next on the Welcome window.

  5. Select File Adapter in the Adapter Type window and click Next.

  6. Enter ThirdFileRead in the Service Name field of the Service Name window and click Next. This name must be unique from the one you entered in Step 6 and Step 6.

  7. Select Read File as the Operation Type in the Operation window

  8. Change the name in the Operation Name field to Read2. This name must be unique.

  9. Click Next.

  10. Select Directory Names are Specified as Physical Path.

  11. Click Browse next to the Directory for Incoming Files (physical path) field.

  12. Select a directory from which to read files (for this example, C:\files\receiveprocess\ThirdInputDir is entered).

  13. Click Select.

  14. Click Next.

  15. Enter appropriate file filtering parameters in the File Filtering window.

  16. Click Next.

  17. Enter appropriate file polling parameters in the File Polling window.

  18. Click Next.

  19. Click Browse next to the Schema File URL field in the Messages window to display the Type Chooser window.

  20. Select an appropriate XSD schema file. For this example, Book1_6.xsd is the schema and CustResponse is the schema element selected.

  21. Click OK.

    The Schema File URL field (Book1_6.xsd for this example) and the Schema Element field (CustResponse for this example) are filled in.

  22. Click Next.

  23. Click Finish.

    You are returned to the Partner Link window. All other fields are automatically completed. The window looks as follows:

    Field Value
    Name ThirdReceivePL
    WSDL File file:/c:OraBPEL/integration/jdev/jdev/mywork/myworkspace/MyCorrelationSet/ThirdFileRead.wsdl
    Partner Link Type Read2_plt
    My Role Read2_role
    Partner Role Leave unspecified.

  24. Click OK.

    When complete, the designer window looks as follows:

    Description of cs_pl.gif follows
    Description of the illustration cs_pl.gif

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:

6.4.3.1 Creating an Initial Receive Activity

  1. Drag and drop a Receive activity from the Component Palette section into the designer window.

  2. Double-click the receive icon to display the Receive window.

  3. Enter the following details to associate the first partner link (FirstReceivePL) with the first receive activity:

    Field Value
    Name receiveFirst
    Partner Link FirstReceivePL
    Create Instance Select this check box.

    The Operation (Read) field is automatically filled in.

  4. Click the first icon to the right of the Variable field. This is the automatic variable creation icon.

  5. Click OK on the Create Variable window that appears.

    A variable named receiveFirst_Read_InputVariable is automatically created in the Variable field.

  6. Ensure that you selected the Create Instance check box, as mentioned in Step 3.

  7. Click OK.

6.4.3.2 Creating a Second Receive Activity

  1. Drag and drop a second Receive activity from the Component Palette section to below the receiveFirst receive activity.

  2. Double-click the receive icon to display the Receive window.

  3. Enter the following details to associate the second partner link (SecondReceivePL) with the second receive activity:

    Field Value
    Name receiveSecond
    Partner Link SecondReceivePL
    Create Instance Do not select this check box.

    The Operation (Read1) field is automatically filled in.

  4. Click the first icon to the right of the Variable field.

  5. Click OK on the Create Variable window that appears.

    A variable named receiveSecond_Read1_InputVariable is automatically created in the Variable field.

  6. Click OK.

6.4.3.3 Creating a Third Receive Activity

  1. Drag and drop a third Receive activity from the Component Palette section to below the receiveSecond receive activity.

  2. Double-click the receive icon to display the Receive window.

  3. Enter the following details to associate the third partner link (ThirdReceivePL) with the third receive activity:

    Field Value
    Name receiveThird
    Partner Link ThirdReceivePL
    Create Instance Do not select this check box.

    The Operation (Read2) field is automatically filled in.

  4. Click the first icon to the right of the Variable field.

  5. Click OK on the Create Variable window that appears.

    A variable named receiveThird_Read2_InputVariable is automatically created in the Variable field.

  6. Click OK.

    When complete, the designer window looks as follows. Each receive activity is now associated with a specific partner link.

    Description of cs_rec.gif follows
    Description of the illustration cs_rec.gif

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:

6.4.4.1 Creating an Initial Correlation Set

  1. Right-click Correlation Sets and select Expand All Child Nodes in the Structure window of JDeveloper BPEL Designer.

  2. Right-click Correlation Sets and select Create Correlation Set.

  3. Enter CorrelationSet1 in the Name field of the Create Correlation Set window.

  4. Click Add in the Properties section to display the Property Chooser window.

  5. Select Properties, then click Create to display the Create Correlation Set Property window.

  6. Enter NameCorr in the Name field and click the flashlight icon to the right of the Type field.

  7. Select string in the Type Chooser window and click OK.

  8. Click OK to close the Create Correlation Set Property window, the Property Chooser window, and the Create Correlation Set window.

6.4.4.2 Creating a Second Correlation Set

  1. Return to the Correlation Sets section in the Structure window of JDeveloper BPEL Designer.

  2. Right-click Correlation Sets and select Create Correlation Set.

  3. Enter CorrelationSet2 in the Name field of the Create Correlation Set window.

  4. Click Add in the Properties section to display the Property Chooser window.

  5. Select Properties, then click Create to display the Create Correlation Set Property window.

  6. Enter IDCorr in the Name field and click the flashlight icon to the right of the Type field.

  7. Select double in the Type Chooser window and click OK.

  8. Click OK to close the Create Correlation Set Property window, the Property Chooser window, and the Create Correlation Set window.

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:

6.4.5.1 Associating the First Correlation Set with a Receive Activity

  1. Double-click the receiveFirst receive activity to display the Receive window.

  2. Click the Correlations tab.

  3. Click Add, select CorrelationSet1, then click OK.

  4. Set the Initiate column to yes. When set to yes, the set is initiated with the values of the properties occurring in the message being exchanged.

    Description of cs_set1.gif follows
    Description of the illustration cs_set1.gif

  5. Click OK.

6.4.5.2 Associating the Second Correlation Set with a Receive Activity

  1. Double-click the receiveSecond receive activity to display the Receive window.

  2. Click the Correlations tab.

  3. Click Add, select CorrelationSet2, then click OK.

  4. Set the Initiate column to yes.

  5. Click Add and select CorrelationSet1.

  6. Click OK.

  7. Set the Initiate column to no for CorrelationSet1.

    Description of cs_set2.gif follows
    Description of the illustration cs_set2.gif

  8. Click OK.

    This groups the first and second receive activities into a correlated group.

6.4.5.3 Associating the Third Correlation Set with a Receive Activity

  1. Double-click the receiveThird receive activity to display the Receive window.

  2. Click the Correlations tab.

  3. Click Add and select CorrelationSet2.

  4. Click OK.

  5. Set the Initiate column to no for CorrelationSet2.

    Description of cs_set3.gif follows
    Description of the illustration cs_set3.gif

  6. Click OK.

    This groups the second and third receive activities into a second correlated group.

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:

6.4.6.1 Creating Property Aliases for NameCorr

You create the following two property aliases for the NameCorr correlation set.

  • Map NameCorr to the LoanAppl message type part of the receiveFirst receive activity. This receive activity is associated with the FirstReceivePL partner link (defined by the FirstReceive.wsdl file).

  • Map NameCorr to the incoming LoanAppResponse message type part of the receiveSecond receive activity. This receive activity is associated with the SecondReceivePL partner link (defined by the SecondFileRead.wsdl file).

  1. Right-click Property Aliases in the Structure section of JDeveloper BPEL Designer.

  2. Select Create Property Alias.

  3. Select NameCorr in the Property list.

  4. Expand and select Message Types > Partner Links > FirstReceivePL > FirstReceive.wsdl > Message Types > LoanAppl_msg > Part - LoanAppl.

  5. Press Ctrl and then the space bar in the Query field to define the following XPath expression:

    /ns2:LoanAppl/ns2:Name
    
    
  6. Click OK.

  7. Repeat Step 1 through Step 3 to create a second property alias for NameCorr.

  8. Expand and select Message Types > Project WSDL Files > SecondFileRead.wsdl > Message Types > LoanAppResponse_msg > Part - LoanAppResponse.

  9. Press Ctrl and then the space bar in the Query field to define the following XPath expression:

    /ns4:LoanAppResponse/ns4:APR
    

6.4.6.2 Creating Property Aliases for IDCorr

You create the following two property aliases for the IDCorr correlation set.

  • Map IDCorr to the LoanAppResponse message type part of the receiveSecond receive activity. This receive activity is associated with the SecondReceivePL partner link (defined by the SecondFileRead.wsdl file).

  • Map IDCorr to the CustResponse message type part of the receiveThird receive activity. This receive activity is associated with the ThirdReceivePL partner link (defined by the ThirdFileRead.wsdl file).

  1. Right-click Property Aliases in the Structure section.

  2. Select Create Property Alias.

  3. Select IDCorr in the Property list.

  4. Expand and select Message Types > Project WSDL Files > SecondFileRead.wsdl > Message Types > LoanAppResponse_msg > Part - LoanAppResponse.

  5. Press Ctrl and then the space bar in the Query field to define the following XPath expression:

    /ns4:LoanAppResponse/ns4:APR
    
    
  6. Click OK.

  7. Repeat Step 1 through Step 3 to create a second property alias for IDCorr.

  8. Expand and select Message Types > Project WSDL Files > ThirdFileRead.wsdl > Message Types > CustResponse_msg > Part - CustResponse.

  9. Press Ctrl and then the space bar in the Query field to define the following XPath expression:

    /ns6:CustResponse/ns6:APR
    
    

    Design is now complete.

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

6.5 Summary

This chapter describes the concepts for a BPEL process that invokes an asynchronous Web service. This service takes a loan application request document as input from a client and asynchronously returns an approved loan offer. An example of how to create correlation sets in JDeveloper BPEL Designer is also provided.