Quick Start Guide

The Quick Start guide explains how to set up and start the WSO2 BPS, model a BPEL process, deploy and test it using the WSO2 BPS management console. The guide has the following sections:

Setting up BPS

WSO2 BPS setup is very simple. While more detail of the installation can be found in the Getting Started, we have given below a basic summary to get you started fast.

1. Ensure that the following are installed in your environment.
   
   • JDK 1.6.* or higher.
   • JAVA_HOME environment variable is set to <JDK_HOME>. For example, JAVA_HOME=c:\Program Files\java\jdk1.6.0_27.
2. Download the BPS binary distribution from http://wso2.com/products/business-process-server/.
3. Extract the zip file to a folder which will be referred to as <PRODUCT_HOME> throughout the rest of this guide.
4. Open a command prompt (or a shell in Linux) and go to the <PRODUCT_HOME>\bin directory.
5. Start the BPS server by executing wso2server.sh (or wso2server.bat in Windows).
6. The operation log keeps running until the server starts, which usually takes several seconds. Wait until the server fully boots up and displays a message similar to "WSO2 Carbon started in n seconds."

Modelling a BPEL process

1. Download and setup WSO2 Developer Studio. (http://wso2.com/products/developer-studio)
2. Open the Developer Studio and select File > New > Other.
   
3. From the window that appears, select Carbon Application Project and click Next.
   
4. Provide a suitable name to the Carbon application project. For the purposes of this example, name it as "WS_NumberAdderCarbon". Click Finish once done.
   The Carbon application project is created and you can see it on Project Explore pane on the left of your Developer Studio screen.
5. Create a new BPEL project. To do this, right-click on the project which is on the Project Explore pane and choose New > BPEL WorkFlow.
6. On the “Create New BPEL Project” wizard, select Create New BPEL workflow and click Next to continue.
7. Provide suitable names, a namespace and select the matching template for your BPEL process and project. 
8. In this example, we use "BPELNumberAdder" as the project name. Also provide a valid namespace as the process namespace. Since we are creating the synchronous business process, select the template “Synchronous BPEL Process”.
   
   • Process Name : AdderProcess
   • Namespace : http://NumberAdder.com
   • Template : Synchronous BPEL Process
   
9. Click Finish to close the wizard.
10. Expand the "WS_NumberAdderCarbon" project folder in the "Project Explore" pane to view another folder named "BPELNumberAdder". The "BPELNumberAdder" project is used here for BPEL process development. The “Project Explorer” window and the AdderProcess.bpel file will look like the following.
    
    This point onwards you have to design your BPEL process by adding business logic to the BPEL process. In this guide we will be designing a simple process to add two integers.
11. Open “AdderProcessArtifacts.wsdl” file in BPELNumberAdder Project in order to set input parameters. Click on the arrow next to "Adder Process Request".
    
    It will open another tab called “Inline Schema of Add”. By default it will have a single variable named “input” with type string. Rename it as x and set the type to int.
12. You need to add another element. To add another element right-click on "AdderProcessRequestType" and “add an element” after it. Name it "y" and set the "type" as "int". Now it should look like the follwing image.
    

13. Now lets design the simple business logic. Open the AdderProcess.bpel file. You need to add business logic in the place of where “FIX_ME-Add_Business_Logic_Here” activity resides. Delete the “FIX_ME-Add_Business_Logic_Here” element. You will have the following process.

    To delete, right-click on the element and choose delete.

    

14. Now you need to add an Assign activity in between “receiveInput” and “callbackClient” activities. To add Assign activity drag it from the Action section of the Action Palette.

    Another way to add activity element to the editor is right-click on element and use add-before option.

    

15. Now you need to configure Assign activity. Click on “Assign” element which is on BPEL process and then click on “Details” tab in ”property window”. 
16. Click on “New” which will lead you to the following view in “property window”
    
17. We will use an Xpath expression to compute the addition of two variables and assign the result to the output variable. To do that choose “Expression” from “From” drop down list and choose “Variable” from “To” drop down list.
18. Choose “Xpath 1.0 in BPEL 2.0 ” as Expression Language.
19. The Expression which we need to evaluate is “ $input.payload/tns:x + $input.payload/tns:y ”. Include this in the box below “Expression Language”.
20. Select “result:string” under “To” as the assigned variable.
21. While you configure the variables, The editor will send you a message asking you to initialize the variables. Click Yes. It will automatically generate an XML string for variable initialization. The property window of Assign activity should look like the following once you have completed the steps.
    
22. Now you need to define inbound and out bound interfaces. Open the deploy.xml file which is in the BPEL project. Choose AdderProcessPort as the inbound address port from the given list. The rest of the parameters will be automatically filled once you select it. There will not be any ports for outbound interfaces as we do not have external invocations in this business process.
    
23. Include the BPEL process as a dependency of the Carbon Application (WS_NumberAdderCarbon). To include it, open “pom.xml” of Carbon application project and select BPELNumberAdder as a dependency. 
    

Deploying and testing the BPEL process

After modelling the BPEL process, it can be deployed in the WSO2 BPS.

1. In Developer Studio, right-click on the "Servers" window and select New -> Server. If it is not visible, select Window -> Show View -> Servers.
2. The New Server window appears. From the List, expand the WSO2 folder and select WSO2 Carbon 4.0 based server as shown below. Carbon 4.0 based server is selected here since BPS 3.0.0 is based on Carbon 4.0.2. If needed, specify the Server name here. In this example, we specify it as WSO2 BPS. Click Next.
   
3. Set the CARBON_HOME by clicking the Browse button and selecting WSO2 Business Process Server home folder. Click Finish once done or Next if more settings of the server need to be configured such as the 'service port', 'web console port' etc.
   
4. Once done, WSO2 BPS is added to Servers List as shown below.
   
5. The next step is to deploy the carbon application in WSO2 BPS. Simply click on "WS_NumberAdderCarbon" project in "Project Explore" window and drag and drop it on Server.  The server will be automatically started.
6. If the server does not get started automatically, run the server by right-clicking on it and selecting "Start". In Console window, note the server process's log.
7. WSO2 BPS login page will be opened automatically in the default web browser. Login using admin as username and admin as password.
   

8. Select "processes →list" menu from the "Main" menu. The "Deployed Processes" window opens with the "AdderProcess" deployed.

   The "Process ID" is generated in the format {"Process NameSpace"} ProcessName-VersionNo. Click the Process ID.

   

9. The "Process Information" window appears with the details of the process. Click on the "Try It" link. 
   
10. A browser window opens to enter the required input parameters. Enter the values and click "Send" for the answer.
    

Writing a Human Task artifact

Business processes cannot always proceed in a fully automated manner. They need human interaction as a means of decision making, error handling and exception cases. For example, canceling a flight due to a strike or bankruptcy, deciding whether to accept the claim based on the requested amount etc. Human tasks provide the specification to define tasks performed by human beings.

Sample scenario

When a user requests a claim to be approved by the system, the system automatically approves claims under an amount of 1000 .This is a simple BPEL process. If the claim exceeds 1000, it will be handed over to the regional clerk who checks the claim amount along with the user information, decides whether or not to approve it, and the final decision is sent to the user. So when the claim is higher than 1000, it will be processed as a human task. The sample process is shown below.

Writing human tasks

The basic process is designed as a normal BPEL process with an IF component. For human tasks, we use the BPEL4PEOPLE activity remote task. It will get the input from the claim approval request such as the name and amount, and the output is sent via a claim approval callback service as true or false. The user can then see the final decision. This process needs some presentation elements. Human tasks are implemented as JSP pages.

The BPEL process is implemented using the BPEL4PEOPLE activities and deployed into the server. Human tasks have to be deployed as a separate process. Since there is no tool to create a human task workflow, all the steps have to be done manually. However, there is a predefined package structure which makes the work easier. As an initial step, you should create a package structure in your local directory.

Package structure of an HT artifact

There are four components in the HT package.

.ht file

The .ht file contains the information about the human task of the BPEL process. It is an XML-based file consisting of a predefined set of human task description elements. The table below shows the basic elements and their descriptions with some examples from the ClaimsApprovalTask sample.

<htd:humanInteractions>

<htd:import>

<htd:importnamespace="http://reminder.sample.humantask.wso2.org"location="OrderProcessReminder.wsdl"importType="http://schemas.xmlsoap.org/wsdl/">

<htd:logicalPeopleGroups>

<htd:logicalPeopleGroups>

        <htd:logicalPeopleGroup name="regionalClerks">
            <htd:documentation xml:lang="en-US">
                The group of clerks responsible for the region specified.
            </htd:documentation>
            <htd:parameter name="role" type="xsd:string"/>
        </htd:logicalPeopleGroup>

        <htd:logicalPeopleGroup name="regionalManager">
            <htd:documentation xml:lang="en-US">
                The manager responsible for the region specified.
            </htd:documentation>
            <htd:parameter name="role" type="xsd:string"/>
        </htd:logicalPeopleGroup>

        <htd:logicalPeopleGroup name="clerksManager">
            <htd:documentation xml:lang="en-US">
                The manager of the clerk whose user ID is passed as parameter.
            </htd:documentation>
            <htd:parameter name="role" type="xsd:string"/>
        </htd:logicalPeopleGroup>

        <htd:logicalPeopleGroup name="directorClaims">
            <htd:documentation xml:lang="en-US">
                The functional director responsible for claims processing.
            </htd:documentation>
        </htd:logicalPeopleGroup>

</htd:logicalPeopleGroups>
 
<htd:logicalPeopleGroups>
       <htd:logicalPeopleGroup name="regionalClerks">
           <htd:documentation xml:lang="en-US">
               The group of clerks responsible for the region specified.
           </htd:documentation>
           <htd:parameter name="role" type="xsd:string"/>
       </htd:logicalPeopleGroup>


	   <htd:logicalPeopleGroup>
    	.....
	   </htd:logicalPeopleGroup>
</htd:logicalPeopleGroups>

<htd:tasks>

<htd:tasks>
        <htd:task1>
        <htd:task2>
        <htd:task3>
<htd:tasks>

<htd:task>

<htd:task name="OrderProcess">  
	<htd:interface />
	<htd:peopleAssignments />
	<htd:presentationElements />
</htd:task>

<htd:interface>

<htd:interface 
 portType="cl:ClaimsHandlingPT"  
  operation="approve"   
 responsePortType="cl:ClaimsHandlingCallbackPT"   
  responseOperation="approvalResponse"/>  

<htd:peopleAssignments>

<htd:peopleAssignments>
	<htd:potentialOwners>
		<htd:from logicalPeopleGroup="regionalClerks">
			<htd:argument name="role">
				regionalClerksRole
			</htd:argument>
		</htd:from>
	</htd:potentialOwners>
	<htd:businessAdministrators>
		<htd:from logicalPeopleGroup="regionalManager">
			<htd:argument name="role">
				regionalManagerRole
			</htd:argument>
		</htd:from>
	</htd:businessAdministrators>
</htd:peopleAssignments>

<htd:documentation>

<htd:documentation>   
	Example for WS-HumanTask 1.1 - WS-HumanTask Task Definition  
</htd:documentation> 

<htd:from>
<htd:argument> 

<htd:from logicalPeopleGroup="regionalClerks">
 	<htd:argument name="role">
		regionalClerksRole
	</htd:argument>
</htd:from>

<htd:presentationElements>

<htd:presentationElements>   
<htd:name xml:lang="en-US">Approve Claim
</htd:name>  
<htd:name xml:lang="de-DE">Genehmigungder Schadensforderung  
</htd:name>   
<htd:presentationParameters>   
<htd:presentationParametername="firstname"  
  type="xsd:string">   
 htd:getInput("ClaimApprovalRequest")/test10:cust/test10:firstname   
</htd:presentationParameter>   
</htd:presentationParameters>

<htd:notifications>

<htd:notifications>   
  <htd:notificationname="ClaimApprovalReminder">  
  	<htd:documentationxml:lang="en-US">

htconfig.xml file

This file consists of deployment details of the human task. Human tasks supports two task types called task and notification. A task can have a publish and a callback. Publish means providing a service and Callback means calling an external service to provide the output. Notification is also a task type. A notification task provides one operation for external parties to create notifications. 

Example from the claim task sample:

<hic:HTDeploymentConfig xmlns:hic="http://wso2.org/ht/schema/deployment/config"
	xmlns:claim="http://www.example.com/claims/"
	xmlns:claimtask="http://www.example.com">
	<hic:task name="claimtask:ApproveClaim">
		<hic:publish>
			<hic:service name="claim:ClaimService" port="ClaimPort" />
		</hic:publish>
		<hic:callback>
			<hic:service name="claim:ClaimServiceCB" port="ClaimPortCB" />
		</hic:callback>
	</hic:task>
	<hic:notification name="claimtask:ClaimApprovalReminder">
		<hic:publish>
			<hic:service name="claim:ClaimReminderService" port="ClaimReminderPort" />
		</hic:publish>
	</hic:notification>
</hic:HTDeploymentConfig>

Here, the htconfig.xml file consists of three services used by a human task; get data from the user, call back of either approve or not and the reminder web service.

<Service>.wsdl

You can have one or more WSDL files which have been used in the BPEL process. You can have a composite WSDL addressing many web services. Claim Approval task has one composite WSDL.

Web folder

There are four .jsp files inside the web folder. Three .jsp files end with:

1. <TaskName>-input.jsp 
2. <TaskName>-output.jsp
3. <TaskName>-response.jsp

<TaskName>-input.jsp

The input.jsp file uses the (OMElement) request.getAttribute("taskInput") attribute to obtain the task details of the OMElement. This is inserted into the JSP context from BPS. The input.jsp file is used to show the task information to the task user.

Example from the ApproveClaim-input.jsp:

OMElement requestElement = (OMElement) request.getAttribute("taskInput");
	String ns = "http://www.example.com/claims/schema";
	if (requestElement != null) {
	OMElement customerElement = requestElement.getFirstChildWithName(new QName(ns, "cust"));
	if (customerElement != null) {
OMElement id = customerElement.getFirstChildWithName(new QName(ns, "id"));
if (id != null) {
customerId = id.getText();
}

The input web will show the human task list of the regional clerk user.

<TaskName>-output.jsp

The output .jsp is used to provide the user with a task form. Task processing happens when this is completed and submitted by the user.

All output .jsp files should implement the JavaScript method:

createTaskOutput = function() { 
};

This should provide the corresponding XML string expected by the task operation.

Example from the ApproveClaim-output.jsp:

createTaskOutput = function() {
var outputVal = getCheckedRadio(); //get approve or not from radio button
if(outputVal == 'approve') {return'<sch:ClaimApprovalResponse 	xmlns:sch="http://www.example.com/claims/schema"><sch:approved>true</sch:approved></sch:ClaimApprova	lResponse>';
} else if (outputVal == 'disapprove') {return'<sch:ClaimApprovalResponse 	  
xmlns:sch= "http://www.example.com/claims/schema"> <sch:approved>false</sch:approved>
</sch:ClaimApprov	 alResponse>';
}
};

Output JSP is used by the regional clerk user to approve the claim.

<TaskName>-response.jsp

Response.jsp is used to display the output of the completed task. It also uses the OMElement responseElement = (OMElement) request.getAttribute("taskOutput"); to obtain the OMElement corresponding to the output.

Example from the ApproveClaim-response.jsp:

String approved = "No Value Assigned"; 
OMElement responseElement = (OMElement) request.getAttribute("taskOutput"); 
if (responseElement != null) { 
approved = responseElement.getFirstElement().getText(); }

The response after approving the claim looks like this: