Thursday, October 11, 2012

Part 1: Developing a WS-BPEL Process using WSO2 Developer Studio

In this post I am going to discuss following list of items.

What's a BPEL Process?
A BPEL Process is a container where you can declare relationships to external partners, declarations for process data, handlers for various purposes and most importantly, the activities to be executed. 

Let's start with designing a simple workflow.

Create a BPEL process that returns addition of two integer numbers. For the number addition operation the BPEL process invokes an existing service and gets the result from the web service. This web service takes two integers and returns addition of the two integer values. The web service will be hosted on WSO2 AppServer (or else you can use any other appserver).

Figure 1, shows the axis2 service that we are going to invoke via the BPEL process. 
Create the axis2 archive (.aar) [Right click on the AdderService Project --> Export Project as a deployable archive and save it].

Now Start WSO2 AppServer (Goto AppServer_HOME/bin --> sh

Deploy AdderService.aar on AppServer.
1. Copy aar file to AppServer_HOME/repository/deployment/server/axis2services directory
2. Using the AppServer Management Console (Add --> AAR Service --> upload the service archive) 
We need to keep the wsdl file for the AdderService as, that is required later when developing the  BPEL process.

wget http://localhost:9763/services/AdderService?wsdl
Save the AdderService.wsdl to your local file system.

Figure 1

Let's start with designing the BPEL workflow.
Open eclipse which has WSO2 Developer Studio installed. 
Goto Dashboard (Developer Studio --> Open Dashboard menu and click on BPEL Workflow under Business Process Server category)
Figure 2: Create New BPEL Project

Give a project Name, Namespace and select the Template type. As we are going to create a short running bpel process, select the template type as Synchronous.

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 we'll use asynchronous services for long-lasting operations and synchronous services for operations that return a result in a relatively short time.
Figure 3 

Figure 4

Here you can see the template for our business process. The BPEL editor automatically generates receiveInput and replyOutput activities(Figure 5). Also it will generate partnerLink and variables used in these two activities.

Note: It will automatically generate AdderProcessArtifacts.wsdl and AdderProcess.bpel. If we look at the folder structure of the BPEL process, we can easily figure out these two files.

Figure 5

In our BPEL process we need to invoke an external service which is AdderService. To invoke this service we need to assign the input variables into external service’s input and again the reply from the external service to our BPEL process output. So that, here we need two assign activities and one invoke activity. 

Let’s add an assign activity in between receiveInput and replyOutput activities. To add assign activity drag it from the Action section of the Palette.

Figure 6 : AdderProcess workflow

Before filling the invoke activity, you need to import the AdderService.wsdl to you workflow project. 
Figure 7

Now start implementing the business logic.  
Goto Properties of invoke activity.
Goto 'Details' tab and from the 'Operation' drop down list, select 'Create Global Partner Link'
Figure 8

Give a Partner Link Name and click OK.
Figure 9

Now you'll prompt to the window shown in Figure 10. Click on 'Add WSDL'
Figure 10

Select the WSDL file which you have already imported to the workflow project. Click OK.
Figure 11

In the Partner Link Type window, you should select the correct PortType. then click OK.
Figure 12

Give a name to the Partner Link Type and click Next.
Figure 13

Give a name to the partner role and then select the correct PortType. Now click Finish. We have only one role for this invoke activity. If we have multiple roles (partner roles and my roles, we need to click on Next and create the next role).
Figure 14

Now you need to pick the 'add' operation from the Quick Pick box. For that 'Double' click on it. 
Figure 15

Now you are done with implementing invoke activity. Next step is to implement two assign activities. Before doing that, you need to identify what are the inputs and outputs of your process. We have two integer values as the request parameters and a resulting integer as the response.

Open the AdderProcessArtifacts.wsdl and find the Service, PortType and the binding there. Click on the arrow next to AdderProcessRequest.
Figure 16

Add two integer elements as shown in Figure 17. [To add a element, RightClick --> Add Element] Select the element type as int from the drop down list.
Figure 17

Configure AdderProcessResponse part similarly the above step.
There you need to click on the arrow next to AdderProcessResponse.
Figure 18

For the request, you have only one integer element as the output.
Now save the wsdl file and close it.
Figure 19

Go back to the bpel file and start implementing the first assign activity, that is 'AssignInputVars'.
Goto 'Details' tab and click on 'New'.
Do the mapping as shown in Figure 20.
Figure 20

It will automatically prompt for the initialization. Click on 'Yes'.
Figure 21

Figure 22

Now you are done with configuring the First Assign Activity.
Figure 23

Configure the second assign activity, that is 'AssignoutputVars'. 
Figure 24

Allow for the automatic variable initialization for response.
Figure 25

Now you are done with the bpel process flow design. Now open the deploy.xml (Deployment Descriptor).

Here you can specify the process state (whether it activated, deactivated or retired) after the deployment, set the process executed only in memory, Inbound Interfaces (Service) and Outbound Interfaces (Invokes) etc.

Figure 26

Now make the BPEL process as a deployable archive (Right click on the AdderProcess workflow --> Export Project as a deployable archive).

Start WSO2 Business Process Server (BPS_HOME/bin --> sh
Make the port offset to 1 (Change offset to 1 in BPS_HOME/repository/conf/carbon.xml)

Deploy on WSO2 BPS.
1. Copy zip file to BPS_HOME/repository/deployment/server/bpel directory
2. Using the BPS Management Console (Processes --> Add --> BPEL Archive(zip) --> upload) 

Figure 27

To test the process use TryIt wizard or any other tool(eg: SOAP UI).
Figure 28 : Click on TryIt

Figure 29 : SOAP Request

Figure 30 : SOAP Request/Response 

Here, we get integer (a+b) as the response in the xml output.


  1. Timeout or execution error when waiting for response to MEX {MyRoleMex#hqejbhcnphr8is9jfenpfe [Client hqejbhcnphr8is9jfenpfd] calling {}AdderService1.process(...)} java.util.concurrent.TimeoutException: Message exchange org.apache.ode.bpel.engine.MyRoleMessageExchangeImpl$ResponseFuture@1e6a1d timed out(120000 ms) when waiting for a response!

  2. i am getting NullPointer Eception as result can u please solve my issue .I followed as it is in the example

  3. Hi Thilini,

    I followed your example exactly as per your steps and get a deployment error, the zip appears to deploy correctly but when you look at the cmd console you see the error and not in the BPS UI
    The error is no service name for "myrole" pLink Client.
    org.apache.ode.bpel.iapi.BpelEngineException: java.lang.IllegalArgumentException
    : No service name for myRole plink client
    at org.apache.ode.bpel.engine.BpelServerImpl.register(BpelServerImpl.jav
    at org.wso2.carbon.bpel.core.ode.integration.BPELServerImpl$ProcessStore
    at org.wso2.carbon.bpel.deployer.BPELDeployer.deploy(
    at org.apache.axis2.deployment.repository.util.DeploymentFileData.deploy
    at org.apache.axis2.deployment.DeploymentEngine.doDeploy(DeploymentEngin
    at org.apache.axis2.deployment.repository.util.WSInfoList.update(WSInfoL

  4. Resolved this issue now but I have the same problem now as maheswar reddy did,

    Can you help with this please?

  5. Hi,
    I have this issue:
    cvc-identity-constraint.4.2.2: Duplicate key value [] declared for identity constraint "import" of element "definitions".
    in the wsdl bpel proccess

    any idea?

  6. thanks for sharing this article.Its work fine