34 Using the Oracle BPEL Process Manager Transport

This chapter provides an overview of the BPEL transport and describes how to use and configure it in your services. The BPEL transport lets you bring Oracle BPEL Process Manager (Oracle BPEL PM) into your service oriented architecture (SOA) environment using Service Bus.

Note:

The BPEL transport (bpel-10g in the user interface) is for messaging with only Oracle SOA Suite 10g Release 3. Service Bus provides the SOA-DIRECT transport for use with SOA Suite 11g and later. For more information, see Using the SOA-DIRECT Transport.

This chapter contains the following sections:

• Introduction to the BPEL Transport

• BPEL Transport Simple Use Cases (Synchronous)

• Advanced Use Cases (Asynchronous)

• BPEL Transport Configuration Reference

• BPEL Transport Security

• BPEL Transport Error Handling

• WS-Addressing Reference

• Examples of XML Messaging with the BPEL Transport

34.1 Introduction to the BPEL Transport

Service Bus provides support for communication with Oracle BPEL Process Manager, letting you include BPEL processes in your service oriented architecture (SOA).

With Service Bus's native BPEL transport for Oracle BPEL PM, you can expose BPEL processes as web services in the service bus layer, letting other services invoke BPEL processes. Likewise, Oracle BPEL PM can call services in the service bus layer for use in its own processes.

The built-in integration between Service Bus and Oracle BPEL Process Manager is enabled at the Service Bus API level. This chapter focuses on this type of integration, but you are not limited to only these solutions. You can also use other standard communication protocols provided with Service Bus, such as HTTP, JMS, and File.

For detailed information on Oracle BPEL Process Manager, go to http://www.oracle.com/technetwork/middleware/bpel/overview/index.html.

34.1.1 SOAP Support with the BPEL Transport

Communication between Oracle BPEL Process Manager and Service Bus is done over SOAP only. Service Bus and Oracle BPEL PM do not provide full support for SOAP RPC encoding. The BPEL transport accepts SOAP RPC encoding bindings, but some encoding mechanisms, such as multiRef, might cause runtime failures.

The BPEL transport supports the following features:

• SOAP 1.1. SOAP 1.2 is supported only from Service Bus to Oracle BPEL PM using synchronous communication.

• SOAP headers

The BPEL transport has the following restrictions:

• No attachments

• No WS-Security or WS-RM

34.1.2 Transaction Propagation in the BPEL Transport

Oracle BPEL PM supports transaction propagation through its API, and the BPEL transport is transactional to support transaction propagation when Oracle BPEL PM is deployed on Oracle WebLogic Server. For example, if a process begins in a service outside of Oracle BPEL PM, Service Bus can propagate the transaction to Oracle BPEL PM through the BPEL transport to complete the transaction.

Transaction propagation is also supported from Oracle BPEL PM to Service Bus using an SB transport-based proxy service.

Note:

Transaction propagation is not yet supported for Oracle servers OC4J and Oracle AS and not yet certified on IBM WebSphere.

34.1.3 SSL Support in the BPEL Transport

Calls from Service Bus to Oracle BPEL PM are made using RMI, so the BPEL transport supports security at the call level through one-way SSL. For more information, see BPEL Transport Endpoint URI.

34.1.4 BPEL Transport Environment Values

The BPEL transport declares the environment variables listed in the following table, each of which corresponds to a property you specify when you configure a BPEL transport. You can update the values for environment variables when moving Service Bus projects among different deployment environments without having to update the transport configuration itself. For more information about environment values, see "Customizing Oracle Service Bus Environments" in Administering Oracle Service Bus.

Table 34-1 BPEL Transport Environment Variables

Environment Variable	Description
Dispatch Policy	Select the instance of WebLogic Server Work Manager that you want to use for the dispatch policy for this endpoint. The default Work Manager is used if no other Work Manager exists. For information about Work Managers, see: Using Work Managers with Service Bus "Using Work Managers to Optimize Scheduled Work" in Administering Server Environments for Oracle WebLogic Server
Service Account	A Service Bus service account resource to use for JNDI context security to access the Oracle BPEL Process Manager delivery service.
Endpoint URI	The URI of the service.

34.2 BPEL Transport Simple Use Cases (Synchronous)

This section describes the most common use cases for communicating to and from Oracle BPEL Process Manager through Service Bus. These represent simple synchronous one-way or request/response communication.

• Synchronous: Invoking Processes in Oracle BPEL Process Manager

• Synchronous: Calling External Services from Oracle BPEL Process Manager

• Associating Messages with the Correct Conversation

34.2.1 Synchronous: Invoking Processes in Oracle BPEL Process Manager

Figure 34-1 illustrates a synchronous communication pattern between a client and Oracle BPEL Process Manager through Service Bus.

Figure 34-1 Invoking Oracle BPEL Processes Synchronously Through Service Bus

Description of "Figure 34-1 Invoking Oracle BPEL Processes Synchronously Through Service Bus"

34.2.1.1 Creating and Configuring the Services

Use the following guidelines to invoke Oracle BPEL Process Manager processes from a client:

• Create a Service Bus business service that represents the BPEL process you want to invoke.

  • Create a WSDL-based business service. Generate the WSDL file from Oracle BPEL Process Manager.

  • Select the bpel-10g transport in the business service configuration.

  • Set the endpoint URI as described in Table 34-2.

  • Configure the remainder of the business service. See BPEL Transport Configuration Reference.

• Create a proxy service in Service Bus that accepts messages from the client.

• Create a pipeline in Service Bus that invokes the business service from the proxy service.

To ensure that messages are associated with the correct conversation, see Associating Messages with the Correct Conversation.

34.2.2 Synchronous: Calling External Services from Oracle BPEL Process Manager

Figure 34-2 illustrates a synchronous communication pattern between Oracle BPEL Process Manager and a service provider through Service Bus.

Figure 34-2 Oracle BPEL Processes Invoking a Service Synchronously Through Service Bus

Description of "Figure 34-2 Oracle BPEL Processes Invoking a Service Synchronously Through Service Bus"

34.2.2.1 Creating and Configuring the Services

Use the following guidelines to invoke an external service from Oracle BPEL Process Manager:

• Create a business service in Service Bus that represents the external service you want to invoke.

• Create a proxy service and its associated pipeline in Service Bus that invokes the business service.

  • You must create the proxy service with a SOAP WSDL file to invoke the business service. When defining your proxy service, select the WSDL service type, and select the desired port or binding.

  • Select the SB transport in the proxy service configuration.

  • To invoke the proxy service from Oracle BPEL Process Manager, export the proxy service's effective WSDL file and import it into your Oracle BPEL Process Manager development environment. Invoke the proxy service from Oracle BPEL Process Manager as you normally would.

  For configuration information, see the online help provided with Service Bus.

To ensure that messages are associated with the correct conversation, see Associating Messages with the Correct Conversation.

34.2.3 Associating Messages with the Correct Conversation

When using stateful services, the messages sent synchronously between Service Bus and Oracle BPEL Process Manager are known as a conversation. Oracle BPEL Process Manager supports the following mechanisms for ensuring that messages are correctly associated with each other as part of a conversation. These mechanisms are independent of each other, and you may choose to use both to ensure correct association.

• BPEL Correlation: BPEL correlation is part of the BPEL specification. When a WSDL-based business service in Service Bus sends a message to a BPEL process, the BPEL engine examines the message to find the target BPEL process instance.

• Opaque Correlation using WS-Addressing: When a conversation is initiated by a client through Service Bus to a BPEL process, the BPEL engine looks in the WS-Addressing SOAP header for the "messageID" value to use as the ID for the new conversation. The conversation ID is carried through the conversation as the "RelatesTo" value.

  For more information on WS-Addressing, see MessageID / RelatesTo in the WS-Addressing reference. For an example of conversation ID setting, see Conversation ID Examples.

34.3 Advanced Use Cases (Asynchronous)

This section describes more advanced use cases for communicating to and from Oracle BPEL Process Manager through Service Bus using asynchronous communication.

• Asynchronous: Invoking Processes in Oracle BPEL Process Manager

• Asynchronous: Calling Service Providers from Oracle BPEL Process Manager

34.3.1 Asynchronous: Invoking Processes in Oracle BPEL Process Manager

Figure 34-3 illustrates an asynchronous communication pattern between Oracle BPEL Process Manager and a service provider through Service Bus.

Figure 34-3 Invoking Oracle BPEL Processes Asynchronously Through Service Bus

Description of "Figure 34-3 Invoking Oracle BPEL Processes Asynchronously Through Service Bus"

In an asynchronous message exchange, a callback is sent on a different connection than the request.

34.3.1.1 Creating and Configuring the Services

Use the following guidelines to invoke Oracle BPEL Process Manager processes asynchronously from a client through Service Bus:

Create two proxy services in Service Bus with their associated pipelines. One that invokes the business service and another that handles the callback.

• Request Proxy Service and Pipeline: Since the callback will be sent on a different connection in asynchronous communication, you must establish the callback address in the request proxy. This callback address will be passed to the callback proxy and callback business services so that the message is sent back to the correct client.

  As part of the business service configuration, you select a callback proxy. At runtime, the BPEL transport uses this proxy as the callback proxy. For approaches to setting a callback address if you do not select a callback proxy in the business service, see WS-Addressing Reference and Asynchronous BPEL to BPEL Through Service Bus Example.

• Callback Proxy Service and Pipeline: Configure the proxy to use the WSDL SOAP or Any SOAP service type and the SB or HTTP transport. Use the SB transport if you want transaction propagation from Oracle BPEL Process Manager to Service Bus.

  If you select this proxy service as the business service's callback proxy, the BPEL transport provides the correct callback URI at runtime.

Create two business services in Service Bus: one that makes the request to the Oracle BPEL Process Manager process you want to interact with and another that handles the callback.

• Request Business Service: Create a WSDL-based business service. Generate the WSDL file from Oracle BPEL Process Manager. Select the WSDL service type, and select the appropriate binding or port in the WSDL file.

  • Select the bpel-10g transport in the business service configuration.

  • Set the role to Asynchronous Client.

  • Specify the endpoint URI, described in Table 34-2.

  • Use the Callback Proxy field on the BPEL transport configuration page to select the callback proxy you created.

• Callback Business Service: Configure the business process you need to handle the callback.

  See the online help provided with Service Bus for configuration information not covered in this guide.

34.3.2 Asynchronous: Calling Service Providers from Oracle BPEL Process Manager

This section describes the steps and configuration needed for Oracle BPEL Process Manager to make service calls through Service Bus.

Figure 34-4 illustrates an asynchronous communication pattern between Oracle BPEL Process Manager and a service provider through Service Bus.

Figure 34-4 Oracle BPEL Processes Invoking a Service Asynchronously Through Service Bus

Description of "Figure 34-4 Oracle BPEL Processes Invoking a Service Asynchronously Through Service Bus"

In an asynchronous message exchange, a callback is sent on a different connection than the request.

34.3.2.1 Creating and Configuring the Services

Use the following guidelines to invoke an external service asynchronously from Oracle BPEL Process Manager through Service Bus.

Create two proxy services and their associated pipelines in Service Bus: one for the request that invokes the business service and another that handles the callback.

• Request Proxy Service and Pipeline: Configure the proxy service to use the SB transport. Since the callback will be sent on a different connection in asynchronous communication, you must establish a callback address so the message is sent back to the correct client.

  For information on setting a callback address, see ReplyTo of the WS-Addressing reference and Asynchronous BPEL to BPEL Through Service Bus Example.

• Callback Proxy Service and Pipeline: Configure the proxy service to pass the callback address to the business service. The callback URI is provided in the request. Use URI rewriting to extract the callback URI and forward it to the business service.

  For proxy configuration details, see Creating and Configuring Proxy Services and Using the SB Transport.

Create two business services in Service Bus: a request business service that invokes the external service and a callback business service.

• Request Business Service: Configure the business service to invoke the external service.

• Callback Business Service: The callback business service receives the callback address from the callback proxy. The URI rewriting performed by the callback proxy service determines which BPEL process to send the response to.

  • Create a WSDL-based business service. Generate the WSDL file from Oracle BPEL Process Manager. Select the WSDL service type and select the appropriate binding or port in the WSDL file.

  • Select the bpel-10g transport in the business service configuration.

  • Set the Endpoint URI to bpel://callback, as described in Table 34-2. The callback URI is provided by the callback proxy service.

    Note:

    If the callback address is always known, for example when the client and BPEL service are linked together because of a trading partner agreement, you can provide the exact callback address in the callback business service instead of using bpel://callback.

  • Set the role to Service Callback on the bpel-10g transport configuration page, as described in Table 34-3.

  • Configure the remainder of the business service. See the online help provided with Service Bus for configuration information not covered in this document.

34.4 BPEL Transport Security

Security in Oracle BPEL Process Manager is handled at the EJB level. The BPEL transport supports a JNDI service account option used for the creation of the JNDI context and the EJB lookup.

This process is described in Table 34-3. The BPEL transport gets the user name and password from the service account. If the service account is not configured, an anonymous subject is assumed.

The BPEL transport also supports security at the call level by letting you indicate one-way SSL in the protocol portion of the URI from Service Bus to Oracle BPEL Process Manager. For more information, see BPEL Transport Endpoint URI.

34.4.1 Using SSL from Oracle Service Bus to Oracle Servers

To use SSL from Service Bus to OC4J and Oracle AS servers (using the ormis and opmns protocols), you must configure SSL on your Service Bus server by adding the following properties to your domain's setDomainEnv script:

-Djavax.net.ssl.trustStorePassword=passphrase
-Djavax.net.ssl.trustStore=file path to a keystore of trust certificate

34.5 BPEL Transport Error Handling

The BPEL transport handles Oracle BPEL Process Manager exceptions in different ways.

• Application Errors

• Connection Errors

• Other Errors

34.5.1 Application Errors

If a BPEL process replies with a fault, the BPEL transport intercepts the fault message at the API and translates it into a SOAP fault. The transport's automated application error-handling functionality lets you decide whether or not to automatically retry application errors—in this case BPEL faults—when they occur. For example, you may determine that application errors will always fail until the problem is fixed. Use the Retry Application Errors option on the transport configuration page to turn application retries on and off.

34.5.2 Connection Errors

Oracle BPEL Process Manager can throw the following non-fault exceptions, which the BPEL transport automatically categorizes as TransportException connection errors:

• NamingException

• RemoteException

The transport's automated connection error-handling functionality lets you determine if and how often connection errors are retried. Use the Retry Count and the Retry Iteration Interval options on the transport configuration page to control the number of retries and the number of seconds to wait between retries on connection errors. Setting Retry Iteration Interval to zero (0) means connection errors are not retried.

34.5.3 Other Errors

Other non-application and non-connection exceptions are re-thrown as generic TransportException errors.

34.6 WS-Addressing Reference

This section describes specific WS-Addressing properties that the BPEL transport uses to communicate with Oracle BPEL Process Manager.

This section also describes ways to provide callback addresses in asynchronous communication, as described in the Advanced Use Cases (Asynchronous) guidelines.

See Examples of XML Messaging with the BPEL Transport for WS-Addressing examples.

• ReplyTo

• MessageID / RelatesTo

34.6.1 ReplyTo

In asynchronous communication, a service callback is sent on a different connection than the request. As a service developer, you must supply the correct callback address in an asynchronous exchange so that the callback is sent to the correct client.

34.6.1.1 Calling a BPEL Process Asynchronously Through Service Bus

The BPEL transport provides a built-in mechanism for providing the correct callback address. When you create a BPEL business service in Service Bus, you can select a callback proxy to handle the callback, and the BPEL transport automatically sets the correct callback address. You do not need to manually use "ReplyTo."

For more information, see Asynchronous: Invoking Processes in Oracle BPEL Process Manager.

34.6.1.2 BPEL Processes Calling External Services Through Service Bus

When calling an external service from Oracle BPEL Process Manager through Service Bus, you must manually set a callback address. To do this using WS-Addressing, in the request proxy service set the callback address as the "ReplyTo" value. The BPEL transport in the business service uses that URI as the callback address.

For more information, see Asynchronous: Calling Service Providers from Oracle BPEL Process Manager.

34.6.2 MessageID / RelatesTo

"MessageID" and "RelatesTo" are used to store the conversation ID in conversations between Service Bus and Oracle BPEL Process Manager, making sure related messages remain in the same conversation. The BPEL transport does not let you specify whether a given operation is a start or continue operation. Instead, the BPEL transport looks for the "MessageID" and "RelatesTo" properties and sets them accordingly.

The following describes how the BPEL transport uses "MessageID" and "RelatesTo" in synchronous and asynchronous conversations:

• Synchronous conversation: In the initial request, the "MessageID" determines the conversation ID. In the remaining communication, the BPEL transport provides the conversation ID as the RelatesTo value.

  If there is no value assigned to "MessageID" or "RelatesTo," the transport assumes either no conversation is occurring or that Oracle BPEL Process Manager is handling the correlation.

• Asynchronous callbacks: In the initial request, the "MessageID" determines the conversation ID. In the remaining communication, the BPEL transport provides the conversation ID as the "RelatesTo" value in the callback.

  If there is no value assigned to "MessageID" or "RelatesTo," the transport assumes either no conversation is occurring or that Oracle BPEL Process Manager is handling the correlation.

For more implementation on establishing a conversation ID to make sure messages participate in the correct conversation, see Associating Messages with the Correct Conversation and the Conversation ID Examples.

34.7 Examples of XML Messaging with the BPEL Transport

This section provides examples of XML messaging issues between Service Bus and Oracle BPEL Process Manager.

• Conversation ID Examples

• Asynchronous BPEL to BPEL Through Service Bus Example

34.7.1 Conversation ID Examples

This section provides different examples of establishing a conversation ID among messages in a conversation between Service Bus and Oracle BPEL Process Manager.

In Figure 34-5, a client is synchronously invoking a process in Oracle BPEL Process Manager. The business service (BS1) uses the BPEL transport to invoke a process. The pipeline (PP1) handles any necessary conversation ID mapping and passes the messages from the proxy service (PS1) to the business service.

Figure 34-5 Operations in a Synchronous Exchange Through Service Bus

Description of "Figure 34-5 Operations in a Synchronous Exchange Through Service Bus"

34.7.1.1 Port and Message Definitions

The examples in this section use the following port and message definitions defined in the WSDL file.

<wsdl:types>
    <xsd:schema
            targetNamespace="http://www.sample.org/spec/samples/types"
            elementFormDefault="qualified">
        <xsd:complexType name="ValueHolder">
            <xsd:all>
                <xsd:any minOccurs="1"/>
            </xsd:all>
        </xsd:complexType>
    </xsd:schema>
</wsdl:types>
<message name="create"/>
<message name="putRequest">
    <part name="key" type="xsd:string"/>
    <part name="value" type="types:ValueHolder"/>
</message>
<message name="putResponse">
    <part name="value" type="types:ValueHolder"/>
</message>
...
<message name="dispose"/>
<portType name="ServiceMap">
    <operation name="create">
        <input message="tns:create"/>
    </operation>
    <operation name="put">
        <input message="tns:putRequest"/>
        <output message="tns:putResponse"/>
    </operation>
    ...
    <operation name="dispose">
        <input message="tns:dispose"/>
    </operation>
</portType>

34.7.1.2 WS-Addressing that Sets the Conversation ID

This example shows how WS-Addressing is used to set the conversation ID among messages in a conversation. Figure 34-5 shows communication pattern.

Create Operation

<soap:Envelope>
    <soap:Header>
        <wsa03:MessageID>uuid:123456789</wsa03:MessageID>
    </soap:Header>
    <soap:Body>
        <create/>
    </soap:Body>
</soap:Envelope>

Put Operation

<soap:Envelope>
    <soap:Header>
        <wsa03:MessageID>uuid:111111111</wsa03:MessageID>
        <wsa03:RelatesTo>uuid:123456789</wsa03:RelatesTo>
    </soap:Header>
    <soap:Body>
        <put>
            <key>key</key>
            <value>
                <PO/>
            </value>
        </put>
    </soap:Body>
</soap:Envelope>
<soap:Envelope>
    <soap:Body>
        <putResponse>
            <value/>
        </putResponse>
    </soap:Body>
</soap:Envelope>

The <put> operation also has a MessageID, but it is ignored because the RelatesTo has a value that provides the conversation ID.

34.7.1.3 Message Payload Data that Sets the Conversation ID

This example shows how message payload data can be used to set the conversation ID among messages in a conversation. In these examples, the proxy service maps the ID to the MessageID / RelatesTo SOAP headers. Figure 34-5 shows communication pattern.

Create Operation

Client to proxy service

<soap:Envelope>
    <soap:Body>
        <create/>
    </soap:Body>
</soap:Envelope>
<soap:Envelope>
    <soap:Body>
        <createResponse>
            <mapID>uuid:123456789</mapID>
        </createResponse>
    </soap:Body>
</soap:Envelope>

Proxy service to BPEL process (using a business service)

<soap:Envelope>
    <soap:Header>
        <wsa03:MessageID>uuid:123456789</wsa03:MessageID>
    </soap:Header>
    <soap:Body>
        <create/>
    </soap:Body>
</soap:Envelope>

Not shown: The ID was generated in the request of the proxy service pipeline and inserted as a <wsa03:MessageID> before invoking the process. On the process side, the create operation is one-way, so a SOAP response must be created before replying to the client. The response sends back the ID that was generated by the proxy service.

Put Operation

Client to proxy service

<soap:Envelope>
    <soap:Body>
        <put>
            <mapID>uuid:123456789</mapID>
            <key>key</key>
            <value>
                <PO/>
            </value>
        </put>
    </soap:Body>
</soap:Envelope>
<soap:Envelope>
    <soap:Body>
        <putResponse>
            <value/>
        </putResponse>
    </soap:Body>
</soap:Envelope>

Proxy service to BPEL process (using a business service)

<soap:Envelope>
    <soap:Header>
        <wsa03:RelatesTo>uuid:123456789</wsa03:RelatesTo>
    </soap:Header>
    <soap:Body>
        <put>
            <key>key</key>
            <value>
                <PO/>
            </value>
        </put>
    </soap:Body>
</soap:Envelope>
<soap:Envelope>
    <soap:Body>
        <putResponse>
            <value/>
        </putResponse>
    </soap:Body>
</soap:Envelope>

Dispose Operation

Client to proxy service

<soap:Envelope>
    <soap:Body>
        <dispose>
            <mapID>uuid:123456789</mapID>
        </dispose>
    </soap:Body>
</soap:Envelope>

Proxy service to BPEL process (using a business service)

<soap:Envelope>
    <soap:Header>
        <wsa03:RelatesTo>uuid:123456789</wsa03:RelatesTo>
    </soap:Header>
    <soap:Body>
        <dispose/>
    </soap:Body>
</soap:Envelope>

34.7.1.4 Transformation Examples

In these examples, the client uses a more recent version of the WS-Addressing spec (wsa04 prefix). The proxy service is responsible for transforming the SOAP headers to use the wsa03 prefix. The proxy service developer configures the transformation. Figure 34-5 shows communication pattern.

Create Operation

Client to proxy service

<soap:Envelope>
    <soap:Header>
        <wsa04:MessageID>uuid:123456789</wsa04:MessageID>
    </soap:Header>
    <soap:Body>
        <create/>
    </soap:Body>
</soap:Envelope>

Proxy service to BPEL process (using a business service)

<soap:Envelope>
    <soap:Header>
        <wsa03:MessageID>uuid:123456789</wsa03:MessageID>
    </soap:Header>
    <soap:Body>
        <create/>
    </soap:Body>
</soap:Envelope>

Put Operation

Client to proxy service

<soap:Envelope>
    <soap:Header>
        <wsa04:MessageID>uuid:111111111</wsa04:MessageID>
        <wsa04:RelatesTo>uuid:123456789</wsa04:RelatesTo>
    </soap:Header>
    <soap:Body>
        <put>
            <key>key</key>
            <value>
                <PO/>
            </value>
        </put>
    </soap:Body>
</soap:Envelope>
<soap:Envelope>
    <soap:Body>
        <putResponse>
            <value/>
        </putResponse>
    </soap:Body>
</soap:Envelope>

Proxy service to BPEL process (using a business service)

<soap:Envelope>
    <soap:Header>
        <wsa03:MessageID>uuid:111111111</wsa03:MessageID>
        <wsa03:RelatesTo>uuid:123456789</wsa03:RelatesTo>
    </soap:Header>
    <soap:Body>
        <put>
            <key>key</key>
            <value>
                <PO/>
            </value>
        </put>
    </soap:Body>
</soap:Envelope>
<soap:Envelope>
    <soap:Body>
        <putResponse>
            <value/>
        </putResponse>
    </soap:Body>
</soap:Envelope>

34.7.2 Asynchronous BPEL to BPEL Through Service Bus Example

The following example shows the SOAP headers involved in one BPEL process invoking another BPEL process asynchronously through Service Bus. In Figure 34-6, PP1 and PP2 are pipelines that perform transformations and pass messages from PS1 and PS2 proxy services to BS1 and BS2 business services. The business services are required to make calls to BPEL processes using the BPEL transport.

Figure 34-6 One BPEL Process Invoking Another BPEL Process Through Service Bus

Description of "Figure 34-6 One BPEL Process Invoking Another BPEL Process Through Service Bus"

Refer to Figure 34-6 for the following SOAP header examples.

34.7.2.1 Port and Message Definitions

<message name="LoanServiceRequestMessage">
    <part name="payload" element="types:loanApplication"/>
</message>
<message name="LoanServiceResultMessage">
    <part name="payload" element="types:loanOffer"/>
</message>
<portType name="LoanService">
    <operation name="initiate">
        <input message="tns:LoanServiceRequestMessage"/>
    </operation>
</portType>
<portType name="LoanServiceCallback">
    <operation name="onResult">
        <input message="tns:LoanServiceResultMessage"/>
    </operation>
</portType>

34.7.2.2 BP1 to P1 – Initiate operation

<soap:Envelope>
    <soap:Header>
        <wsa03:ReplyTo>
            <wsa03:Address>ormi://serverB:7001/default/AmericanLoanClient/1.0/service/LoanServiceRequester
            </wsa03:Address>
        </wsa03:ReplyTo>
        <MessageID>AmericanLoanClient~1.0/60007</MessageID>
    </soap:Header>
    <soap:Body >
        <loanApplication>
            ...
        </loanApplication>
    </soap:Body>
</soap:Envelope>

34.7.2.3 P1/B1 to BP2

<soap:Envelope>
    <soap:Header>
        <wsa03:ReplyTo>
            <wsa03:Address>http://serverB:7001/P2</wsa03:Address>
            <wsa03:ReferenceProperties>
                <osb:Callback>
                    <osb:Address>
ormi//localhost/default/AmericanLoanClient/1.0/service/LoanServiceRequester
                    </osb:Address>
                </osb:Callback>
            </wsa03:ReferenceProperties>
        </wsa03:ReplyTo>
        <MessageID>AmericanLoanClient~1.0/60007</MessageID>
    </soap:Header>
    <soap:Body >
        <loanApplication>
            ...
        </loanApplication>
    </soap:Body>
</soap:Envelope>

The ReplyTo callback address is set by B1, which gets the value from the Callback Proxy field in the BPEL transport configuration, as described in Table 34-2. B1's callback proxy is P2.

You must wrap the original replyTo information and send it as reference properties so that it is echoed back in the onResult callback message (to follow).

Note:

This sample uses osb:Callback and osb:Address for illustration purpose only. There is no standard or Service Bus standard elements defined for WS-Addressing support.

34.7.2.4 BP2 to P2 – onResult operation

<soap:Envelope>
    <soap:Header>
        <wsa03:RelatesTo>AmericanLoanClient~1.0/60007</wsa03:RelatesTo>
        <osb:Callback>
            <osb:Address>ormi//localhost/default/AmericanLoanClient/1.0/service/LoanServiceRequester
            </osb:Address>
        </osb:Callback>
    </soap:Header>
    <soap:Body >
        <loanOffer>
            ...
        </loanOffer>
    </soap:Body>
</soap:Envelope>

The reference property osb:Callback is sent back as a SOAP header by the Oracle BPEL Process Manager engine.

34.7.2.5 P2/B2 to BP1 – onResult operation

<soap:Envelope>
    <soap:Header>
        <wsa03:RelatesTo>AmericanLoanClient~1.0/60007</wsa03:RelatesTo>
    </soap:Header>
    <soap:Body >
        <loanOffer>
            ...
        </loanOffer>
    </soap:Body>
</soap:Envelope>

Proxy service P2 removes the temporary osb:Callback header; but prior to deleting this header, the replyTo address value is copied to the $outbound variable so that the BPEL transport in business service B2 can send the callback message to the correct BPEL process.

34.8 BPEL Transport Configuration Reference

This section provides descriptions for BPEL transport-specific properties for business and proxy services.

• BPEL Transport Endpoint URI

• Configuring Business Services to Use the BPEL Transport

34.8.1 BPEL Transport Endpoint URI

Table 34-2 describes the URI formats for the BPEL transport, which you configure on the main Transport page of the business service in either JDeveloper or the Oracle Service Bus Console.

Table 34-2 Specifying an Endpoint URI

Transport Role	Endpoint URI Format
Synchronous Client or Asynchronous Client role	For the following endpoint URI format, optional elements are shown in square brackets. protocol://host[:port][/protocol-path]/domain/process[/version[/partnerlink/role Following are descriptions of the other endpoint URI elements: protocol: Use one of the following RMI / JNDI protocols. iiop / iiops: For generic, server-agnostic use. t3 / t3s: For use with Oracle WebLogic Server. http / https: For tunneling and use with Oracle WebLogic Server. ormi / ormis: For stand-alone deployment on OC4J (Oracle Container for JEE). port: Optional. For the ormi and opmn protocols only, if the server is configured to use the default port. protocol-path: Optional. For use only with the opmn and opmns protocols. The protocol-path is the server instance in a cluster. version: Optional. The version of the process to invoke. partnerlink/role: Optional. Include this option for a full path description when you specify version. For a cluster, you can also use the following URI format for targeting specific nodes in the cluster: protocol://host1:port1,host2:port2/<remainder_of_URI>
Service Callback	If the callback address is always known, for example when the client and BPEL service are linked together because of a trading partner agreement, you can provide the exact callback address for the Endpoint URI instead of using the following format: bpel://callback

34.8.2 Configuring Business Services to Use the BPEL Transport

Table 34-3 describes the options available on the BPEL transport configuration page of the business service in both JDeveloper and the Oracle Service Bus Console. For more information, see Creating and Configuring Business Services.

Table 34-3 BPEL Transport Properties for Business Services

Property	Description
Role	Select one of the following roles for the business service. The BPEL transport is used to send request messages from Service Bus to Oracle BPEL PM. Each role requires specific configuration. The business service can serve one of the following roles: Synchronous Client: Select this role for synchronous communication with a Service Bus client. The only required location information is the BPEL address. This address is captured statically as the endpoint URI or dynamically through URI rewriting. Asynchronous Client: Select this role for asynchronous communication with a Service Bus client. In this case, a callback from Oracle BPEL Process Manager to Service Bus is sent on a different connection than the request, and you must configure Service Bus to provide the correct callback address in the Callback Proxy field. For more information, see the guidelines in Advanced Use Cases (Asynchronous). Service Callback: Select this role if the business service is designed to be a service callback to Oracle BPEL Process Manager (where Oracle BPEL Process Manager is calling an external service asynchronously through Service Bus). The callback address is known only at runtime. Use an Endpoint URI of bpel://callback. If you configure the business service with the marker URI, configure your pipeline logic to dynamically set the URI on $outbound. For example, you could use the TransportHeader action to do this. Note: A Service Callback business service does not support load balancing or failover. For instructions on using Service Callback, see "Service Callback" in Table 34-2 and Asynchronous: Calling Service Providers from Oracle BPEL Process Manager.
Callback Proxy	For asynchronous clients only, enter the proxy service to use to route callbacks to the Service Bus client that made the request. The proxy service must be either an SB or HTTP proxy service with a service type of Any SOAP. For more information, see the guidelines in Advanced Use Cases (Asynchronous). This field is available only for the Asynchronous Client role.
Service Account	Enter a service account that will be used for JNDI context security to access the Oracle BPEL Process Manager delivery service. If no service account is specified, an anonymous subject is used. There is no restriction on the type of service account that can be configured, such as static or pass-through, but the runtime must be able to access a user name and password. For more information, see Working with Service Accounts.
Suspend Transaction	Select this option to make the business service non-transactional even if the business service is invoked by a transaction. If you do not select Suspend Transaction, the following rules apply: If the protocol indicates a protocol supported by WebLogic Server (t3, iiop, http), the transaction is propagated. If the protocol indicates an OC4J server (ormi, opmn), the BPEL transport throws an exception, since OC4J does not support transaction propagation. The BPEL transport ignores the Suspend Transaction setting in the following situations: The business service is called with quality of service (QoS) "best-effort." The BPEL transport automatically suspends any transaction that does not support QoS. The business service is called with QoS set to "exactly-once" and there is no transaction. For a description of transaction propagation, see Transaction Propagation in the BPEL Transport.
Dispatch Policy	Select the instance of WebLogic Server Work Manager that you want to use for the dispatch policy for this endpoint. The default Work Manager is used if no other Work Manager exists. For information about Work Managers, see: Using Work Managers with Service Bus "Using Work Managers to Optimize Scheduled Work" in Administering Server Environments for Oracle WebLogic Server