WSO2 BPS - User Guide -

User Guide

Table of Content


Deploying BPEL processes

Process Deployment


Deploying a Process in WSO2 BPS

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 BPS

  1. Using the WSO2 BPS 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.

    Add BPEL
    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 BPS, 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:

<providepartnerLink=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:

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

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

<?xmlversion="1.0"encoding="UTF-8"?><deployxmlns="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"><processname="dins:DILoanService"><active>true</active><providepartnerLink="LoanServicePL"><servicename="wns:DILoanService"port="LoanServicePort"/></provide><invokepartnerLink="LoanServicePL"><servicename="wns:LoanServiceCallback"port="LoanServiceCallbackPort"/></invoke></process><processname="xkns:XKLoanService"><active>true</active><providepartnerLink="XKLoanServicePL"><servicename="wns:XKLoanService"port="LoanServicePort"/></provide><invokepartnerLink="XKLoanServicePL"><servicename="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 BPS. To declare a process as in-memory just add an in-memory element in your deploy.xml:

<processname="pns:HelloWorld2"><in-memory>true</in-memory><providepartnerLink="helloPartnerLink"><servicename="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).


Managing BPEL processes

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

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

Deployed Processes page
Figure 2

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


Process Information page
Figure 3

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


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 4).


Instance List page
Figure 4

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


Instance Information page
Figure 5

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


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

In WSO2 BPS 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 a its Service dashboard. Service dashboard (See Figure 6) consists of a widget called Quality of Service Configuration to manage QoS.

Service dashboard
Figure 6

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 7) for the deployed process under Business Processes/Processes in the navigator. You can select a partner link from Partner Links drop down list and configure QoS for each of them specifically.


Process Information Page
Figure 7

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

In WSO2 BPS 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 8) consists of a widget called Quality of Service Configuration to manage QoS. Refer "Adding Security Features" for more information on available security features.

Service dashboard
Figure 8


Securing for the partner links which interact with the BPEL process

The partner links' security can be configured via Process Information page (See Figure 9) for the deployed process under Business Processes/Processes 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.

Process Information Page
Figure 9


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.
    Adding JMS transport feature
    Figure 10
  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.


Deployment Best Practices

Default distribution of WSO2 BPS comes with embedded H2 database as BPEL engine's persistence storage and other settings which are suitable for use in development environment. But when you are going to production with WSO2 BPS, there are several configurations you need to change according to your production requirements. These configurations will change based on how much requests BPS is going to handle per second, your auditing and monitoring requirements, performance requirements and nature of your process. Following are the main things you should do before going production with WSO2 BPS.

In addition to above things you should be careful when deploying WSO2 BPS in virtualized environments. We have seen random increase of network latencies and random performance degradations when running on VMs.

Note 1: Above mention configuration optimizations are true for Apache ODE also.

Note 2: Above mention best practices are valid for WSO2 BPS 2.1.0 and upward. You can do the above optimizations to older versions WSO2 BPS, but configurations and configuration mechanisms will be different. All of the above optimizations are supported by Apache ODE, but configuration is very different from WSO2 BPS.


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 BPS 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:ProcessDehydrationmaxCount="100"value="true"><tns:MaxAgevalue="300000"/></tns:ProcessDehydration>