2011/06/07
7 Jun, 2011

Developing WS-BPEL Processes using WSO2 Carbon Studio

  • Hasitha Aravinda
  • ​Technical Lead - WSO2

 

Introduction

The purpose of this tutorial is to demonstrate how to use WSO2 Developer Studio to model a WS-BPEL Process.

Content

Scenario: Invoke single Web service using BPEL process

In this tutorial I am going to 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. I’m going to host this web service on local Axis2 server. You can download AdderService.aar from the Attachments below.

Following diagram gives an abstract view of our BPEL process.

BPEL process

Developing WS-BPEL Processes using WSO2 Developer Studio

 

Pre-Requirements

 For deploying the WS-BPEL process explained in this tutorial, it is required to have the following applications installed in your machine. 

  • Java Runtime Environment 1.6.x
  • Eclipse Java EE IDE, Version Helios with Carbon Studio 1.0.x.
  • Apache Axis2 server 1.6.
  • WSO2 Business Process Server 2.0.X or 2.1.x

 Tested Environment

  • Ubuntu 10.10
  • WSO2 BPS-2.0.2 and later
  • Apache-Axis2 1.6
  • Eclipse Java EE IDE, Version Helios with Carbon Studio 1.0.14 

Let’s start to build our BPEL process. 

Step 1: Deploying AdderService.aar
 

1.1  First Deploy the AdderService.aar file in Apache Axis2 server.

1.2  Then run the axis2server. You can find the AdderService.wsdl from https://localhost:8080/axis2/services/AdderService?wsdl. We will need this wsdl during our BPEL process development. So save the AdderService.wsdl

Step 2: Create a Carbon Application Project

 2.1  Open Eclipse IDE. Go to File → New → Other  (see Figure 2.1) 

figure 2.1
Figure 2.1 

2.2  From the dialog window select Carbon Application Project and click Next (see Figure 2.2).

 

Figure 2.2

Figure 2.2 

2.3  Give a name to the Carbon Application Project. In this example,  I’m giving the Carbon Application Project name as WS_NumberAdderCarbon. Then click Finish. (See Figure 2.3)

 

Figure 2.3

Figure 2.3

Note:

Eclipse will prompt you to “root-artifact.xml” automatically. Otherwise, open it from Project Explorer window 

 

figure 2.4

Figure 2.4 

2.4  Let’s create a new BPEL project. Click on “Create New Artifact” (figure 2.4) and select “BPEL WorkFlow” (Figure 2.5). In the opened dialog (Figure 2.6) click on “New BPEL Project”. 

figure 2.5             Figure 2.6

Figure 2.5   and    Figure 2.6  

2.5  It will show dialog box (Figure 2.7). Give a name to our BPEL project. Here I am giving the project name as BPELNumberAdder.

2.6  Then click Finish to close the wizard and click Finish to close the New BPEL Workflow dialog. Now you can see the newly created BPEL project in Project Explorer window.

Figure 2.7

Figure 2.7 

Step 3: Creating the BPEL process.

Now we have already created BPEL project. Next step is to create the BPEL process.

3.1  Let’s create a BPEL process file. For that right-click on BPEL project “BPELNumberAdder” in the “Project Explorer”.

Note:

If you expand the WS_NumberAdderCarbon project folder in the Project Explorer window, you can see another folder called BPELNumberAdder. This is an instance of our BPELNumberAdder Project. Both are linked together. In Other words all changes which are done to the BPELNumberAdder project, automatically applied to the BPELNumberAdder folder of the WS_NumberAdderCarbon. Here I am using the BPELNumberAdder project for BPEL process development. 

3.2  Then go to New → Other. It will show a Wizard (Figure 3.1). From the wizard, select “New BPEL process File” which is under the BPEL 2.0. Then click Next

Figure 3.1

Figure 3.1 

3.3  In the next dialog (Figure 3.2), it will ask a name, a namespace and a template for the BPEL process. Here I am giving the Process name as “AdderProcess” and Namespace as “https://NumberAdder.com”. The process which we are going to create is a synchronous process. Therefore select template as Synchronous BPEL process. Then click Finish

Figure 3.2

Figure 3.2 

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 3.3)


Figure 3.3

Figure 3.3

AdderProcessArtifacts.wsdl is used to expose our BPEL process as a service. If you open the wsdl, you can see that, it's only define the port type, messages etc. In-order to deploy our BPEL process in WSO2-Business Process Server we need to define a Binding and a Service. In next section I will demonstrate how to create a binding and a service to our BPEL process.

 

Step 4: Creating a Binding and Service to the AdderProcessArtifacts.wsdl 

First let’s add a binding to the AdderProcessArtifacts.wsdl.

4.1  Write click on the Editor, select Add Binding. (Figure 4.1) 

figure 4.1

Figure 4.1 

4.2  Select the Binding. From the Properties window you can set a name for the Binding. Change it, if you need. Then select “AdderProcess” for the port Type from the drop-down menu.

4.3  Then click on “Generate Binding Content” button. In the Binding Wizard dialog (Figure 4.2), select “SOAP” for protocal and click Finish

Figure 4.2

Figure 4.2 

Note:

There are Three SOAP Binding Options. They are Document Literal , rcp literal and rcp encoded. The WSO2 Business Process Server uses an Axis2 integration layer. Axis2 does not support rcp encoded SOAP binding. So DO NOT select rcp encoded as a SOAP binding options.
 

4.4  Then we need to add a service. Again right-click on the editor and select “Add Service”. Then click on service and rename it as NumberAdderService.

4.5  Select the port and using property window rename the port as NumberAdderServicePort. Then select the binding that we have created from the drop-down menu.

After completing the step 4, the AdderProcessArtifacts.wsdl will look like as follows. See figure 4.3 

Figure 4.3

Figure 4.3 

Now we have finished, defining the Binging and the Service for our BPEL process.

Variables in BPEL process hold the state of the running process instance. In our example, variables are needed to store the sent and received messages to/from partner service. So we need to initialize the variables to invoke external service. Here we use WSDL Message type variables. (there are other types of variables: XML Schema type, XML Schema element, etc). WSDL Message type variables correspond to web service message types that are defined in WSDL files imported by the process. Let’s look at how to define the input and output variables for our BPEL process. To do that we need to modify the service description file of the BPEL process. 

Step 5: Modify the service description file AdderProcessArtifacts.wsdl 

Here I am going to define our input and output parameters of the porject. As I discussed earlier our BPEL process takes two integers values and returns an integer value that is the addition of input values. BPEL editor creates automatically inputs and output parameters. But we need to change those parameters such a way that they suit for our service.

5.1  Open the AdderProcessArtifacts.wsdl file. First set the input parameters. Click the arrow next to AdderProcessRequest.

 

Figure 5.1

Figure 5.1
 

5.2  It will open another tab called “Inline Schema of AdderProcessArtifacts.wsdl”. Default will have single variable called input with type string. Rename it as x and set the type to int.

5.3  Then we need another element. To add another element right-click on AdderProcessRequestType and add an Element. Name it as y and select type as int. (see Figure 5.2) 

Figure 5.2

Figure 5.2 

5.4  Now we have done the input request parameters configurations. We can follow the same procedure to define the response parameters. In Response we need one parameter to return the integer value of addition of inputs. Here I name it as result and set the type to int.

(Tip: Also we can add elements using the Outline view as shown in figure 5.3. In Outline view, go to the Elements and expands it. Then goto the AdderProcessRequest → local type → sequence. Here you can see the elements that are just created. )

 

Figure 5.3

Figure 5.3

Now we have configured the AdderProcessArtifacts.wsdl. The Next step is to design the BPEL process. 

STEP 6: BPEL Process Design
 

6.1  Open the AdderProcess.bpel file from the Project Explorer window. Here you can see the template for our business process. The BPEL editor automatically generates receiveInput and replyOutput activites. (Figure 6.1) Also it will generate partnerLink and variables used in these two activities.

 

Figure 6.1

Figure 6.1
 

Note:

In our BPEL process we need to invoke an external service (Adder Service). To invoke this service we need to assign the input variables into external service’s input and again assign the reply from the external service to our BPEL process output. So in our scenario we need two assign activities and one invoke activity. 

6.2  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.2)

 

Figure 6.2

Figure 6.2 

(Tip: another way to add activity element to the editor is right-click on element and use add-before option).

This assign responsible for mapping inputs between our Process and external service. Rename it as AssignInputVariables.

(Tip: Double-click on the element to rename it or use the Properties View).
 

6.3  Then we need to add an invoke activity. Before add an invoke activity, we need to add a Sequence. Add a Sequence after the Assign activity. Drag Sequence from the Control2 section and drop between Assign and replyOutput.

6.4  In the Sequence section we are going to add our invoke activity. Drag an Invoke activity from Action section and place it in Sequence. Rename the Invoke activity as InvokeAdderService.

6.5  Then we need another Assign activity to map variables between external service reply to our process reply. Add another Assign activity between sequence and replyOutput. Rename it as AssignOutputVariables.
 

After the end of step 6, your design should look like this. 

Figure 6.3

Figure 6.3
 

Step 7: Set the Partner Links for Invoke activities

 

 Before this step we need to import Saved AdderService.wsdl to our BPEL project folder.

7.1  To import that, right-click on BPEL project folder and select Import. Under the General section select “File System” and click Next.

7.2  In next window Click Browse button and select the folder which is AdderService.wsdl file is located. Then select AdderService.wsdl file and click Finish. (Figure 7.1)

Figure 7.1

Figure 7.1 

7.3  Then click on Invoke activity and go to the Properties window. Then click on Details tab.

7.4  In the “Partner Link” drop-down menu select “Create Global Partner Link” and Give a Name For the partnerLink. Here i'm giving Partner-link name as AdderServricePL.

7.5  Then it view a dialog box to Choose Partner-link type dialog. Now I’m going to add Partner-link type. It is coming from the AdderService.wsdl . To add partner-link type in to dialog, click on Add WSDL. Then select the Resources from Import Source section and select the  AdderService.wsdl from the project folder. Then Click Ok. (see Figure 7.2)

 

Figure 7.2

Figure 7.2 

7.6  It will add AdderServicePortType to the list. Select it and click Ok.

7.7  Then it will ask Partner-link type name and give a name for it. Here I'm giving it as AdderServicePLType and Clck Next. (Figure 7.3)

Figure 7.3

Figure 7.3 

7.8  Then it will ask Role name, give it as AdderRole and Select the PortType from the dialog box. Then Click Finish.

Now you have created a Partner-link for our invoke activity. In the Properties view you can see the partner-link that you have created.

7.9  Then select the add operation from the quick pick list which is right side of properties window. It will automatically complete the remaining parts of the properties window. (Figure 7.4)

Figure 7.4

Figure 7.4 

Now you have completed the defining the partner-link for invoke activity. Now let’s look at assigning variables for activities. 

Step 8: Assigning Varaibles

8.1 Click on “AssignInputVaraiabes”. Click on Details tab in properties view.

Now we are going to initialize the input variables. Click on New button. Select “payload: adderPorcessRequest” of input from “Form” list and  “parameters: add” of AdderServicePLRequest from “TO” list. (see Figure 8.1)

Note:

Wrong selection(s) can cause error(s) during run time.

Important:

While you configure the variables, the editor will ask to initialize the variables. Click yes. It will automatically generate codes for Variable initialization.

Figure 8.1

Figure 8.1

Now you have two assign activities in your design. They are “Fixed Value to Variable” and “variable to variable”. Now let’s configure them one by one.

8.2  First click on “Variable to Variable”. Then set the values of “From list” to the “x: int” of the “payload of the input”  and set the values of “To list” to the “args0: int” of the “parameters: add of the AdderServicePLRequest”. (See figure 8.2)

Figure 8.2

Figure 8.2

8.3  Then add another “Variable to Variable” assign for variables “y: int” to “args1:int”. Follow the same procedure which is used in above.

8.4  Then click on “Fixed Value to Variable”.
Check whether the input args0 and args1 variables are initialized or not. If not initialize them.

Note:

Here is an example. Un-initialized variable cause to “selection Failure” error in run time.

Un-initialized variables.

<ns:add xmlns:ns="http://ws.apache.org/axis2" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"> 
</ns:add>

Initialized statement

<ns:add xmlns:ns="http://ws.apache.org/axis2" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"> 
<ns:args0></ns:args0> 
<ns:args1></ns:args1>
</ns:add>

Now you should have one “Fixed Value to Variable” and two “Variable to Variable” initializations for  “AssignInputVaraiabes” assign activity.

8.5  Follow the same procedure for the “AssignOutputVariables” assign activity. Here you have to assign the “return:int” of the “parameter of AdderServicePLResponse”  to “result : int ” of the “payload of the output.

 

Note:

Here we are using only one way to define variables. We can initialize variables in different ways.   If you click on drop-drown menus of From and To, you can see several other options available such as Expressions, Property of a Variable, Partner Link Reference etc.

Tips: If you use Xpath Expressions for initializing variables, editor support for auto completion by ctr + space.

 
Now we have finished the BPEL process design. In order to deploy our BPEL process in WSO2 Business Process Server (BPS), we need to have Deployment Descriptor (deploy.xml). The deploy.xml is used to configure one or several processes to use specific services by WSO2 BPS.

 

Step 9: Creating Deploy.xml
 

9.1  Right-Click on the BPLEAdderNumber project in Project Explorer winndow. Then Goto New->Other.

9.2  From the Wizard Dialog box, select “Apache ODE  Deployment Descriptor” which is under the BPEL 2.0. (Figure 9.1) Click Next.

 

Figure 9.1

Figure 9.1
 

9.3  In next Window it will ask for the file name and BPEL project related to the deploy.xml. Do not Change anything and Click Finish.

NOTE

Note that the file name cannot be changed in Deployment descriptor (deploy.xml). As disused earlier it is used by WSO2 BPS to configure one or several processes to use specific services. Also it is important to know the Structure of the process container (see figure 9.2). As you see in figure it uses a flat file structure (All files are in the same level). We can see the same structure of the process container in Apache ODE.

 

Figure 9.2

Figure 9.2

9.4  Open the deploy.xml in the browser.


Note:

In here You can set the options for BPEL process. For example you can specify the process state (whether it activated, deactivated or retired) after the deployment, can set the process executed only in memory, Inbound Interfaces (Service) and Outbound Interfaces (Invokes) etc.  (see figure 9.3)

Figure 9.3

Figure 9.3 

Inbound interfaces means the services provided by the process. In this option you have to  specify the service, port and binding you want to use for each PartnerLink listed.

9.5  Let’s define the Inbound Interfaces. As you see in the diagram it will show you Client partner-link which is related to our BPEL process. Click on corresponding “Associated Port” in Inbound Interfaces. Here associated port is “NumberAdderServicePort” and select it from the drop-drown menu. (Figure 9.4). It fill automatically complete the other fields as well.

Figure 9.4

Figure 9.4

Let’s set the outbound interfaces (invokes). Outbound interfaces table contains interfaces the process invokes. In this example we use only one invoke activity. So we have to specify the service, port and binding for AdderServicePL Partner-link.

9.6  Click on Associated Port in AdderServicePL row in the Outbound Interface table. Then select “AdderServicehttpSOAP11Endpoint”. It will automatically complete the other fields.

9.7  Save the project.

Now we have completed implementing our BPEL process. Only remaining part is deploy our Carbon application in WSO2 Business Process Server. In next step I will discuss the how to deploy our Carbon application in WSO2 BPS.
  

Step 10: Adding a server and deploy the Carbon Application in WSO2 BPS

10.1  Let’s create a Server first. For that, right-click on the Servers window. (If Server window not appearing in the Eclipse IDE, go to Window → Show View → Servers.). Then select New → Server.

10.2  It will show “New Server” Window. From the List expand the WSO2 folder and Select “WSO2 Carbon 3.1 based server” and (Figure 10.1). If you need, you can specify the Server name here. Here I rename it as WSO2 BPS.

Note:

The BPS 2.0.2 we are using is based on Carbon 3.1.0. That is why we select 3.1 based server.

Figure 10.1
Figure 10.1

10.3  Then we have to set the CARBON_HOME. Click browse button and select the WSO2 Business Process Server home folder. If you didn’t have the WSO2 BPS you can download it from https://wso2.com/products/business-process-server. After selecting the CARBON_HOME Click Finish.

Note:

If you want to configure more setting of the Server like Service port, Web Console port etc. click Next and configure them.

After completing this step 10.3 the WSO2 BPS is added to Servers List. (See Figure 10.2) 

 Figure 10.2

Figure 10.2

10.4  Let’s deploy our carbon application in WSO2 BPS.  Click on WS_NumberAdderCarbon project in Project Explorer and Drag and drop it on Server. As you see in Figure 10.3 our carbon project is added to the WSO2 BPS server.
 

Figure 10.3

Figure 10.3

10.5  To run the server right-click on the server and select Start. In Console window, you can see the server Process’s log.

10.6  It will automatically open the WSO2 BPS login page in your default web browser. Login into the server using admin as username and again admin as password.

 Figure 10.4

Figure 10.4

10.7  After the login to the WSO2 BPS, you will redirect to the WSO2 BPS home page. Click on the “Processes” under the “Business Processes”. It will show the currently deployed processes.

 

Figure 10.5

Figure 10.5

 

Here you can see the AdderProcess is deployed in WSO2 BPS. The Process ID generated as {“Process NameSpace”} ProcessName-VersionNo

10.8  Click on the AdderProcess. It will show the details of the Process. (Figure 10.6)
To try the process click on the “Create Instance”. It will open an another Web browser window. (Figure 10.7) Let''s try our process. Give values for x and y. Then click Process, and it will show the result in the window.

 

Figure 10.6

Figure 10.6

 

Figure 10.7

Figure 10.7

 

Congratulations! We have finished our BPEL process.

Note:

We can use SOAP UI tool to test our process. Using SOAP UI application we can see the request/response soap messages. It will more helpful the error handling purposes.

 

Author

 Hasitha Aravinda,  Intern WSO2.

 

About Author

  • Hasitha Aravinda
  • ​Technical Lead
  • WSO2 Inc