Start BPMN Process by Listening to a Message Queue

There are several types of start events available in BPMN. First of all if you are not much familiar with BPMN processes here is some summary information about Start events, summarized from BPMN specification

Start Enevts

• The Start Event simply indicates where the process start (entry points to process)
• When trigger for start event occurs, a new process instance get created
• There are 7 types of start events for top-level BPMN processes: None, Message, Timer, Conditional, Signal, Multiple, and Parallel

• All the start events, except None Start Event, only applicable to processes used as top level process. None Start Event may used to invoke process from Call Activity

Now we will concentrate main topic of this post

Start BPMN Process by Listening to a Message Queue/Topic

WSO2 BPS 3.5.0/3.5.1 do not support starting bpmn process by listening to a message queue. But that feature will be available OOTB in a future release. At the moment we have to achieve that with the help of WSO2 ESB.

Things you need:

1. WSO2 Enterprise Service Bus (WSO2 ESB 4.9.0 used for this post)
2. WSO2 Business Process Server (WSO2 BPS 3.5.1 used for this post. You must have BPS 3.5.0 or higher version for BPMN support)
3. ActiveMQ (5.12.0 used for this post or you can use WSO2 Message Broker too)

Architecture diagram

BPMNProcess_start_proxy is ESB proxy that consumes messages from the queue, create relevant message to start the bpmn process and make REST call to start the bpmn process. In this case ESB acts as message consumer of the queue.

Step 01 : Create BPMN process 

Follow [1] for basic guide to create BPMN process

Here is the BPMN process that I'm going to use

You can download it from [2]

This sample process shows approval process for placing a stock order. If the entire investment is greater that $100,000 and administrator should approve it.

Stem 02 : Configure WSO2 ESB

• First you have to enable JMS transport of WSO2 ESB. You can find instruction in [3] to configure WSO2 ESB for ActiveMQ and [4] for WSO2 Message Broker. Refer [5] for other popular massage brokers.

• Create BPMNProcess_start_proxy proxy service
• This proxy service receive stock order message and start order approval BPMN process deployed in WSO2 BPS. The proxy extract relevent information and create JSON request including those data as variables and invoke BPMN REST API available in WSO2 BPS.

Step 03 : Start Servers

Start ActiveMQ
Start WSO2 ESB (default port, portOffset=0, 9443)
Start WSO2 BPS (portOffset=1, 9444): start $ sh bin/wso2server.sh -DportOffset=1

Step 04 : Make Stock order 

Make Stock order request to "StockOrderInQueue" message queue
Execute StockQuote Client : navigate to /samples/axis2Client and execute following command

ant stockquote -Dmode=placeorder -Dtrpurl="jms:/StockOrderInQueue?transport.jms.ConnectionFactoryJNDIName=QueueConnectionFactory&java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&java.naming.provider.url=tcp://localhost:61616&transport.jms.ContentTypeProperty=Content-Type&transport.jms.DestinationType=queue"

User tasks can be completed using bpmn-explorer webapp (https://localhost:9444/bpmn-explorer) and login as ‘admin’

As shown above you can start BPMN process by listening to message queue. By integration with WSO2 ESB you can start BPMN process, using any type of transport that WSO2 ESB support for example: JMS, Kafka[6].

References:
[1] https://docs.wso2.com/display/BPS350/BPMN+Guide
[2] https://github.com/milindaperera/MilisLogBlog/tree/master/WSO2BPS/BPMN/BPMN_ESB_MQ_Integration
[3] https://docs.wso2.com/display/ESB490/Configure+with+ActiveMQ
[4] https://docs.wso2.com/display/ESB490/Configure+with+WSO2+Message+Broker
[5] https://docs.wso2.com/display/ESB490/Configuring+JMS+Transport
[6] https://docs.wso2.com/display/ESB490/Kafka+Inbound+Protocol

If this post is useful to you, any questions, corrections or for any suggestion, please leave a comment below :)

Reset default superuser password of PostgreSQL database

If you forgot the password of the PostgreSQL database, you can reset it by following below steps:

Start PSQL terminal with following command
$sudo -u postgres psql postgres

Then run following command and will ask to enter new password:
# \password postgres

Enter new password:

This method is tested with PostgreSQL 9.1.12

Mount Windows shared file in Linux

This post mainly focus on how to mount windows shared file in Linux.

"mount" command [1] is used to attach file systems  (located on an attached device or in network) to the file system tree at specified node.

To mount network shared file, the format of the command with most basic options as follows:

mount -t <type> //<hostname>/<shared_name> <path_to_mount_point>

type: File-system type. In this case cifs (Common Internet File System is variation of SMB protocol developed by Microsoft and native file sharing protocol used in Windows for more information refer [2])
hostname: Host name of the server (or ip address)
shared_name : Name of the shared directory/file
path_to_mount_point : path to the directory that shared file system should be mounted to file system tree

eg:
sudo mount -t cifs //10.100.5.92/TempShareDoc ~/Documents/share/ -v

If you need to mount password protected shared file, you can add those information as options username and password as follows
mount -t <type> -o username=<user_name>,password=<password> //<hostname>/<shared_name> <path_to_mount_point>

Also we can set the permissions of the mounted file system using dir_mode (directory permissions) and file_mode (directory permissions) options, as follows
mount -t <type> -o dir_mode=<permissions>,file_mode=<permissions> //<hostname>/<shared_name> <path_to_mount_point>

eg: 
sudo mount -t cifs -o dir_mode=0755,file_mode=0755  //10.100.5.92/TempShareDoc ~/Documents/share/ -v


[1] http://linux.die.net/man/8/mount
[2] https://technet.microsoft.com/en-us/library/cc939973.aspx

Creating self-signed SSL certificate

• Generate a private key

$ openssl genrsa -des3 -out server.key 1024

You have to provide pass phrase which incorporated the private key

• Generate Certificate Signing Request (CSR)

$ openssl req -new -key server.key -out server.csr

Enter pass phrase for server.key:

You are about to be asked to enter information that will be incorporated

into your certificate request.

What you are about to enter is what is called a Distinguished Name or a DN.

There are quite a few fields but you can leave some blank

For some fields there will be a default value,

If you enter '.', the field will be left blank.

-----

Country Name (2 letter code) [AU]:SL

State or Province Name (full name) [Some-State]:Western

Locality Name (eg, city) []:CMB

Organization Name (eg, company) [Internet Widgits Pty Ltd]:WSO2

Organizational Unit Name (eg, section) []:BRS

Common Name (e.g. server FQDN or YOUR name) []:wso2.brs.com

Email Address []:milindap@wso2.com

Please enter the following 'extra' attributes

to be sent with your certificate request

A challenge password []:

An optional company name []:

For the Common Name (CN), you have to provide fully qualified domain name of the server. In above example the expected server url in https://wso2.brs.com/, hence proved the wso2.brs.com as the CN.

• Create self-signed certificate

$ openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

Signature ok

subject=/C=SL/ST=Western/L=CMB/O=WSO2/OU=BRS/CN=wso2.brs.com/emailAddress=milindap@wso2.com

Getting Private key

Enter pass phrase for server.key:

This will create server.crt certificate. 

Humantask Rendering in WSO2 Business Process Server [WSO2 BPS]

Little introduction about WS-Humantask

WS-Humantask is defined to integrate humans into enterprise integration. When task request received by humantask engine, it create instance of the task with received request information. Then assignee or potential owner can claim the task and work on it and complete it. On completion response message is sent to the callback service. That's the most basic usage of WS-Humantask.  

WSO2 Business Process Server (WSO2 BPS) includes humantask engine which compliance with WS-HumanTask Specification Version 1.1 [1].

Humantask Rendering

When humantask instance created it can be presented to its (potential) owners to claim task and perform work using Task Client application. An easily customizable client application (humantask-explorer) with main basic functionalities is packed with WSO2 Business Process Server.  

When user selects interested task, client application should render task allowing user to view information related to task instance. 

WS-Humantask provide container to provide rendering information to Task Client application. And task clients (eg: humantask-explorer) use these information and construct the user interface. The container mentioned above for rendering a task’s information is tasks rendering element.

 

Task rendering details are out of the scope of WS-Humantask. So WSO2 input and output renderings have introduced WSO2 Business Process Server 3.5.0 onwards.

Why we introduced humantask rendering support:

In previous versions of WSO2 BPS did not support task rendering, instead you had two options with the help of HumanTaskClientAPIAdmin adminservice:

1. Build your own client application including task information rendering for each task definition
2. Using humantask client built into management console. In this case you have to package separate .jsp pages to display input, output and response  which display input data, user workspace and create response message.

Above both methods introduce high workload per task definition (in method 2) and unable to implement client applications which support almost any humantasks (client applications are tightly coupled with each humantask definition), which makes adding new task much complicated work. That's why, with new release WSO2 BPS 3.5.0 onwards we introduce task rendering support. 

Syntax:

Description

<renderings>		Within “renderings” element rendering types are listed.
<rendering>	xmlns, type	WSO2 Business Process Server supports two main rendering types: wso2:input and wso2:output The namespace is specified as: xmlns:wso2=”http://wso2.org/ht/schema/renderings/” The type of the rendering is specified by the “type” attribute as follows: If the rendering elements listed under <rendering> are input renderings : type="wso2:input" If the rendering elements listed under <rendering> are output renderings : type="wso2:output"
<wso2:input>		wso2:input rendering type is used to render input information to the task instance in the user interface. Each information is represented by <wso2:element> which list input information that need to display as label / value pairs. Format of rendering input element (<wso2:element>) as follows: <wso2:element id=”[Unique id for the display element]”>    <wso2:label>[Label to display for the input element]</wso2:label>    <wso2:value>[xpath to get the value from the input message / presentationParameter]</wso2:value> </wso2:element> Attributes id - Unique ID for each element Child elements <wso2:label> - Label (or text) to display with the value <wso2:value> - The value to display with the label. This value can be extracted from the input message (by providing xpath) or by presentation parameters. Example 01 : retrieving value by xpath <wso2:element id="custId">   <wso2:label>Customer Identifier</wso2:label>   <wso2:value>/test10:ClaimApprovalData/test10:cust/test10:id</wso2:value> </wso2:element> Example 02 : Set value by presentation parameter defined in the presentationParameters in humantask definition <wso2:element id="fname">   <wso2:label>First Name</wso2:label>   <wso2:value>$firstname$</wso2:value> </wso2:element>
<wso2:output>		wso2:output rendering is used to render user workspace (to generate html form that need to filled by the task assignee) and to populate response message to the callback service when task instance get completed. Each form element is represented by <wso2:element>. Format of the output rendering element () as follows: <wso2:element id="[unique id for each element]">    <wso2:label>[Label to display for the form field]</wso2:label>    <wso2:xpath>[xpath of the element in the output message to be filled with this form field]</wso2:xpath>   <wso2:value type="[string | boolean | Int | double | list]">[comma separated values for list type and boolean type]</wso2:value>   <wso2:default>[default value for above mentioned value element]</wso2:default>* </wso2:element> Attributes id - Unique ID for each form element Child elements <wso2:label> - Label to display for the form field <wso2:xpath> - Xpath of the element in the output response message to be filled with this form field input content <wso2:value type=””> - The “type” attribute is used to define the type of the form field. string : provide textarea int / double : provide number input boolean : provide radio buttons. Texts to display with two radio buttons should provide as comma separated values within value element, with respective to “true” and “false”. list : provide dropdown selection. Texts to display in the dropdown list should provide as comma separated values. <wso2:default> - Can provide default value to display in the form Example 01: <htd:rendering type="wso2:output">   <wso2:outputs>       <wso2:element id="approve">          <wso2:label>Loan Status</wso2:label>              <wso2:xpath>/test10:ClaimApprovalResponse/test10:approved</wso2:xpath>           <wso2:value type="boolean">Approved, Not approved</wso2:value>           <wso2:default>Disapproved</wso2:default>      </wso2:element>      <wso2:element id="loanTypeSelectList">           <wso2:label>Loan Type</wso2:label>           <wso2:xpath>/test10:ClaimApprovalResponse/test10:loanType</wso2:xpath>           <wso2:value type="list">car loan, house loan, development loan, education loan</wso2:value>           <wso2:default>house loan</wso2:default>      </wso2:element>      <wso2:element id="loadDescription">           <wso2:label>Loan Description</wso2:label>           <wso2:xpath>/test10:ClaimApprovalResponse/test10:description</wso2:xpath>           <wso2:value type="string"></wso2:value>           <wso2:default>car loan</wso2:default>      </wso2:element>      <wso2:element id="loanInterestAlteration">           <wso2:label>Loan Interest Alteration</wso2:label>           <wso2:xpath>/test10:ClaimApprovalResponse/test10:interest</wso2:xpath>           <wso2:value type="int"></wso2:value>           <wso2:default>1000</wso2:default>      </wso2:element>   </wso2:outputs> </htd:rendering> Generated form in humantask-explorer will be shown as follows

[1] http://docs.oasis-open.org/bpel4people/ws-humantask-1.1-spec-cs-01.html 

Changing port in Tomcat Server

Sometimes we need to run several servers (or several tomcat servers) in same machine specially when developing and testing. In such situations we have to change the default port 8080 of the server. For that follow below simple steps.

1. Open server.xml located in the <TOMCAT_HOME>/conf/ directory using your favorite text editor.

2. Then find Connector element similar to the snipt shown below:

3. The attribute "port" is the port number which server get binded. So you have to change that desired port number.

4. Then save the file and restart the server.

That's all :)

Invoking Fault Sequence for SOAPFaults in WSO2 ESB

In WSO2 Enterprise Service Bus Synapse configuration provides ability to execute set of instruction when some fault occurred within mediation flow by with the help of faultSequence. It's similar catch block to try-catch in JAVA. We can bind faultSequence with ESB proxies, API's etc.

Generally faultSequence get executed for errors, exception in mediation flow, such as trying to process malformed xml, endpoint timeout, any mediation errors, etc. It is not designed to execute  when error response get received. But you can set property to execute faultSequence when a standards soap fault (SOAPFault) response received from an endpoint. It becomes handy in service chaining because we do not need to check and verify for fault response before calling the next endpoint.

You can force to execute faultSequence by setting "FORCE_ERROR_ON_SOAP_FAULT" property to "true"

<property name="FORCE_ERROR_ON_SOAP_FAULT" value="true" scope="default" type="STRING"/>

Sample synapse configuration to depict usage of  FORCE_ERROR_ON_SOAP_FAULT



In above sample simply front echo service which comes by default with WSO2 ESB. If you call "echoProxy" which echo service returns SOAPFault such as sending alphabetical character for echoInt operation, you can see the fault sequence "echoFaultSeq" get executed.