Using jBPM's RESTful API as a Black Box Workflow Server

I recently started prototyping the idea of using JBoss jBPM as a solution to meet the workflow needs of a proprietary application. Ultimately, my plan is to build a Docker image to hold the jBPM application, which will act as a black box responding to RESTful API calls from my core application.

Without getting into the sensitive information for my application, for this article, I am going to use the jBPM Workbench Showcase Docker image provided by JBoss. Once a container is started from this image, a demo environment can be used to get a feel of how jBPM functions.

The Sample Process Flow - Employee Review

Most corporate employees are familiar with the performance review process. This is where employees have to perform a self-assessment of their job performance. Once the self-assessment is completed, the employee's immediate manager/supervisor provides a review of the employee. The sample flow within jBPM is an employee review ... or evaluation. When we look at the process flow, it appears as shown below:

The jBPM application provides the ability to build the flow as shown above:

• Employee performs a self-review

• The employee's manager (PM) reviews the employee

• The Human Resources (HR) department adds to the review as well

As you might expect, the employee's self-review is the starting point. From there, the flow branches to allow the PM and HR reviews to occur in parallel. Once both parallel reviews are completed, the review cycle is considered finished.

As an FYI, the jBPM application allows for the flows to be imported from Business Process Execution Language (BPEL) as well.

How jBPM is Designed

At the highest level, a Process Model is created, which was displayed above. Once the model is ready, the model is versioned and deployed. Process Models contain versions, so that the instances of that model can be tracked back to a given state or point in time.

The deployed flow is referred to as a Process Definition. From there, Process Instances can be created and the workflow steps become Tasks within jBPM.

To put things into perspective with our example, the Process Model (shown above) was deployed as a Process Flow called Evaluation with a version of 1.0. In jBPM, the deployment is referred to as org.jpm:Evaluation:1.0. Below, is a screenshot from the jBPM Workbench:

If desired, the following RESTful API call could have been used to perform the deployment:

http://myhost/jbpm-console/rest/deployment/org.jbpm:Evaluation:1.0/deploy

With the Process Definition in place, the application server is ready to create Process Instances - which would be one for every employee submitting a performance review. If employee krisv needed to start a review process, the following API call would be executed:

http://myhost/jbpm-console/rest/runtime/org.jbpm:Evaluation:1.0/process/evaluation/start?map_reason=review&map_employee=krisv

The API call executes a start command and passes parameters for reason (map_reason) as review and employee (map_employee) as the username, krisv.

At this point, an instance of the workflow process is ready for use, as shown in the screen shot below:

Performing Tasks Via The RESTful API

The use of the RESTful API allows the jBPM server to act as a black box. Meaning, the application server can process workflow events from an external source without the need to maintain knowledge of the inner workings. This way, the main application doesn't have to include the workflow engine logic, it merely needs to have the ability to interact to jBPM through API calls.

In our example, when user krisv is ready to start his performance review, the source application would send the following API call into jBPM in order to obtain a list of tasks:

http://myhost/jbpm-console/rest/task/query?potentialOwner=krisv

Since, a Process Instance already exists, the following data would be returned:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<task-summary-list-response>
<task-summary>
<id>1</id>
<name>Self Evaluation</name>
<subject></subject>
<description>Please perform a self-evaluation.</description>
<status>Reserved</status>
<priority>0</priority>
<skipable>false</skipable>
<actual-owner>krisv</actual-owner>
<created-by>krisv</created-by>
<created-on>2016-01-06T16:09:38.430Z</created-on>
<activation-time>2016-01-06T16:09:38.430Z</activation-time>
<process-instance-id>1</process-instance-id>
<process-id>evaluation</process-id>
<process-session-id>0</process-session-id>
<deployment-id>org.jbpm:Evaluation:1.0</deployment-id>
<quick-task-summary>false</quick-task-summary>
<parent-id>-1</parent-id>
</task-summary>
</task-summary-list-response>

When user krisv is ready to start his task, the following API call will be made:

http://myhost/jbpm-console/rest/task/1/start

Which returns the following data:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
<status>SUCCESS</status>
<url>/jbpm-console/rest/task/1/start</url>
</response>

The Process Model for krisv's instance appears as shown below:

When krisv is ready to complete his task, the following API call will be made:

http://myhost/jbpm-console/rest/task/1/complete?map_performance=Good

Here, the query parameter of performance (map_performance) was set to be Good. The jBPM server responds with the following information:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
<status>SUCCESS</status>
<url>/jbpm-console/rest/task/1/complete</url>
</response>

Review of the  jBPM Workbench application's Process Instance shows the task was completed and the performance field is recorded as "Good" as shown in the screenshot below:

The Process Model for krisv's instance appears as shown below:

At this point, the parallel review process begins for the PM (management) and HR (human resources) reviews of krisv. The same RESTful endpoints can be made for these two review cycles after the "claim" endpoint is called. The claim end-point is needed since this flow had groups assigned for the PM and HR approvals.

Conclusion

While still in the early stages of prototyping jBPM as a black box workflow server, I am excited at the progress that has been made thus far. I plan to continue down this path and hope to utilize JBoss Drools as well, which would be implemented as another black box Docker image to house complex business rules. Since jBPM captures metrics from the Process Instances, I should be able to provide KPI information back to the line of business managers and directors who are funding this effort.

Have a really great day!