Objective
This sample explains how synchronous and asynchronous interactions can be handled via BPEL.
Introducing Synchronous and Asynchronous Invocations
BPEL processes can be categorized based on how they invoke 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 the partner service operation also.
Asynchronous Interaction
Suppose a BPEL process invokes a partner service. After this invocation, the BPEL process continues to carry on with its execution process while that partner service completes performing its operation. The BPEL process receives 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 continues 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 asynchronous services are used for long-lasting operations and synchronous services for operations that return a result in a relatively short time. Typically, when asynchronous Web services are used, the BPEL process too is asynchronous.
Consider an example where there are both synchronous and asynchronous interactions where . Suppose a loan approval process allows the client to request for a loan with required documents. Then the service party first retrieves the customer information and his history using CustomerInfo service. Then the service party calculates the credit rate using credit rating service. It finally sends a request to DILoanService with previously-retrieved client history, and the credit rating where the final decision from DILoanService may take a longer time. So we invoke DILoanService asynchronously.
The following diagram depicts this scenario.
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 are defined in partner link type and they map 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 aportType, which defines the partnerRole and another portType which definesmyRole.
Deploying the Sample
WSO2 BPS provides a sample, which can be deployed and executed to understand the constructs. Follow the instructions below to deploy and trigger the process.
1. Log in into BPS server management console and select "Processes -> Add" under the "Main" menu.
2. Upload the LoanProcess.zip. (Samples are located at our sample repository).
3. In the "Deployed Processes" window, click the "Process ID" to access its "Process Information" window.
4. Under the "WSDL Details" widget, trigger the process using the "TryIt" link to create an instance of it.
Example Usage
Refer LoanProcess.zip when going through the following descriptions.
How synchronous interaction works
In LoanProcess.bpel, the following snippet is given.
<invokename="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 to the following article in WSO2 Oxygen Tank: http://wso2.org/library/articles/writing-simple-ws-bpel-process-wso2-bps-apache-ode#invoke-partner-service.
How asynchronous interaction works
In LoanService.bpel, the following snippet is given.
<invokename="Invoke"partnerLink="DILoanServicePL"operation="getLoanOffer"portType="ns2:LoanServicePortType"inputVariable="diLoanServiceRequest"/><receivename="ReceiveDILoanService"createInstance="no"partnerLink="DILoanServicePL"operation="onLoanOffer"portType="ns2:LoanServiceCallbackPortType"variable="diLoanServiceResponse">
<correlations>
<correlationset="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 analyze what's meant by each parameter.
<invokename="Invoke"partnerLink="DILoanServicePL"operation="getLoanOffer"portType="ns2:LoanServicePortType"inputVariable="diLoanServiceRequest"/>
1. partnerLink="DILoanServicePL" - This partner link is defined at <partnerLinks/> in the BPEL.
<partnerLinks>
<partnerLinkname="DILoanServicePL"partnerLinkType="ns2:LoanServicePT"partnerRole="LoanServiceRole"myRole="LoanServiceClientRole"/></partnerLinks>
The two roles, are defined at LoanServicePT partner link type. For example, in LoanService.wsdl
<plnk:partnerLinkTypename="LoanServicePT">
<plnk:rolename="LoanServiceRole"portType="tns:LoanServicePortType"/>
<plnk:rolename="LoanServiceClientRole"portType="tns:LoanServiceCallbackPortType"/>
</plnk:partnerLinkType>
The assigned portType for each role is in-only portTypes where each provides the operation to handle the request or to send the response. In LoanService.wsdl
<portTypename="LoanServicePortType"><operationname="getLoanOffer"><inputname="input"message="tns:getLoanOfferRequest"/></operation></portType><portTypename="LoanServiceCallbackPortType"><operationname="onLoanOffer"><inputname="input"message="tns:getLoanOfferResponse"/></operation></portType>
2. 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.
3. inputVariable="diLoanServiceRequest" - Values of this attribute determine 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/>. For example, in LoanProcess.bpel,
<receivename="ReceiveDILoanService"createInstance="no"partnerLink="DILoanServicePL"operation="onLoanOffer"portType="ns2:LoanServiceCallbackPortType"variable="diLoanServiceResponse"><correlations><correlationset="correlator"initiate="no"></correlation></correlations></receive>
4. createInstance="no" - Determines whether to create a process instance when a message is received, or not.
5. 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. For example, in LoanService.bpel,
<partnerLinks><partnerLinkname="DILoanServicePL"partnerLinkType="ns2:LoanServicePT"partnerRole="LoanServiceRole"myRole="LoanServiceClientRole"/></partnerLinks> ......... <receivename="ReceiveDILoanService"createInstance="no"partnerLink="DILoanServicePL"operation="onLoanOffer"portType="ns2:LoanServiceCallbackPortType"variable="diLoanServiceResponse"><correlations><correlationset="correlator"initiate="no"></correlation></correlations></receive>
6. operation="onLoanOffer" and portType="ns2:LoanServiceCallbackPortType" - An essential attribute and determines which operation's message is the matching input message.
7. 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.
8. <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. In LoanProcess.wsdl,
<bpws:propertyAliaspropertyName="tns:correlatorProp"messageType="ns1:getLoanOfferResponse"part="part"><bpws:query>/ns:CustomerInfo/ns:CustomerID</bpws:query></bpws:propertyAlias>