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

# User Guide

### Table of Content

- Deploying BPEL processes
- Managing BPEL processes
- Managing BPEL process instances
- QoS for BPEL processes
- Securing BPEL processes
- Invoking secured partner services
- Configuring JMS Transport
- Process Instance Cleanup
- Process Hydration and Dehydration
- Enabling Peer-to-Peer(P2P) Communication

## Deploying BPEL processes

### Process Deployment

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

### 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 Processes in Manage category of the left pane of the Management Console. Browse and select the zipped BPEL process(es). Upload the process(es).

   Figure 1

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. Select the BPEL package you want to undeploy from the Deployed Processes List page.

   Figure 2

   The Package Dashboard 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 too. (See Figure 3).

   Figure 3

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.

## 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

## 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 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 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/

## Configuring JMS Transport

Prerequisites - Start a JMS-provider. ActiveMQ is used here as the default configs are already added to axis2.xml (see step 4 below).

1. Add these required jars to $CARBON-HOME/repository/components/lib
   - activemq-core-5.4.1
   - geronimo-j2ee-management_1.1_spec-1.0.1
2. Start the server
3. Install the "WSO2 Carbon - JMS Transport Core Feature" to the product(WSO2-BPS). You can do this by Features link in the left side menu bar.
   Figure 12
4. Add the relevant JMS configs related to JMS transport listener to axis2.xml. You can do this by just uncommenting this element

       <transportReceivername="jms"class="org.apache.axis2.transport.jms.JMSListener"/>

   if you are using ActiveMQ.
5. Restart the server.

   If you have correctly configured, these logs will be shown during the server start-up.

       INFO - JMSSender - JMS Sender started
       INFO - JMSSender - JMS Transport Sender initialized...
       ...
       INFO - JMSListener - JMS Transport Receiver/Listener initialized...
       ...
       INFO - JMSListener - JMS listener started

6. Then you can configure JMS transport from service level via UI.

## Process Instance Cleanup

Process instance cleanup feature in WSO2 Business Process Server allows you to configure periodic process instance cleanup tasks based on various process instance properties to remove process instance data from WSO2 Business Process Server persistence storage.

### How to configure process instance cleanup

You can use 'Schedules' section in bps.xml to configure instance cleanup. 'Schedules' section can contain multiple 'Schedule' elements with multiple 'cleanup' elements. In each 'Schedule' element you can specify attribute 'when' which will be the time that the instance cleanup task get executed. Time is configured using cron expressions. Inside cleanup element you can use filters. In those filter elements you can specify various instance properties which will use to select the instance to be deleted.

#### Example Cleanup Configuration

Below example schedule cleanup task at 5:11 PM every day to clean completed process instances.

    <tns:Schedules>
            <tns:Schedule when="0 11 17 * * ?">
                <tns:cleanup>
                    <tns:filter><![CDATA[status=completed]]></tns:filter>
                </tns:cleanup>
            </tns:Schedule>
        </tns:Schedules>

## Process Hydration and Dehydration

One technique to reduce memory utilization of BPS engine is process hydration and dehydration. That means user can configure the hydration/dehydration policy at bps.xml in repository/conf directory. As well programmatically user can define a custom hydration/dehydration policy.

In bps.xml user can set the maximum age of a process before it is dehydrated via MaxAge element. And the maximum deployed process count can exist in memory at a particular time via maxCount attribute.

### Sample Process Dehydration Configuration

Below example policy with enable the dehydration policy and set the maximum deployed process count can exist in memory at a particular time to 100 and the maximum age of a process before it is dehydrated to 5 minutes.

    <tns:ProcessDehydration maxCount="100" value="true">
        <tns:MaxAge value="300000"/>
    </tns:ProcessDehydration>

## Enabling Peer-to-Peer(P2P) Communication

The usePeer2Peer property informs the BPEL engine not to use internal communications for sending messages between BPEL processes that may be executing within the same engine. The usePeer2Peer property has true as the default value.

    <dd:invoke partnerLink="..." usePeer2Peer="true">
    	<dd:service name="..." port="..."/>
    </dd:invoke>

Disabling P2P Communication

1. Add the attribute usePeer2Peer in the deploy.xml file if it is not already there.
2. Set this attribute value to false for the specific partner link.

    <dd:invoke partnerLink="..." usePeer2Peer="false">
    	<dd:service name="..." port="..."/>
    </dd:invoke>

When the value of this attribute is false, BPS engine will send the message to other process through the integration layer. If you have deployed your BPEL process and its partner services on the same WSO2 Carbon instance, you can avoid the network overhead using usePeer2Peer="false" for the particular partner interaction in deploy.xml.