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)