Configuring and Managing BPEL Processes with WSO2 Business Process Server-Part 1

  • By Ishara Premadasa
  • |
  • 6 Sep, 2011


A business process configuration carries various information that stands unique for the certain process and these settings needs to be configured properly in order to manage and run the process with the expected features and performance. Deployment descriptor in a bpel package is the basic file which is used in this purpose. It is specific to Apache ODE and used to link partnerlinks,porttypes etc. with wsdl service in bpel processes. The following is a detailed guide for configuring these fields in a bpel process to meet our storage and performance expectations.

Applies to

WSO2 BPS 2.1.0


Configuring the fields of a bpel process using deployment descriptor

What is deployment descriptor?

Configuring the process state

Run the process in-memory

Configuring process events

Configuring instance data cleanups for a process

Configuring the invoked and provided services by the process

Configuring Message Exchange Interceptors (Mex-interceptors)

Creating process properties


Configuring the fields of a bpel process using deployment descriptor

What is deployment descriptor?

Deployment descriptor carries the basic configuration information which needs to deploy the process in BPS. The deploy.xml file configures one or more bpel processes. 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 partner link used in an <invoke> activity must be matched with an <invoke> element in deploy.xml (unless that partnerLink has set its initializePartnerRole into "false" value).

Read the XML schema for
the ODE deployment descriptor.

Following is a sampled deploy.xml file of a simple process which includes a few configuration fields.The root element <deploy>, contains a list of all deployed processes in the deployment package under separate <process> element tags. Each <process> element must provide a name attribute with the qualified name(QName) of the process. Note that we can declare more than one process inside our deploy.xml file.

The deployment descriptor can be used to configure seven types of fields in a business process given below.

  1. Process state
  2. In-memory state
  3. Services provided or invoked by the process
  4. Process events
  5. Mex interceptors
  6. Process properties
  7. Process cleanups

Now let’s see how to configure each of these fields for our bpel process.

Configuring the process state

The process state controls overall access to the process which specifies whether the process should be activated or retired once it is deployed. When the state is ‘active’ new instances can be created and accessed from the process and once it is in ‘retired’ state new instances cannot be created. However the existing instances are permitted to be completed normally.

A process can be set into ‘active’ state by adding an <active> element into the deployment descriptor as declared above. The <active> state is set as ‘true’ by default. In other words whether we include <active> element or not, a process is in active state at deployment stage if we haven’t explicitly declared it as a ‘retired’ process.

Figure 1 : A process which is in active state at the deployment

Meanwhile to set a process into ‘retired’ state <retired> element is used in the deployment descriptor. The default value for this is ‘false’ in general. It is also possible to active or retire a process using ‘Status’ option under the ‘Process Details’ table in the ‘Process Information’ page (refer figure 1) in the web console.

Run the process in-memory

Considering the performance aspects, a process can be configured to execute only in memory, as opposed to being persisted in the database. Doing this can significantly increase our application performance and reduce the load on the database, at the expense of recovery guarantees.

To declare a process to execute in-memory, an <in-memory> element is added into the deployment descriptor as shown below.As the default value this is declared ‘false’ for a process.

However in-memory processes have many limitations when it comes to execute their instances. They can only invoke synchronous request-response type message exchanges. Also the process definition can only include one single receive activity which is the instantiating receive activity.
In-memory instances are not visible in the Console and therefore cannot be managed like persistent instances too.

Configuring process events

Why it is needed to configure process events?

WSO2 BPS generates process events to let us track what is exactly happening in the bpel engine and produces detailed information about process executions. These events are persisted in BPS embedded H2 database and can be queried using the BPS Management API. In general bpel engine generates all events for each executed process if they are not configured from the process level. However from the performance aspect, this generates quite a large amount of unwanted data and introduces a significant performance overhead.Therefore it is better to deactivate some of the events (or even all of them) which are not necessary for a certain process.

Event types

There are five types of events can be declared for a process as activityLifecycle, instanceLifecycle, dataHandling, scopeHandling and correlation. Each event type has several sub categories under it. Some of these sub categories can be declared in process level while some must be associated with a specific scope in the process. In the next section i am going to explain how to filter these events in either process or scope level.

The following table displays all event types generated by WSO2 BPS.

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

Filtering events

The ‘generate type’ of a process is used to configure the process level enabled event generation. This field is an optional tag in the deployment descriptor which can be used to either activate all events or deactivate all events for a process.

To declare the process generate type ‘generate’ tag is used in deploy.xml file under <process-events> element with its value set into ‘all’ or ‘none’. As an example let’s say that we would like to generate all events. Hence;

Note that it is not essential to declare to generate all events like this, since it is done by bpel engine as default. However if it is needed to deactivate
events generation it can be done by this way.

Both the above mentioned types can be used to declare events as a whole in process level. However if it is required to specify certain event types to be only generated with a given process this approach will not be sufficient. In that case we can declare the list of necessary event types with <enable-event> element as follows.

In this manner the bpel engine will only generate process events under above three categories. If an instance is created with this process, the database will be only stored with data generated for the above three events.

Apart from the previous configurations, events can be declared with some specific scope too. These kind of events are called scope level enabled events. Scopes are referenced by name (which is simply a string value) in the deployment descriptor. The scope name MUST be defined in our process definition when we create the scope activity and we are using this name to filter the events in that scope.

Filtering at the scope level can override the settings defined on the process. Hence there is no use of re-defining an event into a scope, if the event is already defined in the process level. We will see a little example to clarify this.

The example shown below displays an incorrect process events configuration of a process.

Though the expectation is that only ‘scopeHandling’ will be generated inside the scope named ‘anotherScope’ in this incident, the events ‘instanceLifecycle’ and ‘dataHandling’ will also be generated at the execution time since they become inherited from the process level. Also since it is already defined in process level there is no need to explicitly declare ‘scopeHandling’ in the scope level again.

In conclusion, whatever the events that are enabled in process level will be generated in scope level too. In addition to that more information(if necessary) can be generated in scope level using some additional events. A correct configuration of scope events is displayed in the example below.

No events have been generated in process level here and the events ‘scopeHandling’ and ‘instanceLifecycle’ will be generated only in the scope level. We can declare more than one scope with different event configurations in this manner.

Configuring instance data cleanups for a process

A process instance in execution state consumes a lot of data during its execution cycle. When the instance has completed its operation, there may be a larger amount of data remained in the database, mostly because of its own variables and received/sent messages. All of these are XML documents and in some cases, sizable ones.Therefore a mechanism is needed to remove process instance data including the instance state with its variables, scopes and correlation, messages it has received and sent and execution events from WSO2 BPS persistence storage on demand. The cleanup configurations for a process is used on this purpose.

Meanwhile it will be useful to know how to open the BPS storage and monitor these data stored in the database at this point since it is going to be displayed in the upcoming examples. A detailed guide on monitoring the data in BPS H2 database is provided as an annex here.

Categories of cleanups

There are 5 different categories of cleanups can be defined in deployment descriptor and each level can be turned on or off separately.The following is a brief explanation about each of them. Note that cleanups are set off in a process by default.

1. Instances

Clears all the data associated with a created process instance from the storage. This includes the instance_ID, created date, execution state, last active time, previous state, instantiating correlation id, process_ID and also the rootscope_ID. As all the instance related information have been removed from the database, it can be noticed that this instance is not recorded in Instances menu item under the Business Processes section of BPS.
The sub categories falls under ‘instance’ category in the storage is ODE_PROCESS_INSTANCE and EXECUTION_STATE.

2. Variables

Clears various variable data which was generated during an instance execution. Some of the fields to be cleared are scope_ID, scope name, and scope state, partnerlink_ID, partner session_ID, partnerlink name, input/output variable names and xml data.

Figure 2: ODE_XML_DATA stored in H2 database after an instance execution

To verify the removal of variable data, visit the Instance Information page of the management console (click an instance ID and it will be directed to Instance Information page). Notice that Root Scope Information section will not be visible under Instance Information after we configure a process to clean the instance variables information.

Variables cleanup will remove ODE_SCOPE, ODE_XML_DATA, ODE_PARTNER_LINK data from our persistent storage.

3. Messages

Clears all the message data and headers, message exchange_IDs, message generated time etc. information. The data under the ODE_MESSAGE, ODE_MESSAGE_ROUTE, ODE_MEX_PROPS and ODE_MESSAGE_EXCHANGE sections will be cleared.
Figure 3 displays the message exchange data stored in the BPS’s embedded H2 database during a time of process execution.

Figure 3: Message exchange data stored in the BPS’s embedded H2 database

4. Correlations

The data which belongs to correlation sets, their IDs type of information which falls under ODE_CORRELATION_SET, ODE_CORSET_PROP sections of the storage are cleared.

5. Events

The ‘events’ category is capable of clearing the data of process events generated in a certain instance execution and once enabled this will remove the data associated with all process and scope level events.
To verify this, visit the ‘Activity Information’ section of the ‘Instance Information’ page after creating an instance.This section generally includes the events generated under ‘activityLifecycle’ type during the execution of process related activities. It can be seen that the section is empty under event cleanup activation.

How to cleanup instance data?

Now let’s see how to configure an instance data cleanup for a process with WSO2 BPS. An element called <cleanup> is added into the deployment descriptor for this purpose. There are three occasions where cleanups can be invoked for a process as success/failure instances or invoke for always. If the cleanups are invoked in success level, it will only clear the instance data by the time where an instance is successfully created and so as for the failure level. If it is on for ‘always’ both these levels will be considered.The following configuration invokes cleanup for both these times.

This will clean all data on either successful or faulty completions of instances. Note that it is not needed to define specific categories or all, when the instance cleanup is on for ‘always’ type. But if it is expected to declare a few cleanup categories to success level and need to declare different categories under failure instances cleanup, both those types must be declared separately in the deployment descriptor. An example would be as follows.

Meanwhile all the cleanups for either success or failure instances can be enabled by declaring it as category ‘all’. In this manner there is no need of declaring the five categories separately for the process.

Invalid cleanup configurations

Keep in mind that a declared cleanup configuration can be an invalid one, as some of the categories need to be invoked all together. As an example the ‘instance’ category must be declared along with both ‘variables’ and ‘correlations’ categories.

Therefore if a wrong combination of cleanups is declared, the bpel package deployment will fail at the deployment time. as shown in figure 4.

Figure 4 : An invalid cleanup categories combination

Configuring the invoked and provided services by the process

The deployment descriptor should carry the declarations of all the services provided and invoked by the process and bind each service to an endpoint. This is done through <provide> and <invoke> elements which associates partnerlinks with endpoints. Only a single partnerlink can be bound to a specified endpoint for any provided or invoked service.The port attribute in <service> element can be used to select a particular endpoint from the service definition.

Note that each process must carry at least one provided service at the minimum upto any amount of maximum services. However it is all right for a process to not having any invoked services. In case that deploy.xml contains more than one process the services provided and invoked by each process must be declared separately within the <process> element.

Here is an example process with several services.

Configuring Message Exchange Interceptors (Mex-interceptors)

The interception of message exchanges which enter or leave the server is a mechanism provided by Apache ODE. There are two types of message exchanges. There is my-role message exchange which is the incoming message exchange of the process and the outgoing message is called as partner-role message exchange. They can be intercepted in following points.

  • When the BPEL server is invoked, before any attempt to route the message exchange to a process.
  • When the BPEL server is invoked, after the message exchange has been routed to the process.
  • When the BPEL server is invoked, after the message exchange has been routed to the process
    and it has been determined that a new instance needs to be created.
  • When a partner link is invoked.

Message exchange interceptor is a Java class with an argumentless constructor and it should implement org.apache.ode.bpel.intercept.MessageExchangeInterceptor interface. The following is a model interceptor class which can be used to limit the number of active instances count for a process into 10.

After creating the class it can be used with the deployment descriptor as follows.

  1. Drop the respective jar to the BPS_HOME/repository/components/lib/ directory.
  2. Add the following configuration entry to the bps.xml in BPS_HOME/repository/conf directory. ( When the bps.xml file is opened in WSO2 BPS 2.1.0, the format of a message interceptor entry declared within comments is visible in the document like this.
  3. <!-- BPEL Message Exchange Interceptors. Used to track and handle incoming and out going
             Messages from BPEL Processes.  -->
            <tns:interceptor class=""/>
        </tns:MexInterceptors> -->
  4. Now simply remove the comment tag in above declaration and add the pre-written class name (Let’s say here.
  5. Deployment descriptor for this mex-interceptor can be configured by adding it under <mex-interceptors> element as shown below.

Configuring process properties

What is a property?

A process property is a name-value pair which is identified by a QName and can carry a string as value. A property can be defined according to the user’s wish and can be used in configuring process models and their instances.As an example instead of hard coding some variable value for a certain process, the same field can be read by including it as a property in our process in which way we can reconfigure the process without having to redeploy the process again.

Apart from that, all instances of a process model share the same set of process properties. If a process property changes, it changes for all instances.

How to create a property?

There are two ways to create a property for a process.

1. By declaring it statically in the deployment descriptor,

2. By setting the property using the Process Management API, class provides the following method to set a property.

How to use process properties?

To read process properties in a BPEL process, we can use the non-standard XPath extension bpws:process-property(propertyName). As an example this can be used in a transition condition or in an assign activity as follows.The fixed interest’s value 2000, will be read and assigned into ‘interest’ when the process executes.


Starting the H2 database to view the instance data storage

WSO2 BPS uses embedded H2 database. To login the database follow the given steps.

  1. Go to H2 Database Engine site and download
    the latest stable version.Extract the zipped archive into a directory in your local disk.Let's say
  2. Goto H2_Engine_Home/bin and run the script.

    H2_Engine_Home/bin$ sh

  3. The login window to the database will be appeared in our web browser as shown below.
    Then set the fields in the log in window as follows.
    • Saved Settings : Generic H2 (Embedded)
    • JDBC Url: jdbc:h2:/BPS_HOME/repository/database/jpadb
      (i have given home/isha/Programs/BPSpacks/wso2bps-2.1.0/repository/database in this case.)
    • Username : wso2carbon
    • Password: wso2carbon
  4. Click the ‘connect’ button to login.
  5. Now we can view the data generated in various process executions.

Figure 5: H2 database login window


A business process deployed in WSO2 BPS can be executed with different configurations by simply using its deployment descriptor. In this article we have discussed the ways of configuring most of those important fields in the deployment descriptor. All the sample codes given above are also possible to try out with your bpel process after reading this article and given references.


[1]. WSO2 BPS 2.1.0 Documentation

[2]. Apache ODE User Guide


Ishara Premadasa

Undergraduate, Dept. of Computer Science and Engineering

University of Moratuwa

[email protected]


About Author

  • Ishara Premadasa
  • Solutions Engineer
  • WSO2