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.

WSO2 DSS for absolute beginners

WSO2 Data Services Server is 100% open source product that can be used to create and deploy data services.

What is a Dataservice?

Most businesses require secure and managed data access across these federated data stores, data service transactions, data transformation and validation.

An organization's data exposed as a service, decoupled from the infrastructure where it is stored, is called data services in service oriented architecture (SOA).

If I explain in most simple way: Data service exposes database or database content or any other data source as a web service. In most simplest explanation is it just wraps database (or table, multiple tables) or any other data source and expose the data as web service in more controlled, meaningful manner. 

Data Services provide a convenient mechanism to configure a Web service interface for data in various data sources such as relational databases, CSV files, Microsoft Excel sheets, Google spreadsheets etc

As an example, let’s say you want expose employee information in the database which employee personal information are in emplyeeInfo table and work related information is in another table called employeeWork table. And think you want to expose those information as a web service when requester sends the employee id and the service returns employee personal information with his work performance information. Simply you can create web service using WSO2 DSS by wrapping the SQL query to retrieve that information and present in the response. 

The beauty with DSS is, it handle all dirty work such as creating database connection, database connection pool handling, executing SQL queries, mapping resultant data to the response, etc. which is an unusual overhead to for development. With WSO2 DSS it just simply a web service call, so developers can more concentrate on the business logic / use case.

You can get more feeling about DSS by following  

Generating simple data service using WSO2 DSS Generate wizard

Now we will try out generate data service for given database table. In generate it will create data service with CRUD operations for the table.

Refer https://docs.wso2.com/display/DSS322/Installing+the+Product for installation instructions and refer https://docs.wso2.com/display/DSS322/Running+the+Product for running product instructions.

1. After starting the product and then login to the management console (default username: admin password: admin)
2. First we have to first define data source

NOTE : before creating datasource you have to copy database jdbc driver relevant to your database to <PRODUCT_HOME>/repository/components/lib.

1. Go to Configure tab → Data Sources
2. Will get list of data sources currently configured as follows

3. Click “Add Data Source” and provide information related to the database as follows:

Click Test Connection to verify provided information

Can provide data source connection pool parameters by expanding “Data Source Configuration Parameters” (refer: https://docs.wso2.com/display/DSS322/Configuring+the+Datasource+Connection+Pool+Parameters )

Click save when finished.

3. Now we can generate dataservice
1. Go to Main → Click “Generate” under Data Service
2. Select previously created Data Source from the drop down and give the database name

NOTE : For the “Database name”, you have to give the actual database (schema) name. Most of the time people get confused with this. In this case “DSS_DB” which created with the command “create database DSS_DB;”

Then click “Next”

3. You will get list of all available tables in the database as shown below. You can to select tables which need to expose as data service and click “Next”

4. In “Service Generation” section you have to provide Data Service Namespace and the Data Service Name. And select whether you need single service with CRUD operation for all the tables or multiple services per table (service per table)

4. After click Next you will get notice that service deployed successfully.

4. Now you have finished creating data service. If you navigate to “List” under Services in Main tab you will find created data service. You can tryout it by clicking Try this service.

Solving Code Formatting / Indentation Problem in IntelliJ Idea

When working software engineering tools to make you life easy, especially IDE's you have to be more careful. When using IDE some times code you see through it is not the actual raw data representation of your code. Therefore you need to know how to configure those IDE's prior using them.

In engineering it is a good practice to go through documentation, available features and make proper configurations before using tools.

When using exactly IntelliJ Idea 13.1.5 some times you may face problem with code formatting, which is when looking at the code from the IDE, formatting looks fine, but if you open raw file in another editor like vim, the entire code format is deformed as shown below.

As you can see in IDE formatting looks fine but in vim it's deformed. This situation may occur sometimes due to copying and pasting repeating code from different indentation levels or if you try to make formatting forcefully with a mixture of tabs and spaces in the IDE.

The core reason is the final raw file contains mixture of TAB characters and space characters to create code formatting.

You can see two if blocks are indented differently in tabs (marked in 1) and spaces (marked in 2). In this situation in IDE the formatting looks fine but in raw editor, things get worse.

You can see above view in vim by setting list option [1]

:set list

        Show tabs as CTRL-I is displayed, display $ after end of line. Useful to see 

        the difference between tabs and spaces and for trailing blanks 

This problem occurs if you not properly configure IDE before use.

You can fix this problem in IntelliJ by following below steps:

Go to File → Settings → Code Style → General
Check "Use tab character" option under "Default Indent Options"

This will fix this indentation problem.

[1] http://vimdoc.sourceforge.net/htmldoc/options.html

Cheers ... !

Synchronize forked repository with new commits to original repository

To synchronize with your forked repository with the new updated content of the original repository follow these 5 steps:

Step 1
Check whether that you have configured a remote to original repository
git remote -v  command will list remote URLs as follows

If you haven't configured remote to original repository, you will see only origin (which is forked your repository) in the list. 

Step 2
configure a remote pointing original repository with following command

git remote add <remote_name> <url>

Generally we use name "upstream"

then list down remotes and check whether upstream is in the list

Step 3

Now download content from the original repository using fetch command

git fetch <remote>

This will fetch all the branches and commits from the original repository (if <remote> is pointing to it), in this case upstream

Step 4

Check out your local master branch by git checkout master command. 

At this point you have to commit if you have done any changes to local repository.

Step 5

Now merge changes from upstream master to local master by following command

git merge upstream/master

you will see similar to following

Now you local repository is updated with original repository's new content.

Then you can push new updates to your remote repository

Cheers ....

Create WSO2 ESB Connector for Absolute beginners

In this blog post I’m presenting proper, easiest and standard approach to create esb connector for The WSO2 ESB.

If you follow these steps you can avoid errors or problems at the end of the project, specially when writing integration test.

If you are not familiar with WSO2 ESB read the article “Enterprise Service Integration with WSO2 ESB” [1], and it presents most of information about enterprise integration, wso2 ESB and how we can use it in real world application with an example (Better read you are new to wso2 products).

Fork and clone or just clone wso2 esb-connectors repository following the link https://github.com/wso2-dev/esb-connectors. this repository consists of source codes of all the wso2 esb connectors.

Now find the template directory in your local copy, {LOCAL_CLONE_DIR}/esb-connectors/template ({LOCAL_CLONE_DIR} is the directory that you cloned the repository). It’s a template of directory structure which you need to create for your connector. The most basic file structure is shown below.

If you follow this link to article “How to write WSO2 ESB connectors”[2] you could find summary of purpose of each file in this structure. assemble-connector.xml and filter.properties files does not need to modify for now. Just let it untouched :D …

If you like to contribute for wso2 esb connectors make your file structure to new standardized file structure, we’ll need to modify the above shown file structure to following structure.

Here we’ll consider the connector name as "demo".

First modify {LOCAL_CLONE_DIR}/esb-connectors/demo/demo-connector/pom.xml (which is parent pom file of the connector project) to add module.

add module demo-connector-1.0.0

<modules>

           <module>demo-connector-1.0.0</module>

    </modules>

Note: if you like to contribute project, follow the naming convention for the module name

<name_of_connector>-connector-<verion>

Use {LOCAL_CLONE_DIR}/esb-connectors/demo/demo-connector/demo-connector-1.0.0/pom.xml pom file to add repositories, 3rd party libraries (as dependencies) used in the project if available. Update the maven-assembly-plugin as follows:

<plugin>

   <groupId>org.apache.maven.plugins</groupId>

   <artifactId>maven-assembly-plugin</artifactId>

   <executions>

      <execution>

        <id>demo-library</id>

        <phase>compile</phase>

        <goals>

          <goal>attached</goal>

        </goals>

        <configuration>

          <finalName>demo-connector-1.0.0</finalName>

              <appendAssemblyId>true</appendAssemblyId>

              <filters>

            <filter>${basedir}/src/main/assembly/filter.properties</filter>

              </filters>

              <descriptors>

                  <descriptor>src/main/assembly/assemble-connector.xml</descriptor>

              </descriptors>

          </configuration>

      </execution>

   </executions>

</plugin>

Now we’ll focus on where to put our source {LOCAL_CLONE_DIR}/esb-connectors/demo/demo-connector/demo-connector-1.0.0/src/main folder. This folder contains three folders, assembly, resources, java.

‘resources’ folder contains all the synapse configurations.

‘java’ folder contains java source codes that consumed by the connector.

‘assembly’ contains configuration files required for maven-assembly-plugin

Now, you can follow “Creating a Connector”[3] in documentation and “How to write WSO2 ESB connectors”[2] article and create your own connector.

[1] http://wso2.com/library/articles/2012/11/enterprise-service-integration-wso2-esb/     

[2] http://wso2.com/library/articles/2014/02/how-to-write-a-esb-connector/     

[3] https://docs.wso2.com/display/ESB480/Creating+a+Connector