Doron Sherman

BPEL4WS is now moving rapidly into becoming the de facto standard for Web service orchestration with most platform vendors following in IBM and Microsoft footsteps after the submission of the specification to OASIS. This increased momentum and visibility will drive a great need for educating developers on how to put BPEL to work.

This article illustrates a payment flow example coded using BPEL, highlighting some of the main constructs of the language and demonstrating how the flow can be monitored and managed once it is deployed. The example can be extended in various ways to include more advanced language constructs. Such extensions will be illustrated in subsequent articles.

Business Flow Example

The PayFlow business flow example illustrated in this article is comprised of a client initiating a request to a BPEL process and ending with the process calling back the client with the result of the payment request (receipt). The process includes use of <receive> and <invoke> activities for interacting with the outside world which includes the client (request) and a partner (payment processor service). XML Variables are used for holding messages exchanged between the process and the partners. To make this example interesting, the payment processor service is asynchronous and can take anywhere from several minutes to several days before the service calls back the process. Another interesting element demonstrated by this example is the handling of exceptions and managing of timeouts. These constructs are instrumental to enable a BPEL process to deliver reliable business flows.

The payment processor service, as implemented, will return a normal result if the amount is less than $500. Otherwise, it will return a "transfer refused" fault, which will be handled as an exception by the PayFlow BPEL process. PayFlow also handles an "insufficient funds" fault, which may be thrown by the service. In addition, the PayFlow process specifies a timeout period and terminates if the payment processor takes more than 2 days (the timeout limit) to return a digital receipt indicating a successful fund transfer.

Creating Service Descriptions with WSDL

PaymentProcessor WSDL file

The asynchronous payment processor service provides the following operations: initiate, getStatus and pollResult, grouped under the PaymentProcessorService portType.

<portType name="PaymentProcessorService">
<operation name="initiate">
<input message="tns:initiatePaymentProcessorServiceSoapRequest" />
<output message="tns:initiatePaymentProcessorServiceSoapResponse" />
</operation>
<operation name="getStatus">
<input message="tns:getPaymentProcessorServiceStatusSoapRequest" />
<output message="tns:getPaymentProcessorServiceStatusSoapResponse" />
</operation>
<operation name="pollResult">
<input message="tns:pollPaymentProcessorServiceResultSoapRequest" />
<output message="tns:pollPaymentProcessorServiceResultSoapResponse" />
</operation>

The payment processor service also provides the operations onResult, onInsufficientFundException and onTransferRefusedException, grouped under the PaymentProcessorServiceCallback portType. Note that these callback operations will actually be invoked on the client of the service - in this case the PayFlow process.

<portType name="PaymentProcessorServiceCallback">
<operation name="onResult">
<input message="tns:onPaymentProcessorServiceResultSoapRequest" />
<output message="tns:onPaymentProcessorServiceResultSoapResponse" />
</operation>
<operation name="onInsufficientFundException">
<input message="tns:onInsufficientFundExceptionPaymentProcessorServiceSoapRequest" />
<output message="tns:onInsufficientFundExceptionPaymentProcessorServiceSoapServiceResponse" /> </operation>
<operation name="onTransferRefusedException">
<input message="tns:onTransferRefusedExceptionPaymentProcessorServiceSoapRequest" />
<output message="tns:onTransferRefusedExceptionPaymentProcessorServiceSoapResponse" />
</operation>
</portType>

The payment processor WSDL file defines BPEL partner links for the service. The links associate roles with portTypes for the payment processor service ("service") and for callbacks on its client ("requester").

<plnk:partnerLinkType name="PaymentProcessorService">
<plnk:role name="PaymentProcessorServiceService">
<plnk:portType name="tns:PaymentProcessorService" />
</plnk:role>
<plnk:role name="PaymentProcessorServiceRequester">
<plnk:portType name="tns:PaymentProcessorServiceCallback" />
</plnk:role>
</plnk:partnerLinkType>

You can view the complete contents of the PaymentProcessorService WSDL file, including the details of the input and output messages for the operations described above.

PayFlow WSDL File

The PayFlow BPEL process provides the following operations: initiate, pollResult and PayFlowCallback, grouped under the PayFlow portType.

<portType name="PayFlow">
<operation name="initiate">
<input message="tns:initiatePayFlowSoapRequest"/>
<output message="tns:initiatePayFlowSoapResponse"/>
</operation>
<operation name="pollResult">
<input message="tns:pollPayFlowResultSoapRequest"/>
<output message="tns:pollPayFlowResultSoapResponse"/>
</operation>
</portType>
<portType name="PayFlowCallback">
<operation name="onResult">
<input message="tns:onPayFlowResultSoapRequest"/>
<output message="tns:onPayFlowResultSoapResponse"/>
</operation>
</portType>

The PayFlow WSDL file defines BPEL partner links for the process. The links associate roles with portTypes for the PayFlow process and for callbacks on its client ("requester").

<plnk:partnerLinkType name="PayFlow">
<plnk:role name="PayFlowService">
<plnk:portType name="tns:PayFlow"/>
</plnk:role>
<plnk:role name="PayFlowRequester">
<plnk:portType name="tns:PayFlowCallback"/>
</plnk:role>
</plnk:partnerLinkType>

The PayFlow process WSDL defines types to be used for messages exchanged between the process and its partners. These types include PaymentRequest, comprised of five (5) fields (the last of which is the transfer amount, to be discussed later in the BPEL process logic section) and DigitalReceipt, comprised of three (3) fields (the last of which references PaymentRequest).

<complexType name="PaymentRequest">
<sequence>
<element name="fromName" type="string"/>
<element name="fromAccount" type="string"/>
<element name="toName" type="string"/>
<element name="toAccount" type="string"/>
<element name="amount" type="double"/>
</sequence>
</complexType>
<complexType name="DigitalReceipt">
<sequence>
<element name="status" type="string"/>
<element name="confirmationID" type="string"/>
<element name="paymentRequest" type="s1:PaymentRequest"/>
</sequence>
</complexType>

You can view the complete contents of the the PayFlow WSDL file, including the details of the input and output messages for the operations described above.

Creating the Process with BPEL

After defining the process WSDL and examining the partner WSDL, we can now turn to defining the process logic using BPEL. First, we need to define the namespaces, which will allow the process to refer to the message types defined within the WSDL files and qualify other names appropriately.

<process name="PayFlow"
targetNamespace="http://demo.cxdn.com"
suppressJoinFailure="yes"
xmlns:tns="http://demo.cxdn.com"
xmlns:tpp="http://payment.org"
xmlns="http://schemas.xmlsoap.org/ws/2003/03/business-process/">

Next, we need to declare the parties involved in the process, each associated with a partnerLinkType and up to two roles, myRole and partnerRole, which describe the relative roles the process and the partner play, respectively. The parties involved here include the PayFlow process client PayFlowRequestor and the payment processor service PaymentProcessorService. For each partnerLink, myRole is the role of the PayFlow BPEL process.

<partnerLinks>
<partnerLink name="client"
partnerLinkType="tns:PayFlow"
myRole="PayFlowService"
partnerRole="PayFlowRequester"/>

<partnerLink name="PaymentProcessorService"
partnerLinkType="tpp:PaymentProcessorService"
myRole="PaymentProcessorRequester"
partnerRole="PaymentProcessorServiceService"/>
</partnerLinks>

In order to facilitate the interactions between the process and the partners, we need to define XML Variables, which will contain the messages used to communicate with the partners.

Based on the requirements of the PayFlow process, it receives an initiatePayFlowSoapRequest message as input, communicates with the payment processor asynchronously through request and response messages, needs to handle transfer-refused and a insufficient-funds faults, and finally provides a digital receipt at the conclusion of its execution.

<variables>
<variable name="input"
messageType="tns:initiatePayFlowSoapRequest"/>
<variable name="digitalReceipt"
messageType="tns:onPayFlowResultSoapRequest"/>
<variable name="request"
messageType="tpp:initiatePaymentProcessorServiceSoapRequest"/>
<variable name="response"
messageType="tpp:onPaymentProcessorServiceResultSoapRequest"/>
<variable name="transferRefusedFailure"
messageType="tpp:handleTransferRefusedExceptionSoapRequest"/>
<variable name="insufficientFundFailure"
messageType="tpp:handleInsufficientFundExceptionSoapRequest"/>
</variables>

The PayFlow process is essentially a sequence of activities, meaning the activities should be executed serially. We first add a <receive> activity to the sequence in order to take the client message and put it in the input XML variable. The <receive> activity indicates that a new process instance is to be created upon receiving a message at portType PayFlow for operation initiate.

<sequence>
<receive name="receiveInput" partnerLink="client" portType="tns:PayFlow" operation="initiate" variable="input" createInstance="yes"/>

After receiving the client message, the process proceeds to start the main sequence for processing the payment flow. This <sequence> activity is enclosed within a <scope> that defines a catchall fault handler for terminating the process upon encountering a network error while interacting with an external service. The sequence starts by copying the client request from the input variable to the request variable used for sending it to the payment processor.

<scope variableAccessSerializable="no">
<faultHandlers>
<catchAll>
<terminate/>
</catchAll>
</faultHandlers>

<sequence>
<assign>
<copy>
<from variable="input" part="parameters"
query="//xmlRequest"/>
<to variable="request" part="parameters"
query="/initiatePaymentProcessorService/xmlRequest"/>

Once client request has been copied into the request variable, we can now use the <invoke> activity to pass the request to the PaymentProcessor partner specifying request as its input parameter. The payment processor invocation is asynchronous meaning that the invoke activity does not return or wait for a result. For handling the asynchronous replies from the payment processor, the BPEL PayFlow process uses the <pick> activity, which picks up messages coming as callbacks from the PaymentProcessor partner, saving the messages in the response variable. Upon receiving a message as a result of the payment processor normal execution, it is copied from the response variable to the digitalReceipt variable.

<invoke name="invokePaymentProcessorService" partnerLink="PaymentProcessorService" portType="tpp:PaymentProcessorService" operation="initiate" inputVariable="request"/>

<pick>
<onMessage partnerLink="PaymentProcessorService" portType="tpp:PaymentProcessorServiceCallback" operation="onResult" variable="response">
<assign>
<copy>
<from variable="response" part="parameters" query="result"/>
<to variable="digitalReceipt" part="parameters" query="/onPayFlowResult/result"/>
</copy>
</assign>

Other messages received by the <pick> activity may also include transfer-refused (in case the transfer amount exceeds $500) and insufficient-fund faults (in case the client SSN# provided is invalid). These messages are stored in their respective variables associated with onTransferRefusedException and onInsufficientFundException. In addition to handling exceptions, the BPEL process also provides for timeout management, in case the result from the payment processor is not received within 2 days of invoking it. A timeout alarm in this case will trigger the <terminate> activity and abort the process execution. Note that a real-world process could have any arbitrary logic executed upon a timeout alarm. That completes the <scope> activity containing the payment processor interaction set.

<onMessage partnerLink="PaymentProcessorService" portType="tpp:PaymentProcessorServiceCallback" operation="onTransferRefusedException" variable="transferRefusedFailure">
<terminate/>
</onMessage>

<onMessage partnerLink="PaymentProcessorService" portType="tpp:PaymentProcessorServiceCallback" operation="onInsufficientFundException" variable="insufficientFundFailure">
<terminate/>
</onMessage>

<onAlarm for="P2D">
<terminate/>
</onAlarm>
</pick>

Finally, in order for the PayFlow process to respond to its client's request asynchronously, it uses an activity to invoke a callback operation on the client. The result stored by the digitalReceipt variable is passed as a message to the client using the onResult operation of the callback portType. After the invocation, the process is ended.

<invoke name="replyOutput" partnerLink="client" portType="tns:PayFlowCallback" operation="onResult" inputVariable="digitalReceipt"/>
</sequence>
</process>

Running the Process The PayFlow business flow can be run online using Collaxa's hosted BPEL console or by downloading Collaxa's BPEL Orchestration Server and deploying the above sample (included as part of the software package). Whether using the online console or the locally installed software, the following BPEL console window will show the PayFlow BPEL process:

Resources

• BPEL4WS Fast Facts, including BPEL 1.1 and OASIS submission perspective
• Learn the basics of BPEL4WS in this BPEL 101 Tutorial (followed perhaps by reading the BPEL 1.1 specification).
• And... many more BPEL samples for your perusal and further experimentation.