Customizing and Extending Camunda Tasklist (Communication with External Sources)

This is the 1'st topic in our series of “Customizing and Extending Camunda Tasklist”.

A brief introduction of this series can be found here.

In almost every user task, there is a need to populate/save some data from/to external sources. for example: populating details of current logged-in user (full name, job title, department.. etc.), populating look-ups (countries, regions, cities.. etc.) or saving online order details.

During process execution, there are two major types of data to interact with:

• Application/domain data: application data are maintained in external sources and could be either supporting data (for example: list of store locations to pick up your order from, product details.. etc.) or business objects associated with running process/task instances (for example: order details associated with an order process instance)
• Process data: process data drive the process flow so for example an insurance claim of 5000 USD requires “high-value investigation” activity whereas a claim of 100 USD doesn’t have such requirement. Process data can be a partial replication of domain object so for example: claim value as a process variable is a single attribute replication of claim domain object, it can be a manual input maintained separately from domain data as in process variable used to hold the action taken by a participant or it can be output data of an external service call so “customer membership type” can be an example of a process variable returned from an external service call which expects customer identifier as input and returns membership type as output.

In this story, we are going to create a simple leave request process.

This process to be extended as we advance in this series.

In the start form of this process, the details of request initiator to be populated automatically from employee database table “external source”.

Let’s start with the prerequisites

• Java Runtime Environment 1.8+.
• Camunda BPM Platform version 7.13 (Full Distribution for Tomcat).
• Camunda Modeler.
• Java EE IDE (Eclipse IDE for Java EE Developers).
• Text Editor (Notepad++).

First step is creating a simple database table called “Employee”. (for the sake of simplicity, this table to be created in the process-engine database)

CREATE TABLE employee (
 employee_number varchar(150) NOT NULL,
 employee_name varchar(255) NOT NULL,
 user_id varchar(150) NOT NULL,
 PRIMARY KEY (employee_number)
);

Then we can insert some records into it.

INSERT INTO employee
(employee_number,
employee_name,
user_id)
VALUES
('1111',
'Demo Demo',
'demo');

Now our database table is ready to query so let’s move to the next step which is creating our JAX-RS application.

• Resteasy shipped with camunda platform to be used as the JAX-RS implementation.
• MyBatis shipped with camunda platform to be used as the persistent framework.

The application class

The service implementation class

The complete JAX-RS application can be found here.

Import the project then run as maven install.

The generated jar

Next, we need to declare Resteasy servlet in camunda/WEB-INF/web.xml so below snippet to be added in camunda/WEB-INF/web.xml.

<!-- hr rest api -->
<servlet>
    <servlet-name>HR Api</servlet-name>
    <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
    <init-param>
        <param-name>javax.ws.rs.Application</param-name>
        <param-value>org.camunda.hr.impl.web.HRRestApplication</param-value>
    </init-param>
    <init-param>
        <param-name>resteasy.servlet.mapping.prefix</param-name>
        <param-value>/hr-rest</param-value>
    </init-param>
</servlet>
<servlet-mapping>
    <servlet-name>HR Api</servlet-name>
    <url-pattern>/hr-rest/*</url-pattern>
</servlet-mapping>

Our RESTful employee service is an example of a common service which is usually consumed from within multiple process applications, webapps plugins or from within process engine plugins so we are going to configure it as a common library. (https://tomcat.apache.org/tomcat-9.0-doc/class-loader-howto.html)

• Shutdown camunda.
• Create a new folder labeled “applib” in server/apache-tomcat-9.0.33.
• Put our generated jar “hr-lib-0.0.1-SNAPSHOT.jar” in the new created folder server/apache-tomcat-9.0.33/applib.
• Move all jars of camunda/WEB-INF/lib to server/apache-tomcat-9.0.33/applib (as they are dependent jars).
• Define below values for common.loader property of conf/catalina.properties file.

common.loader=”${catalina.base}/lib”,”${catalina.base}/lib/*.jar”,”${catalina.home}/lib”,”${catalina.home}/lib/*.jar”,”${catalina.base}/applib”,”${catalina.base}/applib/*.jar”,”${catalina.home}/applib”,”${catalina.home}/applib/*.jar”

Start camunda then you can test our unsecured RESTful service (later we are going to show how easily you can make it a secured service).

Now it is time to create an angularjs service to consume our RESTful service. Click here to download the complete JS file.

Put our hr-custom-ng-module.js file in camunda/app/tasklist/scripts.

Replace camunda/app/tasklist/scripts/config.js file with this file to include our custom angularjs service.

Next, we are going to inject and use our angularjs service from within the start form of our leave request process so let’s create our process application.

The complete process application can be found here.

Import the project then run as maven install.

The generated war

Now deploy the generated war to tomcat server (simply drop it into apache-tomcat-9.0.33/webapps folder).

Finally, we are ready to test our process.

Start the process using credentials for a user who has a record in the employee table (demo user in our case)

Great! we have successfully managed to communicate with the external source “employee database table” (data of request initiator have been populated automatically).