WSO2 Business Process Server v3.0.1 Documentation

##### Overview

- Home
- Release Note
- WS-BPEL Compliance
- License

##### Downloads

- Releases

##### Installation Guide

- Installing WSO2 BPS

##### Quick Start Guide

- Modeling the process
- Deploying the process
- Testing the process

##### User Guide

- Deploying BPEL Processes
- Deploying Human Tasks
- Managing BPEL processes
- Managing BPEL process instances
- QoS for BPEL processes
- Securing BPEL processes
- Invoking secured partner services
- Versioning
- Management API

##### Human Task Guide

- Human Tasks Quick Start Guide
- Deploying HumanTasks
- Managing Tasks
- Developing a Human Task Artifact
- Human Task Management and Configuration
- Human Task Concepts

##### Administrator Guide

- External data sources Configuration
- Registry Configuration
- Events
- Unified Endpoints
- BPEL Extensions
- Transaction Factory Configuration
- Message Exchange Interceptors
- OpenJPA specific properties
- JMS Transport Configuration
- Process Instance Cleanup Tasks
- Process Hydration and Dehydration
- Enabling Peer-to-Peer(P2P) Communication
- Setting up a BPS Cluster

##### Best Practices

- Process Deployment Best Practices

##### Concepts

- Process Versioning
- Process instance events
- Partner links

##### WS-BPEL Extensions

- Activity Failure and Recovery
- Extension Activities and Extensible Assign Operations
- XPath Extensions
- Iterable ForEach
- Flexible Assigns
- BPEL4People Extension

##### Samples

- HelloWorld
- If-Else
- ForEach
- While
- Repeat Until
- Flow and Links
- Pick
- Synchronous and Asynchronous Service Invocations
- Fault Handling
- Split
- XslTransform
- Compensation Handler
- Event Handler

##### Resources

- FAQ
- External Articles
- Library
- Source Code

##### Community

- Forum
- Mailing Lists

##### Project Information

- Issue Tracking

[ Documentation Index ]

# WSO2 Business Process Server (BPS) User Guide

The User Guide describes how to configure the WSO2 Business Process Server using the Web based management console. The WSO2 Management Console has been tested on the Mozilla Firefox 2.0, 3.0.x and Internet Explorer 6.0, 7.0 Web Browsers.

## Table of Contents

## Installing WSO2 Business Process Server

Please refer the Installation Guide for details on how to install WSO2 Business Process Server.

## Using WSO2 Business Process Server

### Process Deployment

- Deploying a Process in WSO2 Business Process Server
- Deployment Descriptor
- Formal Definition
  - Examples
  - Additional Settings
    - In memory execution

#### Deploying a Process in WSO2 Business Process Server

Each deployment is a zipped file with all relevant deployment artifacts. At the minimum it should contain the deployment descriptor, one or more process definitions (BPEL), WSDL and XSDs. It may also contain other files, such as SVGs or XSLs. The deployment descriptor is a file named deploy.xml (see the next paragraph for its description).

During deployment, the process engine loads all documents from the deployment descriptor. Loading documents allow it to reference processes, service and schema definitions using fully qualified names, and import based on namespaces instead of locations.

Two ways to deploy a process in WSO2 Business Process Server

1. Using the WSO2 Business Process Server Web Management Console

   Login to BPS Management Console by providing your credentials (default:- user:admin pass:admin). Go to Add BPEL menu item under the Business Process section of the left pane of the Management Console. Browse and select the zipped BPEL process. Upload the process.

2. Manually copying the zipped process file

   To deploy manually, just copy the zipped process file containing your artifacts, to the BPS_HOME/repository/deployment/server/bpel directory. In this case, you need to be aware of the structure of the zipped process. The deployment discripter (i.e. deploy.xml file) should be in the root of the zip.

#### Deployment Descriptor

To deploy your process in WSO2 Business Process Server, you need to create a simple deployment descriptor with basic information. The deploy.xml file configures one or more processes to use specific services. For each process, deploy.xml must supply binding information for partner links to concrete WSDL services. Every partner link used with a <receive> activity must be matched with a <provide> element, and every partnerLink used in an <invoke> activity must be matched with an <invoke> element in deploy.xml (unless that partnerLink has initializePartnerRole="false").

#### Formal Definition

The XML schema describing the deployment descriptor is available here. The root element, deploy, contains a list of all deployed processes from the deployment directory:

    <deploy>
     <process ...>*
     { other elements }
     </process>
    </deploy>

Each process is identified by its qualified name and specifies bindings for provided and invoked services:

    <process name = QName  fileName = String?  bpel11wsdlFileName = String? >
     (<provide> | <invoke>)*
     { other elements }
    </process>

Each process element must provide a name attribute with the qualified name of the process. Optionally, a fileName attribute can be used to specify the location of the BPEL process definition (the .bpel file). The fileName attribute does not need to be provided unless non-standard compilation options are used or the bpel11wsdlFileName attribute is used to specify a WSDL document for a BPEL 1.1 process.

Each <process> element must enumerate the services provided by the process and bind each service to an endpoint. This is done through <provide> elements which associates partnerLinks with endpoints:

    <provide partnerLink=NCName>
      <service name = QName port = NCName?>
    </provide>

Note, that only one partnerLink can be bound to any specified endpoint. The port attribute can be used to select a particular endpoint from the service definition.

##### Examples

A very simple process that would only be invoked would use a deploy.xml very similar to:

    <deploy xmlns="http://www.apache.org/ode/schemas/dd/2007/03"
    	xmlns:pns="http://ode/bpel/unit-test" xmlns:wns="http://ode/bpel/unit-test.wsdl">
    	<process name="pns:HelloWorld2">
    		<active>true</active>
    		<provide partnerLink="helloPartnerLink">
    			<service name="wns:HelloService" port="HelloPort"/>
    		</provide>
    	</process>
    </deploy>

See the complete example here. A deployment including two processes would look like:

    <?xml version="1.0" encoding="UTF-8"?>
    <deploy xmlns="http://www.apache.org/ode/schemas/dd/2007/03" xmlns:wns="http://wso2.org/bps/samples/LoanService" xmlns:dins="http://wso2.org/bps/samples/DILoanService" xmlns:xkns="http://wso2.org/bps/samples/XKLoanService">
      <process name="dins:DILoanService">
        <active>true</active>
        <provide partnerLink="LoanServicePL">
          <service name="wns:DILoanService" port="LoanServicePort"/>
    	</provide>
    	<invoke partnerLink="LoanServicePL">
    		<service name="wns:LoanServiceCallback" port="LoanServiceCallbackPort"/>
        </invoke>

      </process>
      <process name="xkns:XKLoanService">
        <active>true</active>
        <provide partnerLink="XKLoanServicePL">
    		<service name="wns:XKLoanService" port="LoanServicePort"/>
    	</provide>
    	<invoke partnerLink="XKLoanServicePL">
    		<service name="wns:LoanServiceCallback" port="LoanServiceCallbackPort"/>
        </invoke>

      </process>
    </deploy>

See the complete example here.

##### Additional Settings

###### In memory execution

For performance purposes, you can define a process as being executed only in-memory. This greatly reduces the amount of generated queries and puts far less load on your database. Both persistent and non-persistent processes can cohabit in WSO2 Business Process Server. To declare a process as in-memory just add an in-memory element in your deploy.xml:

    <process name="pns:HelloWorld2">
    	<in-memory>true</in-memory>
    	<provide partnerLink="helloPartnerLink">
    		<service name="wns:HelloService" port="HelloPort"/>
    	</provide>
    </process>

Be aware that in-memory executions introduces many restrictions on your process and what it can do. The instances of these processes cannot be queried by using the Management API. The process definition can only include one single receive activity (the one that will trigger the instance creation).

#### Undeploying a Process in WSO2 Business Process Server

There are two methods to undeploy a bpel package from WSO2 Business Process Server.

1. From the Deployed Packages menu item under the Business Processes section of the left pane of the Management Console.

   Here the deployed packages list is visible with each entry has a certain action named "Undeploy" associated with it. Once the link is clicked the selected package will be undeployed from the BPS_HOME/repository/deployment/server/bpel directory.

2. Manually removing the zipped process file

   The same result can be obtained by manually removing the bpel package from BPS_HOME/repository/deployment/server/bpel directory.

### Human Task Deployment

- Deploying a Human Task in WSO2 Business Process Server

#### Deploying a Human Task in WSO2 Business Process Server

Each deployment is a zipped file with all relevant deployment artifacts. At the minimum it should contain the human interaction definition - HI, human task configuration - hiconfig.xml, WSDL and XSDs.

Login to BPS Management Console by providing your credentials (default:- user:admin pass:admin). Go to Add HI menu item under the Human Task section of the left pane of the Management Console. Browse and select the zipped Human Task and upload it.

### Managing BPEL processes

You can manage processes from Manage/Processes in the navigator.

In the navigator, under Manage/Processes/List, there is a list of deployed processes (See Figure 4).

Figure 4

You can select a process and go to Process Information page (See Figure 5) and manage it.

Figure 5

You can view several information via Process Information page (See Figure 5). They are

- Process Details
  - Process ID
  - Version
  - Status - You can activate or retire the process from here. Once the process is retired, can't create new instance of it.
  - Deployed Date
  - Total Instances
  - Package Name
- Instance Summary - Number of Instances vs. Status
- Quality of Service Configuration - Managing security, throttling, response caching etc.
- WSDL details - Service level information
- Process Definition - BPEL code for the process
- Process Visualization - Graphical workflow of the process

#### Deployment Descriptor Editor

You can go to Deployment Descriptor Editor by clicking the link View or Edit Deployment Descriptor on any of the detailed process description pages.

This editor allows BPEL process administrators to configure process/instance/scope event generation, instance cleanup at run-time. Also it provides the other configuration details like MEX interceptors, process properties, provided services (inbound interfaces) and invoked partner services (outbound interfaces). This will modify the runtime process configuration without affecting the uploaded deployment artifact.

### Managing BPEL process instances

You can manage processes from Business Processes/Instances in the navigator.

In the navigator, under Business Processes/Instances, there is a list of deployed processes (See Figure 6).

Figure 6

You can click an instance ID and go to Instance Information page (See Figure 6) and manage it.

Figure 7

You can view several information via Instance Information page (See Figure 7). They are

- Instance Details
  - Instance ID
  - Process ID
  - Status - State of the instance can be managed from here
  - Date Started
  - Last Active Date
- Root Scope Information
- Variables - Current values of each variable created for the instance
- Activity Information - A list of activities with their status and other required information. If the instance is in active state and there are failed activities, they can be retried failed via the management console.

### QoS for BPEL processes

#### Quality of Service(QoS) Configuration for BPEL processes

Configuring Quality of Service(QoS) parameters like security, response caching etc. of a BPEL process is same as configuring QoS for any other service via WSO2 management console. But configuring QoS for a BPEL process can be differentiate in two ways.

- QoS for the BPEL process
- QoS for the partner links which interact with the BPEL process

##### QoS for the BPEL process

In WSO2 Business Process Server a BPEL process is exposed as a Web service. So once the process is deployed successfully, it will be listed out under Manage/Web Services in the navigator. So the process can be QoS configured via its Service dashboard. Service dashboard (See Figure 8) consists of a widget called Quality of Service Configuration to manage QoS.

Figure 8

Configuring security for the BPEL process is elaborated here.

##### QoS for the partner links which interact with the BPEL process

The partner links can be QoS configured via QoS Section of the Process Information page (See Figure 9) for the deployed process under Manage/Processes/List in the navigator. You can select a partner link from Partner Links drop down list and configure QoS for each of them specifically.

Figure 9

Configuring security for partner links is elaborated here.

### Securing BPEL processes

Configuring Security for a BPEL process can be looked in two ways. They are

- Securing for the BPEL process
- Securing for the partner links which interact with the BPEL process

#### Securing for the BPEL process

In WSO2 Business Process Server a BPEL process is exposed as a Web service. So once the process is deployed successfully, it will be listed out under Manage/Web Services in the navigator. So the process's security can be configured via a its Service dashboard. Service dashboard (See Figure 10) consists of a widget called Quality of Service Configuration to manage QoS. Refer "Adding Security Features" for more information on available security features.

Figure 10

#### Securing for the partner links which interact with the BPEL process

The partner links' security can be configured via QoS Section of the Process Information page (See Figure 11) for the deployed process under Manage/Processes/List in the navigator. You can select a partner link from Partner Links drop down list and configure security for each of them specifically. Refer "Adding Security Features" for more information on available security features.

Figure 11

### Invoking secured partner services

Invoking secured partner services is supported by WSO2 Business Process Server. Current release of BPS supports for partner services which are secured with WS-Security. To invoke secure services via a BPEL process, a user need to add few additional configuration files to BPEL process artifact. Then the required password callback handler, key-stores etc.

1. Configure the unified endpoint with relevant policy for the secured service endpoint

   To enable security to a particular service endpoint with the relevant security policy, two files need to be added to the BPEL process artifact. They are as follows.

   - Unified endpoint configuration
   - WS-Security policy

   Unified endpoint is the end-point configuration mechanism used in BPEL processes. A sample unified endpoint configuration is as follows.

       <wsa:EndpointReference
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                       xsi:schemaLocation="http://www.w3schools.com uep_schema.xsd"
                       xmlns:wsa="http://www.w3.org/2005/08/addressing"
                       xmlns:wsdl11="http://schemas.xmlsoap.org/wsdl/">
                   <wsa:Address>https://localhost:9443/services/SecurePartnerService1/</wsa:Address>
                   <wsa:Metadata>
                       <id>SInvokeEPR</id>
                       <qos>
                           <enableAddressing version="final" separateListener="true"/>
                       <enableWsSec policy="file:PolicySecurePartnerService01.xml"/>
                       </qos>
                   </wsa:Metadata>
               </wsa:EndpointReference>

   To invoke a secured partner service, relevant policy file should be mentioned and addressing module should be engaged. Refer <qos/> how it's configured. Then the relevant policy (in this case PolicySecurePartnerService01.xml) should be added to the BPEL process artifact in the correct relative path. You can find a sample process which invoke secured partner services based different security scenarios at [1].

2. Configuring password callback handlers or key-stores

   In addition, the policy file added to the BPEL process artifact may refer key-stores, password callback handlers etc. So user need to add them in relevant places. Password callback handlers can be placed in $CARBON-DIR/repository/components/lib dir. Key-stores can be added into the file system as referred by the policy file (In the sample mentioned at [1], the location for client.jks is repository/resources/security/client.jks according to PolicySecurePartnerService01.xml).

[1] - http://svn.wso2.org/repos/wso2/carbon/platform/trunk/products/bps/modules/samples/product/src/main/resources/bpel/2.0/SecurePartnerBPEL

### Versioning

If a package with existing package name is uploaded, all the processes in the package will be versioned. In this case, all the old processes in the package will be retired while a new version will be be deployed. Since there is only package level versioning, the new package should include all the processes defined in the old package, eventhough you may only need to update a single process in that package.

### Management API

Refer Management API for more details.