Developing WS-BPEL Processes using WSO2 Carbon Studio

Business Process Execution Language or WS-BPEL lets people orchestrate tasks and activities exposed as Web services. WSO2 Business Process Server can execute process descriptions written in WS-BPEL. Since BPEL is structured and based on XML, it is now far easier for business users to model and execute business processes using open source graphical tools like Eclipse BPEL Designer. This tutorial describes how to Develop a WS-BPEL Processes using WSO2 Carbon Studio. Date: Tue, 7th Jun, 2011 Level: Intermediate Reads: 1657 Comments: 3 | Login or register to post comments Printer-friendly version Send to friend PDF version  Post to twitter

Hasitha Aravinda WSO2

Introduction

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

Content

• Scenario : Invoke single Web service using BPEL process.
• Developing WS-BPEL Processes using WSO2 Carbon Studio
  • Pre-Requirements
  • Step 1: Deploying AdderService.aar
  • Step 2: Create a Carbon Application Project
  • Step 3: Creating the BPEL process
  • Step 4: Creating a Binding and Service to the AdderProcessArtifacts.wsdl
  • Step 5: Modify the service description file AdderProcessArtifacts.wsd
  • STEP 6: BPEL process Designing
  • Step 7: Set the Partner Links for Invoke activities
  • Step 8: Assigning Varaibles
  • Step 9: Creating Deploy.xml
  • Step 10: Creating WSO2 BPS server and Deploying the Carbon Application in WSO2 BPS.

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 will give abstract view of our BPEL process.

Developing WS-BPEL Processes using WSO2 Carbon 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.5 or above
• Eclipse SDK 3.5 (Eclipse Galileo) with Carbon Studio 1.0.X.
• Apache Axis2 server 1.6.
• WSO2 Business Process Server 2.0.X

 Tested Environment

• Ubuntu 10.10
• WSO2 BPS-2.0.2
• Apache-Axis2 1.6
• Eclipse SDK 3.5 (Eclipse Galileo) with Carbon Studio 1.0.3
   

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 http://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

2.2  From the dialog window select Carbon Application Project and click Next (see 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 asWS_NumberAdderCarbon. Then click Finish. (See Figure 2.3)


Figure 2.3

Note:

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


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   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 again click Finish to close the New BPEL Workflow dialog. Now you can see the newly created BPEL project appears in Project Explorer window.


Figure 2.7

Step 3: Creating the BPEL process.

Now we have already created BPEL project. Now-onwards we are going to create our BPEL process.
3.1  Let’s create a BPEL process file. For that right-click on BPEL project “BPELNumberAdder” form the “Project Explorer”.

Note:

If you expand the WS_NumberAdderCarbon project folder in the Project Explorer window, you can see another folder calledBPELNumberAdder. This is an instance of our BPELNumberAdder Project. Both are linked in 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

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


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


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

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

Note:

There are Three SOAP Binding Options. They are Document Literal , rcp literal and rcp encoded. The WSO2 Business Process Server use 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 asNumberAdderService.
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 the Completing the step 4, your AdderProcessArtifacts.wsdl will look like this. See figure 4.3


Figure 4.3

Now we have finished the defining the Binging and 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 type 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 the how to define the input and output variables for our BPEL process. So we need to Modify the service description file of the BPEL process.

Step 5: Modify the service description file AdderProcessArtifacts.wsd

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 suits for our service.
5.1  Open the AdderProcessArtifacts.wsdl file. First set the input parameters. Click the arrow next to AdderProcessRequest.


Figure 5.1

5.2  It will open another Tab called “Inline Schema of AdderProcessArtifacts.wsdl”. Defaults it will have single variable called input with typestring. Rename it as x and set its type into 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

5.4  Now we have done the input request parameters configurations. We can follow the same sequence 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 its type as int.
(Tip: another way to add the elements is using the Outline view. See figure 5.3. In Outline view, go to the Elements and expands it. Then goto theAdderProcessRequest → local type → sequence. In here you can see the  elements that just created. )


Figure 5.3

Now we have configured the AdderProcessArtifacts.wsdl. The Next step is design part of our BPEL process.

STEP 6: BPEL process Designing.
 

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

Note:

In our BPEL process we need to invoke an external service (Adder Service). To invoke this service we need to assign the our 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 thePalette.(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: Renaming can be done by double-clicking on it or using 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 mapping 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

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

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

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

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

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”. In properties view click on Details tab.
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 selections can cause error(s) during run time.

Important:

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


Figure 8.1

Now you should have two assigns in your design. They are “Fixed value to variable” and “variable to variable”. Now let’s configurations 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

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 our input args0 and args1 variables are initialized or not. If not initialize them.

Note:

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

Not initialized.

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

Initialized statement

<ns:add xmlns:ns="http://ws.apache.org/axis2" xmlns:xsi="http://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 assing 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 are available like Expressions, Property of a Variable, Partner Link Reference etc. 

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

Now we have finished the BPEL process designing. 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

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

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

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

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: Creating WSO2 BPS server and Deploying 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

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 http://wso2.com/products/business-process-server. After selecting the CARBON_HOME ClickFinish.

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

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

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 againadmin as password.


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

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. Type two numbers for x and y. Then click Process, then it will show the answer in the window.


Figure 10.6


Figure 10.7

Congratulation! 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.

Attachment	Size
AdderService.aar	1.23 KB