How to perform correlation during process instance startup

Correlation

Let us assume we have set of BPMN process instances with various values for a given variable "var1". Correlation is a mechanism of identifying the process instance with the given value of variable "var1". Correlation can be done for single/multiple variables. 

In other word, correlation is a process of finding the instance with similar set of variables. More information on correlation and how the REST API provided by WSO2 Business Server 3.5.1 can be used to correlate among various process instances can be found here.

In this article we are going to provide further description on a newly introduced API which aggregates both instances startup and correlation on a single API call. This API provides following functionality. 

1. If the instance with the given variable state exists, API will return with the existing process instance information.
2. Or if the instance exist with the searched variable state, API will correlate with the process instance and continue the execution.
3. Or if there are no instances exist with defined variable state, new instance will be created and returned back to the client.

This use case can be explained using following BPMN workflow diagram.

This diagram has following properties.

1. A start message :- This message is denoted with "startProcess"
2. Two intermediate message catching events :- Those are "updateRequest" and "recieveResponse"

Requirements

• WSO2 Business Process Server 3.5.1 ( This can be downloaded over here)
• The BPMN workflow can be downloaded over here.

Once the BPMN Archive file is deployed to the server, BPMN instance can be started by hitting the url https://localhost:9443/bpmn/runtime/process-instances with following request.

Prior to sending the request please make sure to set the following header values.
Those are

• Content-Type: application/json or application/xml
• Accept: application/json or application/xml
• Authorization: Basic base64encode(username:password)

Authorization header has to be set with the base64 encoded values of "username:password".

This is a sample request used for creating a process instance

If we want to enable the correlation during process instance creation along with the initial json/xml request message following Boolean flags should be enabled. Those are

• skipInstanceCreationIfExist
• correlate

In addition to this, we did a slight modification to the original request to cater correlation support during process instance creation. That change can be briefed shortly in following way.

• In the previous process instance creation message contains all the variables with in the variables json array.
• but with the introduction of correlation, some times not all the variables mentioned within the variables json array is necessary for correlation task.
• Therefore, we introduced a new json array named "additionalVariables" to include the variables which are not relevant to correlation.
• But eventually once the correlation is completed and if the process instance is found, before prior to continuing with the execution of the workflow, the process instance will be updated with the variables inside the json array  "additionalVariables".

Last but not least we have included the "messageName" variable to be included in the process instance request message.

Now lets go through the requests.

Scenario 1

As per this scenario we are creating the instance for the first time.

You will get the following response.

Scenario 2

In this scenario, we are not going to correlate with the existing instance. We are just going to look whether are there any instance exist with the given variable state. If there is an instance with the given state, it will return with the instance information.

Note the variable "correlate" has been made false. But "skipInstanceCreationIfExist" has been made true.

So there will be neither instance creation nor correlation.

This is the sample request

You will get the following response

Scenario 3

This scenario mainly focuses on correlation. You can notice that we are only interested in correlating with "corrId" variable. The other both variables are being added to the "additionalVariables" field. 

This is the sample request.

And in the successful completion of execution, you will get HTTP Header with 204 (NO-CONTENT) message.

Eventually, you can notice all the variables are being updated in the instance as well.

This method will only work with message based correlation.

How to upgrade the Ubuntu version 13.10 with the updated package repository archives to 14.04

I have been using ubuntu version 13.10 for a while. After some time, ubuntu stops supporting the older version and it keeps throwing error while trying to update the 13.10 packages. 

Therefore in order to fix this issue, you can either update the OS version to the latest one or you can update the package repository archives of archive.ubuntu.com  and  security.ubuntu.compackage repository domain names with  old-releases.ubuntu.com. 

This has been explained in the post to isolate the Ubuntu update error.

But not it's time to update the Ubutnu to 14.04. In order to perform the update you have to follow the following steps.

The semicolon differentiates each individual commands to let us paste together in the terminal.

sudo apt-get clean ;
cd /var/lib/apt ;
sudo mv lists lists.old_`date '+%Y%m%d_%H%M%S'`   ;
sudo mkdir -p lists/partial ;
sudo apt-get clean ;
sudo apt-get update

Sometimes the above commands may fail. In that case you can execute the following set of commands.




sudo sed -i 's/saucy/trusty/g' /etc/apt/sources.list ;
sudo apt-get update ;
sudo apt-get upgrade  ;

How to perform authorizations during BPMN process instance initialization

When designing the BPMN workflow, users can define either the candidate start users or groups.  This permits only the allowed users to start an instance.

Requirements

• WSO2 Business Process Server 3.5.1 ( Beta version can be downloaded from here).
• BPMN Modeling tool. Further information on how to set up this tool can be found at WSO2 Business Process Server Documentation site. 

Candidate start users/groups can be configured like this in Activiti eclipse designer

candidate users/groups can be defined either directly or by defining variables. T

The direct way is to define the user name or group name like admin1, manager etc ...

On the other hand we can use the variables to define the user name or group name as well like ${user1}, ${mgr1}.

The value for these defined variables can be defined in 2 ways. Those are static way and dynamic way.

Static Way

This is similar to variable declarations. This value can be set under the "Data Objects" section of process definition.

Dynamic Way

When invoking the process definition with the REST start call,  you can define the dynamic variable inside "variables" json array.

When starting the process instance following URL should be hit with the json message request
https://localhost:9443/bpmn/runtime/process-instance.

Prior to sending the request please make sure to set the following header values.
Those are

• Content-Type: application/json or application/xml
• Accept: application/json or application/xml
• Authorization: Basic base64encode(username:password)

Authorization header has to be set with the base64 encoded values of "username:password".


In the event of authorization failure REST API will return with 401.

How to Skip the BPMN instances creation with same variable state in WSO2 BPS

This post describes on how to skip the BPMN instance creation with same variable state in
WSO2 Business Process Server 3.5.1 .

Currently in the BPMN Rest API, process instance start operations are not conditional. But there are occasions, process instances  should not be initialized when ever there is a already created instance with same variables state (variable values).

This is the sample request that we use to start a process instance.

In order to make sure that only single instance is being created for an unique value, we can use the "businessKey" attribute. Although this is the most preferred way this won't work every time.

This may fails on following occasions.

• Business key attribute value can not be updated during the run time. Therefore, If the business key is not known before the instance creation, we shall not be able to update it.
• In the event of considering more than one variables to determine the instance state, we can't use the business key attribute.

Therefore as a solution to those issues, WSO2 Business Process Server 3.5.1 introduces a new Boolean flag "skipInstanceCreationIfExist" in the request.  By default the value of the flag is false.

This sample request can be used to start the process instance

This flags looks for the process instances with variables which have the values  defined in the process instance request. In the event of existence of any process instances with the same variables state, instance creation will be skipped. 

How To Implement Correlation support for BPMN workflow

Abstract

WSO2 Business Process Server 3.5.1 will be introducing new BPMN Rest API to support correlating among the client and BPMN workflow instances.

Typically in a BPMN workflow scenario to correlate instances, we use either intermediate message catch event or signal catch event. Since intermediate catch events are used for correlating with single message instance, this blog post will consider one such scenario.

In order to explain this use case we have implemented following workflow diagram.

Requirements

• WSO2 Business Process Server 3.5.1 ( Beta version can be downloaded from here ).
• The BPMN workflow can be downloaded from here.

Once the BPMN Archive file is deployed to the server, BPMN instance can be started by hitting the url https://localhost:9443/bpmn/runtime/process-instances with following request.

Prior to sending the request please make sure to set the following header values.
Those are

• Content-Type: application/json or application/xml
• Accept: application/json or application/xml
• Authorization: Basic base64encode(username:password)

Authorization header has to be set with the base64 encoded values of "username:password".

In the event of successful initialization of the instance, it will return with following response.

Next we can send the following message to execute the correlated instance among already existing instances by hitting the url https://localhost:9443/bpmn/runtime/receive. Make sure to set the header values as well. Currently BPS 3.5.1 supports both json and xml as well.

Instances to be correlated can be identified the field "correlationVariables". This variable can be used to detect the instance with the same variables state.

In addition "variables" can be used to define the variables, that should be updated prior to the resumption of execution of the correlated instance.

Following are the fields that can be used in the correlation request.

processDefinitionKey/processDefinitionId/messageName/signalName (compulsory)

Either one relevant property out of four should be specified in the request.

action (compulsory)

actions can be either messageEventRecieved/signalEventRecieved/signal.

signalName (optional)

If we have any signal related actions, then signalName has to be specified.

variables (optional)

All the variables that should be updated prior to the resumption of execution of the correlated instance can be defined inside the variable.

correlationVariables (compulsory)

All the correlation variables should be mentioned here. By default it performs the equal operation of that variables.

 tenantId (optional)

How to set-up DB2 with WSO2 BPS

System Requirements

• DB2 Express-C 10.5. This can be downloaded over here.
• Ubuntu 13.10
• WSO2 BPS 3.5. This can be downloaded over here .

DB2 database can be installed by following the instructions given from this post. But unfortunately since we are installing a non licensed version of DB2, we won't be able to create the sample database mentioned in the blog post using the db2fs command. 

You can access the database by accessing as the db2 instance user. 

                        su - db2inst1

Step 1 - Create the databases

In order to view the available db2 database directories, you can use the following command 

                      db2 list database directory

Now we can create the necessary databases and assign necessary privileges for them to connect BPS with DB2 server. You have to create 4 such databases like bps_db, bpmn_db, reg_db and user_db.

We are going to create non restricted databases. Thus won't be having any permission issues.

                     db2 create database bps_db

                     db2 activate db bps_db 

Once the database get activated, we need to get connected with the database to perform operations on it.

                     db2 connect to bps_db

Step 2 - Creating the temporary system table spaces

You have to create temporary system table spaces for each database. This system table space stores internal temporary data required during SQL operations such as sorting, reorganizing tables, creating indexes, and joining tables. 

You have to create system tables paces with page size 4K, 8K, 16K and 32K. In addition buffer pool has to be created with the same size for each table space. Therefore in abstract, you have to create 4 buffer pools and 4 table spaces.

Creating a buffer pool with the size 4k

db2 "CREATE BUFFERPOOL STB_4_POOL PAGESIZE 4K"

Creating a system table space with the size 4k

db2 "CREATE SYSTEM TEMPORARY TABLESPACE STB_4 PAGESIZE 4K BUFFERPOOL STB_4_POOL"

More information regarding system table space and buffer pool can be found here

Step 3 - Obtaining the port number used in DB2

By default DB2 operates on port number 50000. In order to ensure the working port number of the DB2, we can execute following commands.

         db2 "get dbm cfg"|grep -i svce

This command will produce following output. 

         TCP/IP Service name                          (SVCENAME) = db2c_db2inst1

now you have to look for the port number in /etc/services. You can find a record like this

         db2c_db2inst1   50000/tcp

The above record defines the tcp port for the DB2 service which is 50000 in this case. 

Step 4 - Configuring the datasources in wso2 bps

Business Process Server 3.5.0 has to be configured with data-source properties files. These files can be found inside /repository/conf/datasources folder. Further configuration can be found here. 

I have copied the sample data-source configuration over here. 

       

Next we have to start the BPS server with -Dsetup option. This will create the tables. If not tables can be created by executing the db2 which can be found in dbscripts

Step 5 - Make sure the tables have necessary privileges

The tables should have the necessary privileges to "insert, update, delete and select". If we have created the database in restricted mode, we have to run the following commands to grant permission to the  tables.

First we have to dynamically generate command to grant privileges. Following script will dynamically generate the SQL and will write it in to the bps.sql file.

db2 "select 'grant insert, update, delete on table ' || trim(tabschema) || '.' || trim(tabname) || ' to user db2inst1;' from syscat.tables where type = 'T'" > bps.sql

Now open the bps.sql and remove the unwanted terms in the file ( in the top and bottom ).

This file will be heaving sql scripts like this 

               grant insert, update, delete on table SYSIBM.SYSDBAUTH to user db2inst1;

Next execute the file 

              db2 -tvsf bps.sql

Dropping the database in DB2

Following commands should be executed prior to dropping a database in DB2.

                      db2 disconnect all

                      db2 force applications all

                      db2 deactivate db  bps_db

                      db2 drop database BPS_DB

Note 

• WSO2 BPS 3.5 db2 scripts can be found inside the pack. ( BPS_HOME/dbscripts/bps/)

How to Fix the linking errors during installation of Oracle 11g in Ubuntu 13.10

I followed the following blog post to install the oracle. But this blog post explains only about installing oracle in Ubuntu 12.04.

When I try to do it in Ubuntu 13.10, I faced some linking errors. Most of the linking errors are like  "Failed to link liborasdk.so.11.1" or some other library names. Therefore in order to over come those errors, after completing the installation of additional packages, some of the installation files to be modified.

">