ToDo List Evaluation Process

RedHat Process Automation Manager (RHPAM) provides the ability to integrate/utilize different technologies with built-in service tasks. It is also possible to implement custom service tasks where out-of-box capabilities do not fulfill the needs. To implement a custom service task one needs to implement org.kie.api.runtime.process.WorkItemHandler interface of KIE API.

For details, please check official documentation.

This project implements a sample BPM project on RHPAM that uses 3 service tasks:

• REST Service Task: Built-in service task that is used to call a test API of JSONPlaceholder
• Logger Service Task: Custom service task implementation that logs input data as JSON using SLF4J and Jackson ObjectMapper.
• MySQL Service Task: Custom service task that persists/inserts task data based on JSONPlaceholder's ToDo API response schema using MySQL JDBC driver.

Service Task Implementations

The two custom service task types were implemented using KIE Java API which are essentially WorkItemHandlers. Due to their nature they are customizable and re-usable throughout processes and projects in Business Central. In order to use them you need to import packaged versions (JAR files) and enable them in Business Central (http(s)://HOST:PORT/business-central). The official documentation contains relevant details throughout implementation and deployment journeys.

The handler implementations in this project can be build and deployed to an artifact server (here docker hosted Artifactory) using following maven goals:

mvn clean package deploy

The resultant JAR file in target folder of project is the packaged version that can be imported to Business Central.

Importing Custom Service Tasks

In order to activate custom service tasks (CustomLogTask, MySQLTask) in Business Central you should follow the procedure set (Chapter 1 - Procedures 1->4) in official documentation:

Then you need to activate them via ON/OFF switch right hand side of imported ones:

Importing Sample Business Process Project

There also exists a business project which uses custom service tasks mentioned here. For a quick start you can directly import the project into Business Central just using Import Project button with setting the repository URL (https://github.com/selcuksert/process-automation-servicetask-repo) in your designated space:

Activating Service Tasks for Project

The procedure set (Chapter 1 - Procedures 6->10) in official documentation need to be applied to activate service tasks for any business process project. For the sample project we need Rest, CustomLogTask, MySQLTask to be installed:

It is also important to note that in deployment settings (MVEL) we need to pass classLoader parameter to constructor of WorkItemHandler classes of Rest, MySQLTask tasks as KIE classloader needs to be in action to avoid ClassNotFound exceptions during process execution:

Service Task Parameters

Based on their implementations service tasks need input and output parameters for their own processing.

Process Variables

The sample project needs some process level variables (.bpmn file view -> Properties -> Process Data):

Name	Data Type	Description
taskId	java.lang.Long	Process variable to store task ID input of JSONPlaceholder's ToDo API
response	com.corp.todo.Task	Custom model that aligns with ToDo API task data schema
insertResult	String	SQL statement execution result

The custom model that aligns with the API data schema can easily be added using visual class editor of Business Central (Project Page -> Add Asset -> Data Object):

REST Service Task

The official documentation (a bit out-dated) contains details on REST Service Task. It is also possible to derive information on input/output parameters and processing logic from WIH implementation class RESTWorkItemHandler.java.

The sample project set following parameters (Click on service task -> Properties (Pen icon right hand side) -> Data Assignments):

Name	Data Type	Source
AcceptCharset	String	UTF-8
AcceptHeader	String	application/json
ContentType	String	application/json
ContentTypeCharset	String	UTF-8
HandleResponseErrors	String	true
Method	String	GET
ResultClass	String	com.corp.todo.Task
Url	String	https://jsonplaceholder.typicode.com/todos/#{taskId}

Name	Data Type	Target
Result	com.corp.todo.Task	response

One can directly access to any process data variable using #{paramName.fieldName}

Log Service Task

The sample project set following parameters (Click on service task -> Properties (Pen icon right hand side) -> Data Assignments):

Task	Name	Data Type	Source
Completed	dataToLog	Object	#{response.completed}
Completed	prettyPrint	String	true
Not Completed	dataToLog	Object	#{response.completed}
Not Completed	prettyPrint	String	true
REST	dataToLog	Object	response
REST	prettyPrint	String	true
Insert	dataToLog	Object	insertResult
Insert	prettyPrint	String	true

MySQL Service Task

The sample project set following parameters (Click on service task -> Properties (Pen icon right hand side) -> Data Assignments):

Name	Data Type	Source
username	String	MySQL DB Username
password	String	MySQL DB Password
url	String	jdbc:mysql://${host}:${port}/{dbName}
taskToInsert	Object	response

Name	Data Type	Target
completed	String	insertResult

You also need to have a table in MySQL with following schema:

mysql> use pam;
Database changed
mysql> show columns from task;
+-----------+------------+------+-----+---------+-------+
| Field     | Type       | Null | Key | Default | Extra |
+-----------+------------+------+-----+---------+-------+
| id        | bigint     | YES  |     | NULL    |       |
| user_id   | bigint     | YES  |     | NULL    |       |
| title     | mediumtext | YES  |     | NULL    |       |
| completed | tinyint(1) | YES  |     | NULL    |       |
+-----------+------------+------+-----+---------+-------+
4 rows in set (0.01 sec)

Triggering the Process

The Business Central comes with Swagger Web Interface (default URL: http(s)://${BC_HOST}:${BC_PORT}/kie-server/docs). For details please refer to the official documentation.

After successfully build and deploy the project to KIE server one can use POST endpoint /server/containers/{containerId}/processes/{processId}/instances under Process Instances group to trigger the process:

KIE Server Status	Swagger UI

The endpoint requires two parameters:

• container id where the process definition resides -> Deployment
• process id that new instance should be created from -> Definition Id

These two parameters can be retrieved via process definition page:

Process List	Process Details

The body of the post request is the taskId (recall process data that we use in API URL):

{
  "taskId":#
}

The result of the API call is the ID of initiated process:

The conditions on Exclusive Gateway

An Exclusive Gateway (or XOR Gateway) joins alternative paths within a Process flow. The flow continues through only one of the paths that satisfies condition set on it.

The sample project joins two paths on an Exclusive Gateway with following conditions:

Completed	Not Completed

Result of the Process Execution

The sample project has a business process design that persists data of given task ID to designated MySQL DB if it is completed.

Not Completed Task:

The external test API returns following data for task #1:

{
  "userId": 1,
  "id": 1,
  "title": "delectus aut autem",
  "completed": false
}

After execution via Swagger UI the stdout log stream of BC server is as follows (the result of custom log service task executions):

curl -X POST "http://localhost:8080/kie-server/services/rest/server/containers/ToDo_1.0.0-SNAPSHOT/processes/ToDo.evaluation/instances" -H "accept: application/json" -H "content-type: application/json" -d "{ \"taskId\": 1}"

redhat-pam     | 20-09-2020 19:07:14,817 INFO  [com.corp.concepts.process.automation.handler.log.LogTaskWorkItemHandler] (default task-34) [CustomLogTask-2] Data:
redhat-pam     |  {
redhat-pam     |   "userId" : 1,
redhat-pam     |   "id" : 1,
redhat-pam     |   "title" : "delectus aut autem",
redhat-pam     |   "completed" : false
redhat-pam     | }
redhat-pam     | 20-09-2020 19:07:14,836 INFO  [com.corp.concepts.process.automation.handler.log.LogTaskWorkItemHandler] (default task-34) [CustomLogTask-3] Data:
redhat-pam     |  "false"

The MySQL DB table contains no data:

mysql> use pam;
Database changed

mysql> select * from task;
Empty set (0.00 sec)

Completed Task:

The external test API returns following data for task #44:

{
  "userId": 3,
  "id": 44,
  "title": "cum debitis quis accusamus doloremque ipsa natus sapiente omnis",
  "completed": true
}

After execution via Swagger UI the stdout log stream of BC server is as follows (the result of custom log service task executions):

curl -X POST "http://localhost:8080/kie-server/services/rest/server/containers/ToDo_1.0.0-SNAPSHOT/processes/ToDo.evaluation/instances" -H "accept: application/json" -H "content-type: application/json" -d "{ \"taskId\": 44}"

redhat-pam     | 20-09-2020 19:26:18,417 INFO  [com.corp.concepts.process.automation.handler.log.LogTaskWorkItemHandler] (default task-34) [CustomLogTask-5] Data:
redhat-pam     |  {
redhat-pam     |   "userId" : 3,
redhat-pam     |   "id" : 44,
redhat-pam     |   "title" : "cum debitis quis accusamus doloremque ipsa natus sapiente omnis",
redhat-pam     |   "completed" : true
redhat-pam     | }
redhat-pam     | 20-09-2020 19:26:18,438 INFO  [com.corp.concepts.process.automation.handler.log.LogTaskWorkItemHandler] (default task-34) [CustomLogTask-6] Data:
redhat-pam     |  "true"
redhat-pam     | 20-09-2020 19:26:18,786 INFO  [com.corp.concepts.process.automation.handler.mysql.MySQLWorkItemHandler] (default task-34) Insert statement: com.mysql.jdbc.JDBC42PreparedStatement@3224a981: insert into task (completed,user_id,title,id) values (1,3,'cum debitis quis accusamus doloremque ipsa natus sapiente omnis',44)
redhat-pam     | 20-09-2020 19:26:18,803 INFO  [com.corp.concepts.process.automation.handler.log.LogTaskWorkItemHandler] (default task-34) [CustomLogTask-8] Data:
redhat-pam     |  true

The MySQL DB table contains data of related task:

mysql> use pam;
Database changed

mysql> select * from task;
+------+---------+-----------------------------------------------------------------+-----------+
| id   | user_id | title                                                           | completed |
+------+---------+-----------------------------------------------------------------+-----------+
|   44 |       3 | cum debitis quis accusamus doloremque ipsa natus sapiente omnis |         1 |
+------+---------+-----------------------------------------------------------------+-----------+
1 row in set (0.00 sec)

Docker

The sample project uses Docker images from docker-images repository:

docker-compose -f ./docker-images/redhat/pam/docker-compose.yml mysql pam openldap mavenserver