1. Developing SOA Applications with Oracle SOA Suite
  2. Using the BPEL Process Service Component
  3. Invoking an Asynchronous Web Service from a BPEL Process

8 Invoking an Asynchronous Web Service from a BPEL Process

This chapter describes how to configure and invoke an asynchronous web service from a BPEL process. It also describes how to route callback messages to the correct endpoint when multiple receive or pick activities use the same partner link, manage idempotence at the partner link operation level, create a dynamic partner link at runtime, override security certificates and WSDL files in dynamic partner link environments, 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.

Subsequent 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

8.2.1.1 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 Components section of the Components window into the designer.

    The Create BPEL Process dialog appears.

  2. Follow the instructions in the dialog to create an asynchronous 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).

    Oracle BPEL Designer appears.

  5. In the Components window, 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 Browser 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.

8.2.1.2 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 Components window, 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, 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.

  7. Click OK.
  8. Click the invoke activity to display its property fields in the Property Inspector or double-click the invoke activity to display the Invoke dialog.

    For information about editing activities in the Property Inspector, see How to Edit BPEL Activities in the Property Inspector.

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

  11. Click OK.
8.2.1.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.

To add a receive activity:

  1. From the Components window, drag a Receive activity to the location right after the Invoke activity you created in 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 Adding an Invoke Activity.

    Note:

    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). BPEL 2.0 is the default version when you create a BPEL process. For more information, see How to Initialize 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 check box.
  6. Select the variable you created in Step 3 through Step 7 of 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.

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

8.2.2 What Happens When You Invoke an Asynchronous Web Service

This section describes what happens when you invoke an asynchronous web service.

8.2.2.1 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

  • The other calls back the client with the asynchronous response

In the example shown below, the portType LoanServiceCallback receives the client's loan application request and the portType LoanService asynchronously calls back the client with the loan offer response. 

<!-- portType implemented by the LoanService BPEL process -->
   <portType name="LoanService">
      <operation name="initiate">
         <input message="tns:LoanServiceRequestMessage"/>
      </operation>
   </portType>
<!-- portType implemented by the requester of LoanService BPEL process
for asynchronous callback purposes
-->
   <portType name="LoanServiceCallback">
      <operation name="onResult">
         <input message="tns:LoanServiceResultMessage"/>
      </operation>
   </portType>
8.2.2.2 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 the following example, 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. 

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

Two port types are combined into this single asynchronous BPEL process service component: portType="services:LoanService" of the invoke activity and portType="services:LoanServiceCallback" of the receive activity. Port types are essentially a collection of operations to be performed. For this BPEL process service component, there are two operations to perform: initiate in the invoke activity and onResult in the receive activity.

8.2.2.3 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. The following provides an example. 

  <!-- 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 myRole and partnerRole attributes in asynchronous processes.

8.2.2.4 Composite Application File

In the composite.xml file, the loan application approver web service appears, as shown below. 

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

For more information, see Adding a Partner Link for an Asynchronous Service for instructions on creating a partner link.

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

The following provides an example.

  <variables>
    <variable name="request"
               messageType="services:LoanServiceRequestMessage"/>
    <variable name="response"
               messageType="services:LoanServiceResultMessage"/>
  </variables>
<sequence>
    <!-- initialize the input of LoanService -->
    <assign>
    . . .
    . . .
    </assign>
    <!--  initiate the remote process -->
    <invoke name="invoke" partnerLink="LoanService"
        portType="services:LoanService"
        operation="initiate" inputVariable="request"/>
    <!--  receive the result of the remote process -->
    <receive name="receive_invoke" partnerLink="LoanService"
        portType="services:LoanServiceCallback"
        operation="onResult" variable="response"/>

When an asynchronous service is initiated with the invoke activity, a correlation ID unique to the client request is also sent, using Web Services Addressing (WS-Addressing) (described in 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.

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

The following example shows the source code for the createInstance attribute: 

    <!-- receive input from requester -->
    <receive name="receiveInput" partnerLink="client"
             portType="tns:LoanBroker"
             operation="initiate" variable="input"
             createInstance="yes"/>
8.2.2.7 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 Dehydrate Activity.

8.2.2.8 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. The following provides an example. 

<reference name="HeaderService ...>
<binding.ws port="http://services.otn.com/HelloWorldApp#wsdl.endpoint(client/
  HelloWorldService_pt)"
location="http://server:port/soa-infra/services/default/ 
 HelloWorldService!1.0/client?WSDL">
<property name="endpointURI">http://jsmith.us.example.com:80/a.jsp 
@http://myhost.us.example.com:8888/soa-infra/services/HelloWorldApp/HelloWorld!
1.0*2007-10-22_14-33-04_195/client
 </property>
</binding.ws>
</reference>

8.2.3 What You May Need to Know About Midprocess Receive Activities Consuming Messages After Timing Out

A BPEL process can consume midprocess receive activity messages even after the expiration of a configured timeout on the receive activity, if the exception resulting from the timeout goes unhandled. In these scenarios, the callback message is consumed when it is delivered. This is the expected behavior.

For example, assume you perform the following tasks:

  • Create a SOA composite application with a client BPEL process and service BPEL process to exchange a message using asynchronous invoke and receive activities.

  • Configure a timeout of 30 seconds in the Timeout tab of the receive activity of the client BPEL process.

  • Configure a wait activity to wait for five minutes in the service BPEL process.

You may expect that after the timeout occurs, the client BPEL process is marked as completed in the faulted state instead of remaining in the running state, and the callback message from the service BPEL process is ignored. However, when the timeout fault is thrown on the client BPEL process, it remains in the running state. When the service BPEL process responds five minutes after the completion of the wait activity, the response is sent back to the client BPEL process and the response is consumed by the client BPEL process and reconciled with the running process instance.

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

Note:

You cannot explicitly set the Conversation ID (internal/hidden state) of a composite while using AQ Adapter. The Database sets the Conversation ID in this case.
8.2.6.1 bpelx:conversationId in BPEL 1.1

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

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

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

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

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

<invoke ...>
  <bpelx:conversationId>$convId1</bpelx:conversationId>
</invoke>

<receive ...>
  <bpelx:conversationId>$convId1</bpelx:conversationId>
</receive>

<onMessage ...>
  <bpelx:conversationId>$convId2</bpelx:conversationId>
</onMessage>

8.3 Routing Callback Messages to the Correct Endpoint when Multiple Receive or Pick Activities Use the Same Partner Link

The replyToAddress normalized message property is required for resolving the routing of callback messages to the correct endpoint address when multiple receive or pick activities are associated with the same partner link.

This is because the BPEL process service engine only stores the replyToAddress property once when receiving a request from a partner link at the initiating receive or pick activity. The replyToAddress property routes the callback message and is not reset if a midprocess receive or pick activity is used. The replyToAddress property uses the bpelx:inputProperty extension.

8.3.1 How to Route Callback Messages to the Correct Endpoint when Multiple Receive and Pick Activities Use the Same Partner Link

Set this property to the client's replyToAddress on the invoke activity (for the callback) following the midprocess receive activity. This means that even if the client sends WS-Addressing replyTo information for a midprocess receive activity, it is not set on the partner link unless you use an assign activity to set it dynamically.

For example, assume your BPEL process is as shown below:

Caller                               Callee
-----------------------------------------------------------
<receive>                            <receive> Initiate CS1
<invoke>initiate CS1 -------->       <receive> Use CS1
                                     <wait>
<receive>use CS1    <--------        <invoke>
<invoke>

To route callback messages to the correct endpoint when multiple receive and pick activities use the same partner link:

  1. Obtain the client's replyToAddress value from the midprocess receive activity.
    <receive name="receiveMsgFromAccessor" partnerLink="midprocess_client"
       portType="client:mySingletonBPEL" operation="process"
       variable="ReceiveMidProcess" createInstance="no">
<bpelx:fromProperties>
   <bpelx:fromProperty name="replyToAddress" variable="var_replyToAddress"/>
</bpelx:fromProperties>
   <correlations>
       <correlation set="<YourCorrset>" initiate="no"/>
   </correlations>
</receive>
  2. On the invoke activity (for the callback), click the Properties tab.
  3. Click the Add icon to select the property and its content (either a variable or an XPath expression).

    Note:

    In BPEL 1.1 processes, the properties are automatically displayed in the Properties column. Select the property in the Name column and double-click the Value and Type columns to enter appropriate values.

  4. In the Name column, scroll down and select the replyToAddress property. Do not select wsa.replyToAddress or bpel.replyToAddress.
  5. In the Value column, specify the variable name as the value (for this example, var_replyToAddress from Step 1 is entered), and click OK.

    The Edit Invoke dialog appears as shown in Figure 8-1.

    Figure 8-1 Properties Tab of Invoke Activity

    Description of Figure 8-1 follows
    Description of "Figure 8-1 Properties Tab of Invoke Activity"
  6. Click Apply, then OK.
  7. In Oracle BPEL Designer, click Source.

    The invoke activity in the BPEL process file looks as follows:

    <invoke name="callbackAccessor" partnerLink="midprocess_client"
                portType="client:mySingletonBPELCallback"
                operation="processResponse"
inputVariable="CallbackAccessorVar"
                bpelx:invokeAsDetail="no">
            <bpelx:inputProperty name="replyToAddress"
variable="var_replyToAddtess"/>

8.4 Managing Idempotence at the Partner Link Operation Level

An idempotent activity is an activity that can be safely retried. Idempotent activities are applicable to both durable and transient processes. You can manage idempotence at the operation level of a partner link. For example, some partner links can expose multiple operations (for example, getEmployee, depositPayCheck, and so on). You can define some operations as idempotent (for example, getEmployee). This enables these operations to be called multiple times. Other operations may not need to be idempotent (for example, depositPayCheck), and do not require this setting. Dehydration does occur after a nonidempotent operation.

By default, all partner link operations are idempotent. If you want, you can set an operation to be nonidempotent. This setting provides the same functionality as the idempotent deployment descriptor property, but at the more granular, operational level.

For more information about the idempotent deployment descriptor property, see What You May Need to Know About the idempotent Property and Fault Handling and Introduction to Deployment Descriptor Properties.

8.4.1 How to Manage Idempotence at the Partner Link Operation Level

To manage idempotence at the partner link operation level:

  1. In Oracle BPEL Designer, double-click the partner link that includes the operations for which to manage idempotence.
  2. Click the Idempotence tab of the partner link.

    By default, all operations are selected to be idempotent in the Idempotent column.

  3. If you want to define an operation to be nonidempotent, deselect the Idempotent check box for that operation. Figure 8-2 provides details.

    Figure 8-2 Idempotence Tab of Partner Link Activity

    Description of Figure 8-2 follows
    Description of "Figure 8-2 Idempotence Tab of Partner Link Activity"
  4. Click Apply.
  5. Click OK.

For more information about idempotence and the idempotent property, see Introduction to Deployment Descriptor Properties.

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

  • Service endpoints (addresses) may not be known at design time.

  • Endpoint references may need to change while the application is running.

The dynamic partner link feature enables you to dynamically assign an endpoint reference to a partner link for use at runtime in BPEL versions 1.1 and 2.0. The dynamic partner link provides conditions, similar to a switch activity, that are evaluated at runtime.

8.5.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="host:port/soa-infra/services/domain_
name/AmericanLoan/client"/>
 </port>
</service>

<service name="AlliedLoan">
 <port name="LoanServicePort" binding="tns:LoanServiceBinding">
  <soap:address location="host:port/soa-infra/services/domain_
name/AlliedLoan/client"/>
 </port>
</service>

<service name="AcmeLoan">
 <port name="LoanServicePort" binding="tns:LoanServiceBinding">
  <soap:address location="host:port/soa-infra/services/domain_
name/AcmeLoan/client"/>
 </port>
</service>
  2. Drag a SOAP 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="http://services.otn.com#wsdl.interface(LoanService)"
callbackInterface="http://services.otn.com#wsdl.interface(LoanServiceCallback)"
/>
    <binding.ws port=
       "http://services.otn.com#wsdl.endpoint(AmericanLoan/LoanService_pt)"/>
  </reference>

    Note:

    • Adding the binding.ws port setting is optional. This is because the port is overridden at runtime by properties passed from Oracle BPEL Process Manager.

    • If there is no port setting, and there is no composite import of the concrete WSDL associated with this reference, you must specify the location of the concrete WSDL with a location attribute.

  4. Double-click the BPEL process to enter Oracle BPEL Designer.
  5. Drag an Assign activity into the designer.
  6. 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"
  7. Drag the 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.

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

    The following provides a BPEL 1.1 sample:

    <EndpointReference xmlns="http://schemas.xmlsoap.org/ws/2003/03/addressing">
         <Address>http://host:port/soa-infra/services/domain_name
           /AlliedLoan/client</Address>
<ServiceName xmlns:ns1="http://services.otn.com"
   PortName="LoanServicePort">ns1:AlliedLoan</ServiceName>
</EndpointReference>

    The following provides a BPEL 2.0 sample:

    <assign>
  <copy>
    <from>
      <literal>
        <sref:service-ref>
          <services:EndpointReference>
          <services:Address>http://host:port/soa-infra/services/domain_
           name/AlliedLoan/client</services:Address>
           <services:ServiceName
           xmlns:ns1="http://services.otn.com">ns1:AlliedLoan</services:
           ServiceName>
          </services:EndpointReference>
        </sref:service-ref>
      </literal>
    </from>
    <to partnerLink="LoanService"/>
  </copy>
</assign>

8.6 Overriding Security Certificates when Invoking Dynamic Partner Links

You can interact with multiple web services using dynamic partner links. This interaction may involve using message protection policies that require different security certificates for encrypting the message. These certificates may be different for each web service. You can specify a keystore recipient alias value to override the security certificate in the WSDL file of the web service.

To override security certificates when invoking partner links:

  1. Define a variable of type string (for example, KEYSTORE_RECIPIENT_ALIAS). Figure 8-5 provides details.

    Figure 8-5 Variable Definition of KEYSTORE_RECIPIENT_ALIAS

    Description of Figure 8-5 follows
    Description of "Figure 8-5 Variable Definition of KEYSTORE_RECIPIENT_ALIAS"
  2. In the Copy Rules tab of an assign activity, assign orakey to the variable KEYSTORE_RECIPIENT_ALIAS. Figure 8-6 provides details.

    Figure 8-6 Assignment of orakey to KEYSTORE_RECIPIENT_ALIAS

    Description of Figure 8-6 follows
    Description of "Figure 8-6 Assignment of orakey to KEYSTORE_RECIPIENT_ALIAS"
  3. In the invoke activity that invokes the partner link for the web service, click the Properties tab.
  4. Click the keystore.recipient.alias property.

    Note:

    In BPEL 2.0 processes, the properties are not automatically displayed in the Properties column. You must click the Add icon to select the property and its content (either a variable or an XPath expression).

  5. Double-click the Value column to display the Browse (...) icon.
  6. Click the Browse (...) icon to display the Adapter Property Value dialog.
  7. Click the Browse icon to display the Variable XPath Builder dialog.
  8. Select keystore_recipient_alias as the value, and click OK. Figure 8-7 provides details. This property overrides the security certificates set in the WSDL file while invoking a web service in a BPEL process.

    Note:

    In BPEL 2.0, there are only Name and Value columns in the Properties table. The Type column is not included.

    Figure 8-7 keystore.recipient.alias Normalized Message Property of Invoke Activity

    Description of Figure 8-7 follows
    Description of "Figure 8-7 keystore.recipient.alias Normalized Message Property of Invoke Activity "
  9. Click Apply, then OK.

    When complete, the BPEL file is defined as follows:

    . . .
. . .
<variables>
  <variable name="WsaAddress" element="ns6:EndpointReference"/>
  <variable name="KEYSTORE_RECIPIENT_ALIAS" type="xsd:string"/>
</variables>

<assign name="AssignAddress">
  <copy>
    <from
expression="'http://localhost:8001/soa-infra/services/default/ServiceWithNewCer
tificate!1.0*soa_c94537fb-97a4-4b0f-900f-fefffc34f7fe/service_ep'"/>
    <to variable="WsaAddress"
    query="/ns6:EndpointReference/ns6:Address"/>
  </copy>
  <copy>
    <from variable="WsaAddress"/>
    <to partnerLink="Service"/>
  </copy>
</assign>

<assign name="AssignAlias">
  <copy>
    <from expression='"orakey"'/>
    <to variable="KEYSTORE_RECIPIENT_ALIAS"/>
  </copy>
</assign>

<invoke name="Invoke"
        inputVariable="Invoke_InputVariable" 
        partnerLink="Service"
        portType="ns1:ServiceBPELProcess" 
        operation="process"
        bpelx:invokeAsDetail="no">

            <bpelx:inputProperty name="endpointURI" 
                                 variable="inputVariable"
                                 part="payload"
                                 query="/client:process/client:input"/>

            <bpelx:inputProperty name="keystore.recipient.alias" 
                                 variable="KEYSTORE_RECIPIENT_ALIAS"/>
</invoke>

For more information about normalized message properties, see Propagating Normalized Message Properties Through Message Headers.

8.7 Overriding WSDL Files of Dynamic Partner Links

You may need to override the default WSDL file used by dynamic partner links for the following reasons:

  • You must integrate with services that use message protection security policies.

  • The WSDL may contain important information such as the certificate used for message encryption.

The normalized message property endpointWSDL enables you to specify the WSDL file of the dynamic partner link. You must specify the entire WSDL dynamically instead of just the endpoint. This enables it to be passed to Oracle Web Services Manager (OWSM), which can then retrieve the correct service certificate from the specified WSDL.

The certificate in the WSDL file is ignored in the following cases:

Otherwise, the certificate is retrieved from the WSDL file.

To override WSDL files of dynamic partner links:

  1. Define a variable of type string (for this example, the_wsdl_var is defined).
  2. In the Copy Rules tab of an assign activity, assign the WSDL to the_wsdl_var.
  3. In the invoke activity that invokes the partner link, click the Properties tab.
  4. Click the endpointWSDL property.

    Note:

    In BPEL 2.0 processes, the properties are not automatically displayed in the Properties column. You must click the Add icon to select the property and its content (either a variable or an XPath expression).

  5. Double-click the Value column to display the Browse (...) icon.
  6. Click the Browse (...) icon to display the Adapter Property Value dialog.
  7. Click the Browse icon to display the Variable XPath Builder dialog.
  8. Select the_wsdl_var as the variable, and click OK. This value specifies the WSDL of the dynamic partner link.

    Note:

    In BPEL 2.0, there are only Name and Value columns in the Properties table. The Type column is not included.

    Figure 8-8 endpointWSDL Normalized Message Property of Invoke Activity

    Description of Figure 8-8 follows
    Description of "Figure 8-8 endpointWSDL Normalized Message Property of Invoke Activity"

    When complete, the BPEL file is defined as follows:

    <variables>
  <variable name="the_wsdl_var" type="xsd:string"/>
</variables>
 
<assign name="myAssignWsdl">
  <copy>
    <from
expression='"http://localhost:8001/soa-infra/services/default/ServiceWithNewCer
tificate!1.0/service_ep?WSDL"'/>
    <to variable="the_wsdl_var"/>
  </copy>
</assign>
 
<invoke name="Invoke"
        inputVariable="Invoke_InputVariable" 
        partnerLink="Service"
        portType="ns1:ServiceBPELProcess" 
        operation="process"
        bpelx:invokeAsDetail="no"> 
                   
            <bpelx:inputProperty name="endpointWSDL" 
                                 variable="the_wsdl_var"/>
 
</invoke>

For more information about normalized message properties, see Propagating Normalized Message Properties Through Message Headers.

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

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

Figure 8-9 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 Tunneling to View 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 service component flow and the web service (including those containing the correlation ID). You can see the exact SOAP messages that are sent to, or received from, services with which a BPEL process service component flow communicates.

    You insert a software listener between your BPEL process service component flow and the web service. Your BPEL process service component flow communicates with the listener (called a TCP tunnel). The listener forwards your messages to the web service, and also displays them. Responses from the web service are returned to the tunnel, which displays and forwards them back to the BPEL process service component.

8.8.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 and Oracle Mediator. You do not need to edit the .bpel and .wsdl files to use WS-Addressing.

8.8.1.1 Using TCP Tunneling to View 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 view 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.

8.8.1.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 and Oracle Mediator 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
port_on_which_remote_server_is_running
  5. In the composite.xml file, add the endpointURI property under binding.ws 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.

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

      Note:

      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 navigate to the specific SCAComposite.SCAReference.SCABinding folder.

    2. Click WSBinding.

    3. Perform steps 44.b through 44.l.

  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.

For information about using correlation sets for message correlation, see Using Correlation Sets and Message Aggregation .