WSO2 Business Process Server v3.0.1 Documentation

##### Overview

- Home
- Release Note
- WS-BPEL Compliance
- License

##### Downloads

- Releases

##### Installation Guide

- Installing WSO2 BPS

##### Quick Start Guide

- Modeling the process
- Deploying the process
- Testing the process

##### User Guide

- Deploying BPEL Processes
- Deploying Human Tasks
- Managing BPEL processes
- Managing BPEL process instances
- QoS for BPEL processes
- Securing BPEL processes
- Invoking secured partner services
- Versioning
- Management API

##### Human Task Guide

- Human Tasks Quick Start Guide
- Deploying HumanTasks
- Managing Tasks
- Developing a Human Task Artifact
- Human Task Management and Configuration
- Human Task Concepts

##### Administrator Guide

- External data sources Configuration
- Registry Configuration
- Events
- Unified Endpoints
- BPEL Extensions
- Transaction Factory Configuration
- Message Exchange Interceptors
- OpenJPA specific properties
- JMS Transport Configuration
- Process Instance Cleanup Tasks
- Process Hydration and Dehydration
- Enabling Peer-to-Peer(P2P) Communication
- Setting up a BPS Cluster

##### Best Practices

- Process Deployment Best Practices

##### Concepts

- Process Versioning
- Process instance events
- Partner links

##### WS-BPEL Extensions

- Activity Failure and Recovery
- Extension Activities and Extensible Assign Operations
- XPath Extensions
- Iterable ForEach
- Flexible Assigns
- BPEL4People Extension

##### Samples

- HelloWorld
- If-Else
- ForEach
- While
- Repeat Until
- Flow and Links
- Pick
- Synchronous and Asynchronous Service Invocations
- Fault Handling
- Split
- XslTransform
- Compensation Handler
- Event Handler

##### Resources

- FAQ
- External Articles
- Library
- Source Code

##### Community

- Forum
- Mailing Lists

##### Project Information

- Issue Tracking

# Sample Guide - Synchronous and Asynchronous Service Invocations

### Table of Content

- Objective
- Prerequisites
- Overall Idea

### Objective

Explain how synchronous and asynchronous interactions can be handled via BPEL.

Let's understand what's meant by synchronous and asynchronous in BPEL terms. BPEL processes can also be categorized based on how it invokes an operation of a partner service: synchronous and asynchronous. However, it is not possible to use both methods when invoking a partner service's operation, as it is dependent on the type of partner service operation also.

Asynchronous interaction - Suppose a BPEL process invokes a partner service. After this invokation of the partner process, the BPEL process will continue to carry on with its execution process while that partner service completes performing its operation. The BPEL process will receive a response from the partner service, when the partner service is completed.

Synchronous interaction - Suppose a BPEL process invokes a partner service. The BPEL process then waits for the partner service's operation to be completed, and responded. After receiving this completion response from the partner service, the BPEL process will continue to carry on its execution flow. This transmission does not apply for the In-Only operations defined in the WSDL of the partner service.

Usually you'll use asynchronous services for long-lasting operations and synchronous services for operations that return a result in a relatively short time. Typically, when you use asynchronous Web services, the BPEL process too is asynchronous.

Let's take an example where there are both synchronous and asynchronous interactions. Suppose a loan approval process, where the client request for a loan with required documents. Then the service party first retrieve the customer information and his history using `CustomerInfo` service, then the service party calculate the credit rate using Credit rating service. Then service party finally send a request to `DILoanService` with previously retrieved the client history and the credit rating where the final decision from `DILoanService` may take a longer time. So we invoke `DILoanService` asynchronously.

So what's the difference between Asynchronous and Synchronous interactions?

Here when invoking a service asynchronously, we need to define two roles(`myRole` and `partnerRole`) for the partner link. In a synchronous interaction only `partnerRole` is need to be defined.

These roles which are defined in partner link type. And they maps to particular port types. A partner link type binds two port types; port type process offers(`myRole`) to a partner and port type partner offers(`partnerRole`) to a process. In the above example `DILoanService` is invoked asynchronously and `DILoanService` has to provide a`portType`, which defines the `partnerRole` and another `portType` which defines`myRole`.

### Prerequisites

- Log in into BPS server admin console.
- Under Business Processes -> Add BPEL.
- Upload the LoanProcess.zip , (all samples are located at our sample repository.)
- Under the Business Processes -> Processes.
- Under the WSDL details widget -> Create instance

- Note - SampleAsynchronousProcess which is solely intended on implementing an asynchronous invocation, can also be referred.

### Overall Idea

Refer LoanProcess.zip

- #### How synchronous interaction works.

  In LoanProcess.bpel,

      <invoke name="InvokeCustomerInfo" partnerLink="CustomerInfoPL" operation="getCustomerSSN"
              portType="ns1:CustomerInfoPortType" inputVariable="customerInfoInput"
              outputVariable="customerInfoOutput"/>

  Synchronous interaction is pretty simple compared to asynchronous interaction where correlations need to be defined and <receive/> retrieves the response from the invoked service operation.

  To get a detailed view on how this done, refer http://wso2.org/library/articles/writing-simple-ws-bpel-process-wso2-bps-apache-ode#invoke-partner-service.

#### How asynchronous interaction works.

In LoanService.bpel

    <invoke name="Invoke" partnerLink="DILoanServicePL" operation="getLoanOffer"
            portType="ns2:LoanServicePortType" inputVariable="diLoanServiceRequest"/>
    <receive name="ReceiveDILoanService" createInstance="no" partnerLink="DILoanServicePL"
             operation="onLoanOffer" portType="ns2:LoanServiceCallbackPortType"
             variable="diLoanServiceResponse">
    <correlations>
        <correlation set="correlator" initiate="no"></correlation>
    </correlations>
    </receive>

In this interaction, two separate activities manage request sending and response retrieving from the external service. <invoke/> handles external service execution and <receive/> manages the service response.

Let's figure out what's meant by each parameter.

    <invoke name="Invoke" partnerLink="DILoanServicePL" operation="getLoanOffer"
            portType="ns2:LoanServicePortType" inputVariable="diLoanServiceRequest"/>

- `partnerLink="DILoanServicePL"`

  This partner link is defined at <partnerLinks/> in the BPEL.

      <partnerLinks>
          <partnerLink name="DILoanServicePL" partnerLinkType="ns2:LoanServicePT"
                       partnerRole="LoanServiceRole"
                       myRole="LoanServiceClientRole"/>
      </partnerLinks>

  The two roles, are defined at `LoanServicePT` partner link type.

  eg - In LoanService.wsdl

      <plnk:partnerLinkType name="LoanServicePT">
          <plnk:role name="LoanServiceRole" portType="tns:LoanServicePortType"/>
          <plnk:role name="LoanServiceClientRole" portType="tns:LoanServiceCallbackPortType"/>
      </plnk:partnerLinkType>

  The assigned `portType` for each role is in-only portTypes which each provides the operation to handle the request or to send the response.

  In LoanService.wsdl

      <portType name="LoanServicePortType">
          <operation name="getLoanOffer">
              <input name="input" message="tns:getLoanOfferRequest"/>
          </operation>
      </portType>
      <portType name="LoanServiceCallbackPortType">
          <operation name="onLoanOffer">
              <input name="input" message="tns:getLoanOfferResponse"/>
          </operation>
      </portType>

- `operation="getLoanOffer"` & `portType="ns2:LoanServicePortType"`

  operation determines which operation to be invoked in the particular WSDL's `portType`, which was determined by `partnerLink` attribute previously.

- `inputVariable="diLoanServiceRequest"`

  values of this attribute determines the incoming messages for the partner Web service. So the variable specified by the inputVariable attribute value must be compatible with the message type specified in the <wsdl:input /> element of the particular WSDL's operation.

As mentioned <receive/> manages the service response. Let's understand the functionality of each parameter and <correlations/>.

eg - In LoanProcess.bpel

    <receive name="ReceiveDILoanService" createInstance="no" partnerLink="DILoanServicePL"
             operation="onLoanOffer" portType="ns2:LoanServiceCallbackPortType"
             variable="diLoanServiceResponse">
        <correlations>
            <correlation set="correlator" initiate="no"></correlation>
        </correlations>
    </receive>

- `createInstance="no"`

  determines whether to create a process instance when a message is received, or not.

- `partnerLink="DILoanServicePL"`

  an essential attribute in a <receive /> element. This determines the WSDL's portType to be chosen based on the partnerLinkType attribute and the myRole attributes defined in the particular <partnerLink /> element.

  eg - In LoanService.bpel

      <partnerLinks>
          <partnerLink name="DILoanServicePL" partnerLinkType="ns2:LoanServicePT"
                       partnerRole="LoanServiceRole"
                       myRole="LoanServiceClientRole"/>
      </partnerLinks>
              .........
      <receive name="ReceiveDILoanService" createInstance="no" partnerLink="DILoanServicePL"
               operation="onLoanOffer" portType="ns2:LoanServiceCallbackPortType"
               variable="diLoanServiceResponse">
          <correlations>
              <correlation set="correlator" initiate="no"></correlation>
          </correlations>
      </receive>

- `operation="onLoanOffer"` and `portType="ns2:LoanServiceCallbackPortType"`

  an essential attribute and determines which operation's message is the matching input message.

- `variable="diLoanServiceResponse"`

  where the incoming message will be stored as a BPEL process variable for further manipulation in the BPEL process execution. This variable should be defined in a <variable /> inside <variables /> element.

- `<correlation set="correlator" initiate="no"></correlation>`

  In asynchronous service invocation, correlation is compulsory to define, as it used to correlate the outgoing message from <invoke/> and incoming message to <receive/>. In this particular example, messages are correlated by CustomerID.

  eg - In LoanProcess.wsdl

      <bpws:propertyAlias
              propertyName="tns:correlatorProp"
              messageType="ns1:getLoanOfferResponse"
              part="part">
          <bpws:query>/ns:CustomerInfo/ns:CustomerID</bpws:query>
      </bpws:propertyAlias>