WSO2 BPS - User Guide

[ Documentation Index ]

WSO2 Business Process Server (BPS) User Guide

The User Guide describes how to configure the WSO2 BPS 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 BPS

Please refer the Installation Guide for details on how to install WSO2 BPS.

Using WSO2 BPS

Configuring WSO2 BPS

External Data Source Configuration

Setting up Database Server
WSO2 BPS uses Apache ODE as it's BPEL engine and Apache ODE can be configured to use external database other than the embedded H2 databse as it's persistence storage. First you must create a database in your preferred database server and load the database schemas provided to that database.
  1. Set up and start your database server.
  2. Create a database.
  3. Load the BPS schema into that database using provided SQL scripts. For example if you are using Oracle as your databse server, use oracle.sql script located inside 'dbscripts/bps' directory to create the BPS schema.
Configuring a Data Source
Definition of the reusable database sources can be done using datasources.properties file located inside WSO2 BPS 'repository/conf' directory under BPS root directory. It is possible to configure any number of data sources. Data source support was developed based on Apache dbcp datasources. Configuration is somewhat similar to the log4j appender configuration. Following steps must be follow to create a simple data source. If you need to specify furthur configuration paramaeters look at parameters document from Apache Commons. WSO2 BPS data sources support all the parameters support by Apache dbcp and you must follow the synapse.datasources.<data source name>.<parameter>=<parameter value> pattern when specifying parameters for the data source. You can use any of the parameters supported by Apache dbcp to replace 'parameters' field.
  1. Create file named 'datasources.properties' inside 'repository/conf' directory located under the WSO2 BPS root directory.
  2. First you have to specify data source names, initial context factory and provider port. Here is an example which creates only one data source named 'bpsds'. (You may need to create another datasource to configure a seperate database for Human Tasks) 
                        synapse.datasources=bpsds
                    synapse.datasources.icFactory=com.sun.jndi.rmi.registry.RegistryContextFactory
                    synapse.datasources.providerPort=2199
  3. Then you have to specify the properties for previously defined data sources. In this case we have only one data source and here is the completed datasource.properties file for MSSQL server database called 'bps' with the username 'sa' and password 'root123'. In this particular configuration we used jTDS database driver. You have to specify driverClassName, url, username, password and dsName properties according to the JDBC driver you are using and Database server configuration you are using. 
                        synapse.datasources=bpsds
                    synapse.datasources.icFactory=com.sun.jndi.rmi.registry.RegistryContextFactory
                    synapse.datasources.providerPort=2199

                    synapse.datasources.bpsds.registry=JNDI
                    synapse.datasources.bpsds.type=BasicDataSource
                    synapse.datasources.bpsds.driverClassName=net.sourceforge.jtds.jdbc.Driver
                    synapse.datasources.bpsds.url=jdbc:jtds:sqlserver://192.168.1.2:1433/bps
                    synapse.datasources.bpsds.username=sa
                    synapse.datasources.bpsds.password=root123
                    synapse.datasources.bpsds.dsName=bpsds
                    synapse.datasources.bpsds.maxActive=100
                    synapse.datasources.bpsds.maxIdle=20
                    synapse.datasources.bpsds.maxWait=10000
  4. After saving the datasources.properties file, copy the JDBC driver jar file into the 'repository/components/lib' directory under WSO2 BPS root direcotry.
Configuring BPS to use the Data Source created
After you configure the data source properly, you have to configure WSO2 BPS's BPEL engine to use the data source you have created. Therefore, you have to modify the bps.xml configuration file located inside BPS_HOME/repository/conf directory. The default database configuration is looks like <DataBaseConfig mode="EMBEDDED"/>. You have to change the DB mode to EXTERNAL and update the datasource. 
    <tns:DataBaseConfig mode="EXTERNAL">
        <tns:DataSource name="datasource name">
          <tns:JNDI contextFactory="class name" providerURL="url"/>
        </tns:DataSource>
    </tns:DataBaseConfig>
For example, if we use the data source we created ealier, the configuration will look like following. 
    <tns:DataBaseConfig mode="EXTERNAL">
        <tns:DataSource name="bpsds">
          <tns:JNDI contextFactory="com.sun.jndi.rmi.registry.RegistryContextFactory" providerURL="rmi://localhost:2199"/>
        </tns:DataSource>
    </tns:DataBaseConfig>
Configuring BPS to use the Data Source created for Human Tasks
Human Tasks use H2 as default embedded database. You can configure a seperate datasource for Human Tasks. You can find database schemas in BPS_HOME/dbscripts directory. After you configure the data source properly, you have to configure WSO2 BPS's Human Task's engine to use the data source you have created. For that you have to create humatask.xml configuration file inside BPS_HOME/repository/conf directory. If we have created a datasource called "htds", then sample humantask.xml file is given below. 
<HumanTask xmlns="http://wso2.org/humantask/schema/humantaskconfig">
	<PersistenceConfig>
		<DataSource>htds</DataSource>
		<JPAVendorAdaptor>org.wso2.carbon.humantask.runtime.dao.jpa.vendor.OpenJpaVendorAdapter</JPAVendorAdaptor>
		<GenerateDdl>true</GenerateDdl>
		<ShowSql>false</ShowSql>
		<JNDIInitialContextFactory>com.sun.jndi.rmi.registry.RegistryContextFactory</JNDIInitialContextFactory>
		<JNDIProviderUrl>rmi://localhost:2199</JNDIProviderUrl>
	</PersistenceConfig>
</HumanTask>
Registry Configuration
You must leave Registry configuration in bps.xml as it is. If you want to configure registry to use external data base you must follow the registry configuration document.
Other BPEL Engine Related Configurations

Human Task Deployment

Deploying a Human Task in WSO2 BPS

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.

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
  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: 
<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 BPS. 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).

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.

Events

WSO2 BPS generates events to let you track what is exactly happening in the engine and produces detailed information about process executions. These events are persisted in BPS's database and can be queried using the Management API. The default behaviour for the engine is to always generate all events for every executed action. However from a performance standpoint it is better to deactivate some of the events you're not interested in (or even all of them). Inserting all these events generates a non-negligible overhead.

Event Types

The following table details each event possibly generated by ODE:
Event Name Process/Scope Description Type
ActivityEnabledEvent Scope An activity is enabled (just before it's started) activityLifecycle
ActivityDisabledEvent Scope An activity is disabled (due to dead path elimination) activityLifecycle
ActivityExecStartEvent Scope An activity starts its execution activityLifecycle
ActivityExecEndEvent Scope An activity execution terminates activityLifecycle
ActivityFailureEvent Scope An activity failed activityLifecycle
CompensationHandlerRegistered Scope A compensation handler gets registered on a scope scopeHandling
CorrelationMatchEvent Process A matching correlation has been found upon reception of a message correlation
CorrelationNoMatchEvent Process No matching correlation has been found upon reception of a message correlation
CorrelationSetWriteEvent Scope A correlation set value has been initialized dataHandling
ExpressionEvaluationFailedEvent Scope The evaluation of an expression failed dataHandling
ExpressionEvaluationSuccessEvent Scope The evaluation of an expression succeeded dataHandling
NewProcessInstanceEvent Process A new process instance is created instanceLifecycle
PartnerLinkModificationEvent Scope A partner link has been modified (a new value has been assigned to it) dataHandling
ProcessCompletionEvent Process A process instance completes instanceLifecycle
ProcessInstanceStartedEvent Process A process instance starts instanceLifecycle
ProcessInstanceStateChangeEvent Process The state of a process instance has changed instanceLifecycle
ProcessMessageExchangeEvent Process A process instance has received a message instanceLifecycle
ProcessTerminationEvent Process A process instance terminates instanceLifecycle
ScopeCompletionEvent Scope A scope completes scopeHandling
ScopeFaultEvent Scope A fault has been produced in a scope scopeHandling
ScopeStartEvent Scope A scope started scopeHandling
VariableModificationEvent Scope The value of a variable has been modified dataHandling
VariableReadEvent Scope The value of a variable has been read dataHandling
The second column specifies whether an event is associated with the process itself or with one of its scopes. The event type is used for filtering events.

Filtering Events

Filtering at the process level

Using the deployment descriptor, it is possible to tweak events generation to filtrate which ones get created. First, events can be filtered at the process level using one of the following stanza: 
<dd:process-events generate="all"/> <!-- Default configuration -->

<dd:process-events generate="none"/>

<dd:process-events>
    <dd:enable-event>dataHandling</dd:enable-event>
    <dd:enable-event>activityLifecycle</dd:enable-event>
</dd:process-events>
The first form just duplicates the default behaviour, when nothing is specified in the deployment descriptor, all events are generated. The third form lets you define which type of event is generated, possible types are:

Filtering at the scope level

It is also possible to define filtering for each scope of your process. This overrides the settings defined on the process. In order to define event filtering on a scope, the scope activity MUST have a name in your process definition. Scopes are referenced by name in the deployment descriptor: 
<dd:deploy xmlns:dd="http://www.apache.org/ode/schemas/dd/2007/03">
    ...
    <dd:process-events generate="none">
        <dd:scope-events name="aScope">
            <dd:enable-event>dataHandling</bpel:enable-event>
            <dd:enable-event>scopeHandling</bpel:enable-event>
        </dd:scope-events>
        <dd:scope-events name="anotherScope">
            <dd:enable-event>activityLifecycle</bpel:enable-event>
        </dd:scope-events>
    </dd:process-events>
    ...
</dd:deploy>
Note that it is useless to enable an event associated with the process itself when filtering events on scopes. The filter defined on a scope is automatically inherited by its inner scopes. So if no filter is defined on a scope, it will use the settings of its closest parent scope having event filters (up to the process). Note that what gets inherited is the full list of selected events, not each event definition individually.

Event Listeners

WSO2 BPS lets you register your own event listeners to analyse all produced events and do whatever you want to do with them. To create a listener, you just need to implement the org.apache.ode.bpel.iapi.BpelEventListener interface. Then add your implementation in the server's classpath (BPS_HOME/repository/components/lib) and add a property in bps.xml giving your fully qualified implementation class name: 
<tns:WSO2BPS xmlns:tns="http://wso2.org/bps/config">
  ...
    <tns:EventListeners>
        <tns:listener class="org.wso2.bps.samples.eventlistener.CustomEventListener"/>
    </tns:EventListeners>
  ...
</tns:WSO2BPS>
You can try the sample event listener that is shipped with WSO2 BPS by adding abouve configuration to the bps.xml and restart the server. You can find the source of the sample implementation of event listener here.

Manipulating Endpoints

Partner endpoinds can be configured to enable security and etc, using the deployment descripter (deploy.xml). The supported configurations are shown below. 
<deploy xmlns="http://www.apache.org/ode/schemas/dd/2007/03">
 ...
   <process name="QName">
  ...
      <invoke partnerLink="string">
        <service name="QName" port="string">
            <endpoint xmlns="http://wso2.org/bps/bpel/endpoint/config">
                <serviceDescription location="url"/>?
                <enableSec policyLocation="url"/>?
                <address uri="string"/>?
                <mex-timeout value=""/>?
                <enableAddressing value="true|false"/>?
                <httpOptions>
                    <request-chunk value="true|false"/>?
                    <protocol-version value="1_0|1_1"/>?
                    <request-gzip value="true|false"/>?
                    <accept-gzip value="true|false"/>?
                    <protocol-content-charset value="string"/>?
                    <connection-timeout value="seconds"/>?
                    <socket-timeout value="seconds"/>?
                    <protocol-max-redirects value="int"/>?
                    <proxy host="url" port="int" domain="url" user="string" password="string"/>?
                    <default-headers>
                        <header name="string" value="string"/>*
                    </default-headers>?
                </httpOptions>?
            </endpoint>
          </service>
       </invoke>
     ...
   </process>
 ...
</deploy>
Sample configuration can be found here.

BPEL Extensions

You can find more details on BPEL extensions here.

Configure Transaction Factory

You can specify an external or custom transaction factory class to take care of transactions. The following onfiguration in BPS_HOME/repository/conf/bps.xml can be used to set transaction factory. 
<tns:WSO2BPS xmlns:tns="http://wso2.org/bps/config">
  ...
    <tns:TransactionFactory class="class name"/>
  ...
</tns:WSO2BPS>

Message Exchange Interceptors

Message Exchange Interceptors can be used to pull out data as well as to manipulate them by enabling interception of parntner/server invocations. MEX interceptors can be used in four different situations. You need to implement MessageExchangeInterceptor interface to implement a custom message exchange interceptor and drop the respective jar to the BPS_HOME/repository/components/lib/ directory. Then, add the following configuration entry to the bps.xml in BPS_HOME/repository/conf directory 
<tns:WSO2BPS xmlns:tns="http://wso2.org/bps/config">
  ...
    <tns:MexInterceptors>
        <tns:interceptor class="class name"/>
    </tns:MexInterceptors>
  ...
</tns:WSO2BPS>

Configure OpenJPA specific properties

You can configure and fine tune OpenJPA by specifying OpenJPA properties in BPS_HOME/repository/conf/bps.xml file. 
<tns:WSO2BPS xmlns:tns="http://wso2.org/bps/config">
  ...
    <tns:OpenJPAConfig>
        <tns:property name="openjpa.FlushBeforeQueries" value="true"/>
        <tns:property name="property name" value="value"/>
        ...
    </tns:OpenJPAConfig>
  ...
</tns:WSO2BPS>

Configure Multi Threaded HTTP Connection Manager

HTTP connection manager should be configured to be sync with the concurrent HTTP connections that should be in the BPS server. 
<tns:WSO2BPS xmlns:tns="http://wso2.org/bps/config">
  ...
    <tns:MultithreadedHttpConnectionManagerConfig>
        <tns:maxConnectionsPerHost value="20"/>
        <tns:maxTotalConnections value="200"/>
    </tns:MultithreadedHttpConnectionManagerConfig>
  ...
</tns:WSO2BPS>

Configure Process Instance Cleanup Tasks

BPS allows you to shcedule instance cleanup task which runs daily at specified time. It is possible to configure the age of completed and failed instances seperately. Say, you need to delete all the completed instances after one day and all the failed instances after 2 days and you need to run this cleanup task in the most inactive time, say, at 20:00:00 hour. The sample configuration is given below for the above mensioned situation. This should be configured in bps.xml in BPS_HOME/repository/conf directory 
<tns:WSO2BPS xmlns:tns="http://wso2.org/bps/config">
  ...
    <tns:ProcessInstanceCleanupConfig>
        <tns:completed lifeTime="1"/>
        <tns:failed lifeTime="2"/>
        <tns:scheduledTime value="20:00:00"/>
    </tns:ProcessInstanceCleanupConfig>
  ...
</tns:WSO2BPS>