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.
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 Derby 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.
Set up and start your database server.
Create a database.
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 'conf' directory under BPS root directory. It is possible to configure any number of data sources,
but for BPS you need only one data source. 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.
Create file named 'datasources.properties' inside conf directory located under the WSO2 BPS root
directory.
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'.
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 MS SQL 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.
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. For that you have to modify the bps.xml configuration file located inside
BPS_HOME/conf directory.
The default data base configuration is looks like <dbConf mode="EMBEDDED"/>. You have to change the
DB mode to EXTERNAL and specify you configuration like following.
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.
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
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.
Manually copying the zipped process file
To deploy manually, just copy the zipped process file containing your artifacts, to the BPS_HOME/Repository/bpel/
directory.
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:
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:
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).
Process Deployment Best Practices
When there are calls from one BPEL process to another BPEL process deployed same BPS, BPS will bypass
the Axis2 intgeration layer and will use process to process communication. When BPS is using process to
process communication, both processes must use same DAO implementation. Two process can't talk to each
other when one process is in-memory process and other is persistent.
Process Versioning
Introduction
Once you deploy your newly designed business processes, there may be situations where you'll identify
some issues with your current process. To fix the issues you need to modify your BPEL process definition.
But there may be process instances created from old process definition and you can't simply deploy the
new version. Depending on your process those process instances will take hours or days to complete. So you
need some kind of versioning support in your process engine to handle this situation.
Also it's hard to migrate existing process instaces to the new version. Process engine will have to
calculate differences between versions to habdle this. So migrating to the new process definition is not the
ideal solution.
In WSO2 BPS we handle this thing by keeping the old process definition by forcefully retiring it and all the
process instances created from old process definition will funtion normally. All the requests which need
creation of a process instance will be hand over to the new process definition.
How versioning works
Versioning is based on the fact that, instead of directly updating the original process definition
(leaving its instances to their dreadful fate), another new version of this definition is created.
The older one is declared retired so no new executions can be started on that one, the new process is
the one to be used now on. But running instances can still finish their job peacefully as the process
they've been using to execute so far is still available and unchanged.
WSO2 BPS's process versioning is developed based on hot update feature of Apache Axis2 deployers. Process
versioing will not depends on deployment mechanism(through admin console or file copy) like in Apache ODE.
Once you copy or upload the new BPEL archive, deployer will detect it based on last modified time and do
the neccessary work to deploy the new process definition and retire the old process definition.
When BPEL archive is deployed, BPS will pick the newly deployed archive and extract it to a directory in
bpel repository. This extracted directory name will has the global version number appended to it. All processes
in this archive will share this version number. Once new version of process archive is deployed, new directory
will get created with the new version number appended to it's name. That's how BPS versioning is implemented.
When you undeploy a BPEL package, all the versions will get undeployed automatically. When you redeploy a old
package there will not be any processes for older versions.
Process Versioning Best Practices
There couple of scenarios current versioning mechanism cannot handle, so that the user must pay attention
to the best practices described below.
WSO2 BPS cannot detect the difference between number of processes in BPEL archive. For example if
there are two processes in the first version of the archive and new version will only have one process,
BPS will retire both processes in older archive. So BPEL archives must not change the number of processes
contains in different versions and only change should be in the process definitions.
Users must pay attention to the external Web Service interface exposed by processes in different versions.
Conflicts in web services operations like schema changes will effect the older process instances.
For example if there is a receive in process definition which doesn't use for new instance creations,
and changes in WSDL operation definition corresponding to that receive can cause problems in
process instances created from older process version.
When you deploy a new version of your process, you will also find older versions of the process in the
process list and current version of BPS allow users to activate those retired old versions. This will
break the functionality of management API and users must be careful when activating processes. Fix will
be available in the next release.
Two different BPEL processes should not have same WSDL service definition in same namespace. This will
remove the reference for older process in the Axis service and breaks the management API. When different
process with existing WSDL service name and namespace is uploaded, old Axis service will get removed from
Axis configuration and older process will get abondoned. The new service will has the reference to new
process.
Management API
Ode has a complete management API
WSO2 BPS 1.1.0 ships with a new secured management API to check which processes are deployed, running and
completed instances, variables values and more.. You can find how to on using management API
here.
Current management API is not finalised yet. There are things that we can improve. Suggestions are welcome
for improvements.
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:
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:
instanceLifecycle
activityLifecycle
dataHandling
scopeHandling
correlation
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:
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:
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
BPEL Extensions
You can find more details on BPEL extensions here.
