DEV Community: Karina Macedo Varela

Delivering domain logic with Custom Tasks

Karina Macedo Varela — Sun, 05 Jul 2020 23:02:07 +0000

Custom Tasks, a.k.a. custom Work Items are used when the natively provided components are not clear enough to demonstrate the required domain demands. See examples of domain-specific tasks that a business user would find useful to have available in the process designer:

Enhance customer data;
Validate Personal ID against Official State Service;
Check customer health plan;
Calculate tax over an acquisition;

Creation of custom work item handler demands the involvement of a developer which knows Java. Once developed and deployed, the custom WIH will be displayed in the process designer components tab, along with the other bpmn2 tasks. In this way the business automation specialists can drag and drop it into the flow, and care only about the parameters, and not about the logic execution itself.

Let’s separate the Custom WIH in four topics:

Development: Creation of the project and development of the core logic.
Deployment: Provision of the custom tasks in a service repository.
Installation: Act of choosing available tasks from the service repository and installing into a Business Central.
Usage: Using the new custom task in process design.

Once developed, deployed and installed, the custom task is displayed in the process designer pallet, under the service tasks option ready to be used during the authoring phase.

Development

To develop a custom WI, a new Java project needs to be created. This project can be created from scratch or from an official jBPM maven archetype.

Here is some important information the developer should know:

Creating the project that will hold the WI, based on the archetype will provide all the necessary structure including test samples; It will also provide generation, deployment and installing features.
To use the archetype it is necessary to clone the project jbpm-work-itemto the local environment. This will eliminate a lot of manual work and save dev time.
The archetype is org.jbpm.jbpm-workitems-archetype, and it is available in the project https://github.com/kiegroup/jbpm/tree/master/jbpm-workitems/jbpm-workitems-archetype.
The project is Maven based and can be edited in your favorite IDE; The project core is consisted initially by one class: CustomWorkItemHandler.java (it may have a different prefix other than “Custom”)
In this class is the method where the developer should code the domain specific custom logic, executeWorkItem. This method is executed when your task is activated;
Then, if the task finishes successfully, the engine will trigger the method completeWorkItem ;
If the task gets aborted, the abortWorkItem method will be triggered.

Creating a custom task

Let’s see how to create it using a maven archetype org.jbpm.jbpm-workitems-archetype which provides all the basic starters already set and ready to use.

[INFO] For versions prior to jBPM 7.40.0 , it is required to use JDK 8. You can confirm you Java version by running the “java -version” command on your terminal. Check details here: https://issues.redhat.com/browse/JBPM-9204

The first step is to download the project which contains the official work item archetype:

$ mkdir ~/projects/jbpm-getting-started-lab/ && cd ~/projects/jbpm-getting-started-lab/$ git clone https://github.com/kiegroup/jbpm-work-items$ cd jbpm-work-items$ mvn clean install

It might take a while until the dependencies are downloaded. Then, it is possible to create a new project using the archetype:

$ mvn archetype:generate -DarchetypeGroupId=org.jbpm -DarchetypeArtifactId=jbpm-workitems-archetype -DarchetypeVersion= **7.40.0-SNAPSHOT** -DgroupId= **org.kie.learning** -DartifactId= **hello-workitem** -DclassPrefix= **Custom** -Dversion= **7.40.0-SNAPSHOT** -DarchetypeCatalog=local

The following parameters can be changed according to your environment and needs.

artifactId : name of your project
groupId : group id used in your project
classPrefix : will be appended to the work item files;
archetypeVersion : Should be set according to the version of jBPM you just cloned. You can check that on the pom.xml using the command

$ head -10 ~/projects/jbpm-getting-started-lab/jbpm-work-items/pom.xml

After executing the archetype generation command, Maven will download all the required libs to build the project. You will be asked to confirm if the data is correct. If it is correct, input Y and press enter.

A new project will be created in the current directory with the name of your artifactId, in this example, hello-workitem. The developer can import the project to eclipse, check its structure, created classes, annotations, tests and implement the custom logic.

Once the development is done, compile the project with mvn clean install. The file jar file is created inside the target folder.

Now, it is ready to be deployed to jBPM and configured in BA Projects.

Deployment

Once the coding phase is done, the project should be compiled and installed in a maven repository which is visible for Business Central (during authoring) and for Kie Server (for execution).

Compile the project using the command below and the jar will be available inside target folder.

$ cd hello-workitem/$ mvn clean package

Install it into the maven repository or do this using business central UI.

Access Business Central settings (right up corner settings icon), and access Service Tasks Administration menu.

Click on “Add Service Task” button and upload the jar generated inside your project target folder i.e. ~/projects/labs/hello-workitem/target/hello-workitem-7.40.0-SNAPSHOT.jar.

After deploying it, look for it in the task list and enable it.

If you open the class src/main/java/org/kie/learning/CustomWorkItemHandler.java, you will see the class-level annotation defining this WIH name as “CustomDefinitions”.

The custom WIH will now be available to be installed in any project. Let’s proceed.

Installation

Now that your Business Central and Kie Server have access to your custom task (the jar is in the maven repository), the business application can be configured.

Access the project, and open the project settings;

Select the “Service Tasks” menu
Locate your custom task in the list and click on the “Install” button.

Check if it is properly configured under Deployment, Work Item Handler, if the WIH with the name you configured and class are present, for example: CustomDefinitions, new org.kie.learning.CustomWorkItemHandler()
Hit the save button.

If you open a new business process and check the tasks, you will be able to see your custom task:

That’s it, you can now create custom tasks with so that the user who is authoring business process can re-use domain logic in a more customize and visible way.

This blog post is part of the fourth section of the jBPM Getting started series:

Effective modeling, Integration and Delivery.

jBPM: Consuming business assets via REST

Karina Macedo Varela — Wed, 01 Jul 2020 01:09:25 +0000

As expected as default over any REST communication, when the integration via client and Kie Server is done via REST, there is no guarantee on the delivery or retry of this message.

The initialization of Kie Services Client requires an instance of org.kie.server.client.KieServicesConfiguration.

When using the REST approach, we should create the instance of KieServicesConfiguration with the method KieServicesFactory.newRestConfiguration.

To create a new Rest Configuration, it’s required to inform the auth data, URL where the Kie Server is located. Optionally it is possible to set the timeout in milliseconds for this connection attempt.

Recommendation about the URL : If the architecture contains only one Kie Server, point the client URL configuration to the Kie Server domain: “/kie-server/services/rest/server”. If the architecture contains multiple kie servers, you might need to add a kie smart router component. The kie smart router is especially useful in auto-scalable cloud environments when it is hard to maintain the clients’ code that interacts via dynamic addresses. In this case, the URL should point to the smart-router root URL.

TIP: When using smart-router, the kie server url path “kie-server/services/rest/server/” is omitted. In kie-server a new process can be created with a URL like: http://localhost:8080/kie-server/services/rest/server/containers/{containerId}/processes/{processId}/instances. In smart router, the same action is available via: http://localhost:9000/containers/{containerId}/processes/{processId}/instances.

The default timeout is 5000ms, and the default Marshaling Format is JAXB (XML). Consider we have an up and running instance of Kie Server on a WildFly serving on localhost:8080, where we are connecting with user “kieserver”, password “kieserver1!” and setting a timeout of 6 seconds. The Kie Client Configuration could be created like:

private static final String KIESERVER\_URL = "http://localhost:8080/kie-server/services/rest/server";
private static final String KIESERVER\_USER = "kieserver";
private static final String KIESERVER\_PASSWORD = "kieserver1!";private static final long KIESERVER\_CONNECTION\_TIMEOUT = 6000l;
private static final MarshallingFormat KIESERVER\_MARSHALLING = MarshallingFormat.JSON;final KieServicesConfiguration connectionConfig = KieServicesFactory.newRestConfiguration( KIESERVER\_URL, KIESERVER\_USER, KIESERVER\_PASSWORD, KIESERVER\_CONNECTION\_TIMEOUT);
connectionConfig.setMarshallingFormat(KIESERVER\_MARSHALLING);

When using a client application, developers generally use custom domain objects to interact with business processes, tasks, or rules. For example, if starting a medical attendance, probably, the patient information is an input for this process. All these information are modeled into data objects. Kie Server has the capability to automatically marshal and unmarshal objects that are sent and retrieved by it. This being said, if you are starting a process using a client application, you could just say “Kie Server, start a new process with this instance of Patient object”. When properly configured, the client automatically creates a rest request where these parameters are sent using a format (the Marshalling Format), in this case, a JSON format.

When the request reaches Kie Server, it is able to parse this object and associate it to the respective process variable. But when we are using objects other than the basic ones (String, Boolean, Long, Integer, Object, …), we need to inform to the Configuration, which are these custom classes we are transmitting via requests.

The following example, adds a “Patient” custom data object class to the Kie Configuration so that Kie Server knows how to marshall and unmarshall it. The extra classes configuration looks like below, where :

Set<Class<?>> customClassesList = new HashSet<Class<?>>(); customClassesList.add(Patient.class); connectionConfig.addExtraClasses(extraClassList);

TIP: Currently, the Marshalling Format options are XTREAM, XML and JSON. Check more details on org.kie.server.api.marshalling.MarshallingFormatclass.

Once configured, the developer is now ready to create an instance of the client and consume the assets. Let’s check this step by step on practice.

Integrating a Quarkus Application with Kie Server

In order to create a client application to consume a business project deployed in a Kie Container, inside Kie Server, let’s use Quarkus.

Creating the Quarkus Project – the client app

Create the folder below or choose a folder where we will create a new project.

$ mkdir -p ~/projects/labs

Inside $HOME/projects/labs/, create a new Quarkus project using the maven archetype below. A pre-configured project will be created with the REST class pointed in the command below.

$ mvn io.quarkus:quarkus-maven-plugin:1.5.2.Final:create -DprojectGroupId=org.kvarela -DprojectArtifactId=kie-client-lab -DclassName="org.kvarela.rest.client.HelloKieServerResource" -Dpath="/hello-kieserver" -Dextensions="resteasy-jsonb"$ cd kie-client-lab/

Run it using mvn compile quarkus:dev -Dquarkus.http.port=8081 . In the first time, Maven will download the required libraries and start the application in sequence
Open Eclipse or any other preferred IDE, and import this maven project. You have a new Java application with rest capabilities ready to go. If you want to confirm, point your browser to http://localhost:8081/hello-kieserver and check the output “hello” printed.

Now let’s configure this project, enabling it to consume business assets from jBPM engine, Kie Server.

The Kie Service – Configuring Kie Client API and testing the client application

To configure the KIE client API and use it, you can follow the step-by-step below. If you want to check the complete application you can check it here: https://github.com/kmacedovarela/kie-client-lab

In pom.xml, add the maven dependency for the kie-server-clientaccording to your jBPM version. In this example, jbpm.version is a property configured with value 7.38.0.Final.

<dependency> <groupId>org.kie.server</groupId> <artifactId>kie-server-client</artifactId> <version>${jbpm.version}</version> </dependency>

IMPORTANT: In versions prior to 7.39.0.Final, there is a conflict in between imported Jackson libraries (details in JBPM-8937 ). Due to that, a little trick is necessary to exclude jackson dependencies from kie-server-client, and import the proper libraries versions.

Now, add a class that is responsible for connecting the client application to the Kie Server, during the application startup. Name it KieClientInitializer (or any another preferred name);

public class KieClientInitializer implements java.io.Serializable {

Annotate it with @javax.enterprise.context.ApplicationScoped, and add a new method onStart. Let’s also add some logging to test our app. This method will be invoked during the application start up. It should look like this:

@ApplicationScopedpublic class KieClientInitializer implements java.io.Serializable {

private static final Logger LOGGER = LoggerFactory.getLogger("KieClientInitializer"); 

void onStart(@Observes StartupEvent ev) { 
    // LOGGER.info("The 
    application is starting..."); 
}}

Validate your configuration by restarting quarkus, and checking if your logs are outputted. Something similar to the bold logs below.

**2020-06-28 21:16:54,879 INFO [KieClientInitializer] (Quarkus Main Thread) The application is starting…**2020-06-28 21:16:54,990 INFO [io.quarkus] (Quarkus Main Thread) kie-client-lab 1.0-SNAPSHOT on JVM (powered by Quarkus 1.5.2.Final) started in 1.185s. Listening on: http://0.0.0.0:80812020-06-28 21:16:54,993 INFO [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.2020-06-28 21:16:54,993 INFO [io.quarkus] (Quarkus Main Thread) Installed features: [cdi, resteasy, resteasy-jsonb]

INFO: Java EE EJB provides the annotation @javax.ejb.Startup to create a startup service. In a Quarkus application, we are going to use start event to initialize our connection. More information can be found at: https://quarkus.io/guides/application-lifecycle-events-guide

Following the variable examples presented in the previous explanations, create the REST connection settings, and initialize your REST connection.

5.1. Add the KieServicesClient variable. We will use this client to list all the deployed kie containers. There is a client for each need as mentioned in this post, like, interacting with processes, rules, etc…

private static KieServicesClient kieServicesClient;

5.2. Declare the class variables containing the connection settings:

private static final String KIESERVER\_URL = "http://localhost:8080/kie-server/services/rest/server";private static final String KIESERVER\_USER = "kieserver";private static final String KIESERVER\_PASSWORD = "kieserver1!";private static final MarshallingFormat KIESERVER\_MARSHALLING = MarshallingFormat.JSON;private static final long KIESERVER\_CONNECTION\_TIMEOUT = 6000l;

5.3. Add a method that builds the Kie Services Client based on the rest configuration:

private void buildKieServicesClient(){final KieServicesConfiguration connectionConfig = KieServicesFactory.newRestConfiguration( KIESERVER\_URL, KIESERVER\_USER, KIESERVER\_PASSWORD, KIESERVER\_CONNECTION\_TIMEOUT); connectionConfig.setMarshallingFormat(KIESERVER\_MARSHALLING); // addExtraClasses(connectionConfig); setKieServicesClient(KieServicesFactory.newKieServicesClient(connectionConfig));}

5.4. Invoke this method on the onStart method:

void onStart(@Observes StartupEvent ev) { LOGGER.info("The application is starting..."); buildKieClient();}

Open the terminal and restart your quarkus application, so that it invokes this method during the initialization.

TIP: Since this is an example, you can use the user kieserver and password kieserver1!. In a real-world project, use a new user for the service. Also, make sure you have your jBPM instance up and running in another terminal tab. Our jBPM is running on localhost:8080. Our client service is running on 8081.

In your endpoint named HelloKieServerResource, inside the methodhello, delete the return "hello"; code. Let’s add some code that can list the existing KIE containers:

public String hello() { ServiceResponse<KieContainerResourceList> kieContainers = KieClientInitializer.getKieServicesClient().listContainers(); StringBuffer containersString = new StringBuffer(); containersString.append("Existing containers: \n"); for (KieContainerResource kieContainer : kieContainers.getResult().getContainers()) { containersString.append("\n " + kieContainer.toString()); } return containersString.toString();}

Save your files.

INFO: If you try to start your client and jBPM is not up and running on the socket you configured, you’ll get this error: Caused by: org.kie.server.common.rest.NoEndpointFoundException: No available endpoints found.

That’s it! You have a java client application ready to consume whatever business assets deployed on your Kie Containers. Open your browser, point to http://localhost:8081/ hello-kieserver and you will see a list of all the Kie Containers from the Kie Server. Validate your deployed projects and try to write an endpoint which starts a process and interacts with business tasks. This will make you feel familiar with the API which is intuitive and easy to use.

Last two important tips:

The full application is available here for you to clone and run on your environment: https://github.com/kmacedovarela/kie-client-lab
The official jBPM documentation shows an implementation sample with all the clients. Make sure you check the implementation and explanations available on the class implementation section named: Advanced client configuration example with additional client services

This blog post is part of the sixth section of the jBPM Getting started series:

Consuming Business Assets

Getting Started with the Kie Server Java API

Karina Macedo Varela — Sun, 28 Jun 2020 23:53:09 +0000

Kie Server Java client API is used when it’s necessary to create a Java service to interact with a remote Kie Server (not an embedded engine). Consider that you have an architecture with a Kie Server running your business projects and you want to consume them using a Java service running in another application server (deploying applications in different JVMs is a recommended practice). To allow this service to interact with deployed Kie Containers, it first needs to be authenticated and authorized to execute operations inside Kie Server. Once the service is authorized, it is now possible to create and manipulate Kie Deployments, Containers, interact with business assets and query data.

Kie Server Java client API has core services that can be used in your Java classes to authenticate, manage and consume the assets. These services facilitate the development and interaction with business assets since it is not required to create and parse each detail of the requests (this is a need, for example, in front-end applications which connect directly to Kie Server).

TIP: Instead of presenting details of each available method in the services, the author opted to present the documentation and source code, which is the best origin of reliable knowledge. All the classes presented in this section are in the source code in the jBPM repository: https://github.com/kiegroup/droolsjbpm-integration/blob/master/kie-server-parent/kie-server-remote/kie-server-client/src/main/java/org/kie/server/client/

The available services that can be used to interact with Kie Server and business projects are:

Kie Management Related: org.kie.server.client.KieServicesClientorg.kie.server.client.KieServicesConfigurationorg.kie.server.client.KieServicesFactory
Cases Related org.kie.server.client.CaseServicesClient;org.kie.server.client.DocumentServicesClient
Rules Related org.kie.server.client.DMNServicesClientorg.kie.server.client.RuleServicesClient
Solver Related org.kie.server.client.SolverServicesClient
Process Related org.kie.server.client.ProcessServicesClientorg.kie.server.client.QueryServicesClientorg.kie.server.client.JobServicesClient

Every client application needs to be authenticated and authorized to interact with Kie Server. The necessary role to authorize this interaction is kie-server role. The user containing this role should be configured in the application server where Kie Server is running, or, it should exist in the external IDP (i.e. Keycloak).

The following guideline provides overall steps on how to configure the Kie Client Java API in any Java application. Details on REST and JMS integration configuration are provided in sequence. To allow an application to interact with business assets:

Add the kie server client library as a dependency in the client application project:
- To consume remote kie servers, add org.kie.server:kie-server-client dependency in the pom.xml file.
Create a configuration class (extending KieServicesConfiguration) . This class indicates whether this is a JMS or a REST client. Additionally, it contains the connection settings used to integrate with the Kie Server. Let’s see more details on each respective topic in a while.
Once the configuration is set, use KieServicesFactory to create a newKie Services Client. It’s recommended that this is done only once, for example during the application startup. All the client services presented in the previous services table are accessible from KieServicesClient instance. Use the configuration created on step 2, as to create this object:

kieServicesClient = KieServicesFactory.newKieServicesClient(conf);

Choose the services you need in this client, and initialize them. Example:

ProcessServicesClient processService = kieServicesClient.getServicesClient(ProcessServicesClient.class);

Use the services as you wish. For example, to start a new process instance:

processService.startProcess("container:id", "processId");

After following these steps this application is now a client ready to interact with any deployed business application inside the configured remote Kie Server. The developer can now do all kinds of integration: fire rules, manage and interact with processes, cases, and resource planning assets.

This blog post is part of the sixth section of the jBPM Getting started series:

Consuming Business Assets

jBPM: Mastering Transaction Boundaries

Karina Macedo Varela — Sun, 28 Jun 2020 23:33:14 +0000

When planning usage of processes that are complex, long-running, and with possible points of failures like custom work item handlers, asynchronous tasks, timers, signals, and service tasks, it is crucial to understand how jBPM deals with transactions.

This knowledge might save some troubleshooting hours if you have persistent processes. “Why?“, you might ask: if the process is not properly designed and an unhandled error occurs, you may end-up with tasks being triggered more times than you planned.

Let’s drill down.

During the following process execution, jBPM will execute all these tasks in a single transaction:

Therefore, if the process reaches Service B, and it throws an exception, Service A won’t be rolled back. This process will not be persisted on the database, it is like it was never executed. This would happen because there is no wait state point in this process.

To the engine, a wait state is any point during the process execution which it might need to wait for some external intervention. When this occurs, the engine persists the process state in the database. These are the possible wait states of a process:

Human Tasks
Catch events (signals, timers)
Async Tasks (marked with Async flag)

So, if we consider the following process, what will happen if Service B throws an exception?

If service B with an unrecoverable error and throwing exception, Service A would be triggered three times. (worrying, right?)

In this case, the process was persisted when the human task was completed. So, when Service B threw an exception, the transaction will roll back and return to the Human Task again. Gateway is validated, Service A is triggered the second time, and then, Service B is triggered. If B throws an exception, the execution again returns to the Human Task. This will happen as many times as configured in the engine retry count, which by default is three.

In cases like the one represented below, by simply configuring Rest Task 2 as Async you can make the engine persist the process state, and in case of an error on REST Task 3, Rest Task 1 and 2 would not be executed again.

To avoid situations like this, during the process authoring, have the transaction boundaries clear in your mind. Choose wisely which task should be async, which are the wait states, and if you need to create any wait state or handle errors with compensation events to avoid unexpected businesses outcomes.

Summary

Understanding how the engine works will help business automation specialists and developers to deliver fine-tuned projects that perform better on the jBPM engine. The business automation specialist should be able to absorb the business requirements and be able to reflect this on the project not only by authoring the assets but by improving the execution of these assets adjusting every configuration to best perform in each scenario and by being able to understand the impacts of the transaction boundaries in each delivered process.

This blog post is part of the fifth section of the jBPM Getting started series:

Techniques to boost a BA Project

jBPM: Persisting domain data in a custom database

Karina Macedo Varela — Wed, 17 Jun 2020 10:00:00 +0000

When working with business processes, it is expected to work with persistent process data scenarios. Considering this situation, it is common for users to use a different database to store process data, apart from the database where the domain information is stored.

As an example, storing critical information from customers apart from the engine database is an expected data architecture. In this way, the user can maintain the data consistent and isolated. But what if these objects, stored in a different database, needs to be used in one of the business automation projects?

[INFO] Many of the concepts here applied are valid for any application which involves distributed transactions (XA Transactions), this means, any application which might possibly have a transaction which spawns through two or more different databases. An overview of how application deployed in Java EE application servers, communicates with a database can be found at this blog post:Datasources, what, why, how?

Let’s understand how to configure and access different databases within the same project.

Pluggable Variable Persistence (PVP)

Here are the steps required to make a business automation process store process variables (domain information) in a different database:

Configure the app server datasource pointing the database where you want to store the custom data;
Make sure custom POJOs (the object to be persisted) are a JPA object
1. Data Object must implement Serializable interface;
2. Must be a JPA Entity;
3. Must have a unique id, a primary key;
Configure business automation project
1. Configure a JPA Marshalling Strategy;
2. Configure the persistence unit (pointing to the datasource mentioned on the first step);

Once this is done, every time this object gets created or updated during the process execution, it will be properly persisted on the database. Let’s check this with a hands-on exercise.

Persisting custom objects using PVP

Bootstrap a database

To run this example, using docker to start a database is the easiest way to get a database up and running. Make sure you have docker running in your environment. Let’s create a directory to store the database information.

$ mkdir -p ~/projects/jbpm-getting-started-lab/postgresql

Make sure you have Docker up and running. Then you can start a Postgres container:

$ docker run --name jbpm-postgres-container -e POSTGRES\_PASSWORD=psqlpass -d -p 6543:5432 -v $HOME/projects/jbpm-getting-started-lab/postgres:/var/lib/postgresql postgres:9.4

This command will download the image (if you don’t have it locally), start a container named postgres, based on the latest PostgreSQL image. expose the internal port 5432 opened by PostgreSQL, to be accessed externally also in 6543.

Let’s enter in this SQL Server to create a new database for our jBPM tables. Run the command below to get the Container ID of this psql container:

$ docker psCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES620350186bbe postgres:9.4 "docker-entrypoint.s…" About a minute ago Up About a minute 0.0.0.0:6543->5432/tcp jbpm-postgres-container

Use the whole ID, or simply the first two numbers, to enter the container. Then, we will start the psql client:

$ docker exec -it jbpm-postgres-container /bin/bash $ psql -h localhost -U postgres -d postgres

Now, let’s create a database to be used by jBPM, with a new a user and password. This user needs permision on this new database. The tables will be created automatically by jBPM on startup.

[TIP] You might want to create additional indexes on some tables and columns in your production environment

CREATE DATABASE jbpmdb;CREATE USER jbpmdb WITH ENCRYPTED PASSWORD 'jbpmdb';GRANT ALL PRIVILEGES ON DATABASE jbpmdb TO jbpmdb;

And create another database, to store the specific domain data.

CREATE DATABASE labpvp;CREATE USER labuser WITH ENCRYPTED PASSWORD 'labuser';GRANT ALL PRIVILEGES ON DATABASE labpvp TO labuser;

When done, type \q and press enter, to quit psql client, and then exit to exit the container.

Configuring the Application Server

Now, let’s configure WildFly: we will create two datasources one connecting to jbpmdb and other to labpvp . Once the datasources are configured, applications can start connecting to these databases.

In this example we expect that you have downloaded jBPM and have it available in your ~/projects directory. If you want to use the commands here, you can optionally create a symbolic link for the folder with the command below:

$ ln -s ~/projects/jbpm-server-7.38.0.Final-dist ~/projects/jbpm

Configuring WildFly basically requires two steps:

Adding a JDBC driver (the responsible for teaching WildFly how to talk the specific database language);
Adding a datasource with the credentials, connection URL, and driver information.

The simplest way to add a JDBC driver to WildFly is deploying it. Download postgresql-42.2.2.jarand place it into ~/projects/jbpm/standalone/deployments. WildFly will immediately tell you the driver is deployed:

16:11:07,515 INFO [org.jboss.as.connector.deployers.jdbc] (MSC service thread 1-4) WFLYJCA0005: Deploying non-JDBC-compliant driver class org.postgresql.Driver (version 42.2)16:11:07,540 INFO [org.jboss.as.connector.deployers.jdbc] (MSC service thread 1-5) WFLYJCA0018: Started Driver service with driver-name = postgresql-42.2.12.jar16:13:33,885 INFO [org.jboss.as.server] (ServerService Thread Pool -- 45) WFLYSRV0010: Deployed "postgresql-42.2.12.jar" (runtime-name : "postgresql-42.2.12.jar")

Let’s use the JBoss CLI script, which is less error-prone, to do the configuration. Start your WildFly in one terminal tab, and open another terminal tab so you can connect to it using CLI.

$ ~/projects/jbpm/bin/jboss-cli.sh -c

Add a new datasource, informing the connection data, and your deployed driver name:

[standalone@localhost:9990 /] xa-data-source add --name=psqljBPMXA --jndi-name=" **java:/jboss/datasources/psqljBPMXADS**" --user-name= **jbpmdb** --password= **jbpmdb** --driver-name= **postgresql-42.2.2.jar** --xa-datasource-class=org.postgresql.xa.PGXADataSource --xa-datasource-properties=[{ServerName= **localhost** ,PortNumber= **6543** ,DatabaseName= **jbpmdb** }]

Now, let’s add a datasource to connect to our domain-specific database, labpvp:

[standalone@localhost:9990 /] xa-data-source add --name=psqlLabPVP --jndi-name=" **java:/jboss/datasources/psqlLabPVP**" --user-name= **labuser** --password= **labuser** --driver-name= **postgresql-42.2.2.jar** --xa-datasource-class=org.postgresql.xa.PGXADataSource --xa-datasource-properties=[{ServerName= **localhost** ,PortNumber= **6543** ,DatabaseName= **labpvp** }]

The following test commands validate both datasource configurations:

[standalone@localhost:9990 /] /subsystem=datasources/xa-data-source=psqljBPMXA:test-connection-in-pool{"outcome" => "success","result" => [true]}

Finally, we need to tell jBPM to stop using the H2 database and start using Postgres by connecting through the datasource with JNDI name: java:/jboss/datasources/psqljBPMXADS .

[standalone@localhost:9990 /] /system-property=org.kie.server.persistence.ds:write-attribute(value=java:/jboss/datasources/psqljBPMXADS, name=value)[standalone@localhost:9990 /] /system-property=org.kie.server.persistence.dialect:add(value=org.hibernate.dialect.PostgreSQLDialect)

Restart jBPM.

It will bootstrap creating its tables inside the Postgres in your docker container. You can confirm this by getting into your Postgres container and listing the tables:

$ docker exec -it jbpm-postgres-container /bin/bashroot@620350186bbe:/# psql -h localhost -U jbpmdb -d jbpmdbpsql (9.4.22)Type "help" for help.jbpmdb=> **\d**

Creating persistent objects with Business Central

Scenario: You joined a team which has on-going project, hello-jbpm. In this project, the final user does a question, complain or suggestion and gets an automatic or a manual answer. You noticed that the data architecture can be improved by storing the reported issue and person details, into a separate database. apart from the one used by the engine.

Import project 02-customer-service-jbpm if you don’t have it in your business central yet. You should see it in your space:

In order to persist a POJO into a database, we need will make use of JPA benefits and to convert it into a JPA Entity.

Open hello-jbpm project, and notice both data object named Issue and the Person.

You can use the filter to see only specific types of assets. In this example the list is filtered to show only Model assets.

Let’s start by configuring Person. By clicking on the “Source” tab you can view it’s code.

[TIP] In order to be persisted, classes should implement java.io.Serializable interface. By default, Business Central creates the Data Objects implementing Serializable interface.

Transform it into an entity by adding @javax.persistence.Entity annotation;
Inform the name of the table you want to store this Data Object with the annotation @javax.persistence.Table(name = "Person")
This class does not have a primary key yet. Add an id, with type Long to Person.java. Don’t forget the attribute should have the get and set method and be annotated with @javax.persistence.Id.

Person.java should look like this:

@javax.persistence.Entity @javax.persistence.Table(name = "Person")public class Person implements java.io.Serializable { @javax.persistence.Id @javax.persistence.SequenceGenerator(name = "ID\_GENERATOR", sequenceName = "PERSON\_ID\_SEQUENCE") private java.lang.Long id;

Click on the save button.

Configuring business application persistence unit with Business Central

The persistence unit, if the configuration which tells a Java EE application which datasource it must use to connect to the database. To configure a business application to persist process variables in a custom database, inform the datasource details in the persistence unit, and create a Marshaller configuration. This Marshaller configuration allows the engine to convert the variables data to/from process and database.

When the JPA Marshaller is configured, every JPA Entity used as a process variable, is automatically persisted in the database pointed by the application used datasource.

To configure the persistence unit details, access the project Settings, and select the Persistence option.

Considering we are using PostgreSQL and the datasource configured in the last step, use the following values in the form:

Persistence Unit: customer-service-jbpm-pu
Data Source java:/jboss/datasources/psqlLabPVP
hibernate.dialect: org.hibernate.dialect.PostgreSQLDialect
hibernate.show_sql: true

Set the show_sql attribute to true, to enable logs and permit checking in the server logs if the entity is being manipulated as expected. Save the configuration.
Make sure you scroll down and add the persistable class, Person:

Still in the project Settings, configure the JPA Marshaller. Access the Deployments option, and select Marshalling Strategies.

Click on “Add Marshalling Strategy“, insert the following value and hit save:

new org.drools.persistence.jpa.marshaller.JPAPlaceholderResolverStrategy("customer-service-jbpm-pu", classLoader)

Now you have JPA Classes ready to be used as process variables, and to be automatically persisted in a different database!

You can check the result of this work by clicking on the Deploy button. If everything is properly set, you should see something similar in the server log:

17:41:12,801 INFO [stdout] (default task-20) Hibernate: create table Person (id int8 not null, birthDate timestamp, name varchar(255), primary key (id))

Start a new process instance, and validate if the object was persisted in the database table you specified.

This blog post is part of the fifth section of the jBPM Getting started series:

Techniques to boost a BA Project

jBPM: Runtime Strategy: Choose wisely

Karina Macedo Varela — Tue, 16 Jun 2020 17:50:37 +0000

Kie Server can be configured to deal differently with the requests it receives and the objects it stores in memory or in the database. Properly configuring how the engine deals with the objects in memory, ensures a project with fewer resource consumption and avoids unexpected behaviors.

Runtime Strategy configuration affects directly how the engine deals with the lifecycle of the Kie Sessions and objects loaded in memory.

You have to choose between four options, for each new project deployment you create:

Singleton Runtime Strategy
Per Process Runtime Strategy
Per Request Runtime Strategy
Per Case

Choosing a strategy

Understand the key concepts of each strategy to guide your decision of when you should use each of them:

Singleton Runtime Strategy: If you create and deploy a project, this runtime strategy configuration is used. It’s the default configuration. This strategy uses a single Kie Session. This makes things easier for beginners since every inserted object is available in the same Kie Session. Also, jBPM persists the Kie Session, and it is reused if the server restarts.

Rule execution within processes can be impacted. Consider that: if process instance A inserts person John to be evaluated by business rules. Process instance B, inserts Maria. Later, when process C fires rules for its own person, John and Maria will still be in memory and will be evaluated by process C rules improperly!

When using this configuration, process execution happens within a synchronized Runtime Engine: it is thread-safe. Consequently, this characteristic can affect and bring consequences on performance. If you expect a high workload, or if the project use timers or signals in the process definitions, you may want to consider a diﬀerent strategy for your production environment.

Per Request Strategy: defines a stateless behavior. The engine will create one Kie Session per request and destroy it at the end. The Kie Session will not be persisted. This is a good choice for high workload environments.

The following situation can occur: Consider two requests executed simultaneously to interact with the same process instance. One of the two requests might lock a database row to update it, and the other request might try to update it as well. This will lead to an OptimisticLockException.

This strategy might do the implementation more challenging if your project uses timers events or if the process involves business rule tasks.

Per Process Instance Strategy: recommended when your process uses timers and businessrule tasks. The Kie Session is created when the process instance starts, and it dies, when the process instance ends. This is usually adequate for most use cases.

Keep in mind: creating Kie Bases is an expensive operation. Creating new Kie Sessions is cheap.

The engine stores the Kie Session in the database, and always use the same Kie Session for the same process instances.

Per Case: this strategy should be used if you are using a Case Management project. If you create a new “Case Project”, this strategy is selected by default. The Kie Session will last while the case is still opened (active).

Now, let’s check the possible places to configure Runtime Strategies, and when should each one be used.

Choosing where to configure the strategy

Container Level : Affects the deployed kjar. Configuration can be made in kie containers using Business Central via the Execution Servers page.

Project level : The configuration will affect only this project. Configuration can be done via Business Central in the XML file or via. Inside the file src/main/resources/META-INF/kie-deployment-descriptor.xml the following configuration is present: SINGLETON

Server level : No UI Available. A new system property needs to be configured pointing to the new file.

This change will impact all projects from this server. A new deployment-descriptor.xml needs to be provided with all the tags and components (not only the ones which you want to customize). The system property is org.kie.deployment.desc.location and its value must point to a valid accessible file: “file:/path/to/file/deployment-descriptor.xml“

[INFO] If using the server level configuration, make sure to provide a valid XML file. See more details about the configuration in the official documentation, topic “ Default deployment descriptor”

https://docs.jboss.org/jbpm/release/latest/jbpm-docs/html_single/#_deployment_descriptors

Finally, considering that we can configure the runtime strategy in three different places, this is how the precedence works by default: Container configuration overrides KJar and Server configs. KJar configuration overrides Server configs.

This blog post is part of the fifth section of the jBPM Getting started series:

Techniques to boost a BA Project

5. Techniques to boost a Business Automation Project

Karina Macedo Varela — Tue, 16 Jun 2020 01:26:27 +0000

Previous posts of thejBPM Getting Started Series should provide a good base for the understanding of this chapter. Also, basic knowledge about application transactions should provide a better understanding of the chapter.

The engine can be tuned for business automation projects to achieve better performance results are achieved. Mainly when involving business rules validation, there are important decisions that need to be taken about the process execution runtime.

And this is not about how to tune your JVM or operational system. This is about using the engine in the best possible way for each project you deliver.

To create high-performance business automation projects, there are some topics in which the business automation specialist needs to worry:

Is your project lightweight and easily scalable?
What is the best way, in each scenario, for the engine to deal with objects in-memory?
Are you properly storing the domain data – do you need to store data in a different data store?
What will happen in cases of failure – make sure no service is called twice unexpectedly!
How can you extend the engine API to better attend to your domain needs?
Do you need special auditing or some type of listener?

Let’s understand a little bit more about how you can improve and adapt your project and the engine in the blog posts of this section:

This section is part of the jBPM Getting Started series

Dealing with Unexpected Errors in Business Processes

Karina Macedo Varela — Mon, 01 Jun 2020 20:12:17 +0000

During the development phase, it is expected that developers deal and treat unexpected behaviors, predictable and unpredicted errors that might happen during the execution of code. Consider the following situation:

An online traveling company named MaTrip.com sells a whole trip experience with a discount for a single package buying: flight + hotel. But each of these services is independent as they are provided by external specialized companies. In this way, MaTrip orders need to interact with the services via services integration.

The customer has bought a trip package and the flight has already been successfully booked. What should happen if the hotel application services go offline for two days? Should the flight be canceled? Should it be automatically reassigned? Should the user be contacted in order to schedule a new trip?

There are several business outcomes to solve this scenario, all it takes is that the developer properly handles this incidents. There are cases where only the main biz scenarios are described by the biz team, and the development team does not have enough information to implement the exception handling. In these cases, the Business Analyst of the project should be involved in order to define the outcomes of these scenarios.

When handling errors like this, for example, in a Java or Javascript code, the developer directly implement exception handling with try and catch; When considering the endpoint layers, developers likely uses HTTP codes to transmit a proper message to the consumer; but, how to deal with exceptions and errors when working with a business flow?

Treating exceptions the right way

Give a look at the following situation, considering it is at an initial development phase. The “happy path” for this trip schedule flow is:

The user selects a trip (User Task);
An embedded subprocess starts to handle pre-reservation;
Both hotel and flight tasks are parallelized for quicker processing ( Divergent Parallel Gateway); Flight and hotel availabilities are checked (RestTask);
Flight and hotel are pre-reserved (Rest Task);
The process only ends steps are completed for both flight and hotel( Convergent Parallel Gateway);
Finally, the user confirms the trip(User Task).

There are two gaps in this process that can lead to instances aborted or failed:

First uncovered scenario: The selected option (flight or hotel) is not available ( business exception );
Second uncovered scenario: One or more rest services are unavailable ( runtime exception );

Treating Business Exceptions

Business Exceptions are errors that are not technical. They are not thrown by unexpectederrors in the code itself. See some examples of business exceptions:

Sell a product that does not exist in the inventory;
Reserve a seat in a full theater movie;
Register a monthly payment twice in the same month;

These exceptions are examples of behaviors directly related to each domain exception. The recommended way to handle business exceptions would be to catch the error

using error events, and then, triggering following actions to handle the error according to the business logic. By using this approach, the whole process – including the treatment of the errors – is clear for all the personas involved in the project. This will facilitate validation by the business users and further maintenance, and enhancements.

Look at this process of a store which opted to follow digital transformation. They allow their customer to select products in a rich multi-channel online store; once payment is confirmed, a personal shopper manually chooses the items; finally, the delivery team takes the order to the customer address:

Both tasks Charge from credit card service and reserve products from stock are rest tasks. Eventually, the store can run out of available products in the stock when the task reserve products from stock is triggered. Does this look like a business exception to you?

Reserve product from stock when the number of available products is zero.

We just identified a business exception: NoAvailableProductException. Let’s consider that this Java REST Service treats this error like this:

if (!product.isAvailable()){ log.error("Product is not available, throwing exception."); throw new NoAvailableProductException(Response.Status.CONFLICT);}

In this example, you can consider that NoAvailableProductException extends WebApplicationException.

Now, the author of the process design knows which error the service will throw in case of a NoAvailableProductException: HTTP 409 code.

javax.ws.rs.core.Response.Status.CONFLICT relates to HTTP 409.

As per RFC specification, this code should be used in situations where the user might be able to try the same request and possibly get a different response. The server should include information about the error in the payload for the consumers.

See more details in: https://tools.ietf.org/html/rfc7231#section-6.5.8

The business automation specialist also receives the updates from the business team, and the new exception flow business scope is also defined: if the product is not available, the personal shopper should call the consumer and switch missing item for a similar one or remove it from the order. The order price will change and the new value should be charged.

Scenario 1: The BA specialist increments his process to deal with the business exception thrown in a specific task: He/She added a boundary intermediate catch event to the REST Task. The error code is configured on the error events properties.

In this way, the business analyst can capture business exceptions thrown in specific tasks and provide proper handling for each scenario. But when there are too many possible errors, this approach can make the process too verbose and might affect the clarity of the flow.

Considering that the same business exception can be thrown by more than one task, the author can choose to group the tasks in a subprocess and catch the exception in the parent process definition. See the following scenario.

Scenario 2: Tasks inside a subprocess throw an error end event, which will be catch and handled by the parent process.

Another possible approach is to store the output of the processing in a process variable instead of throwing an exception. Based on the variable value, a gateway can lead to an end error event which will be handled by an event subprocess.

Scenario 3: Process throws an error endevent, which will be handled by an event subprocess with a starting error event.

The author of the process should choose the proper option which better suits the business needs, worrying about the variable scopes and with the understanding and maintainability of the process. On scenario 2 for example, the variables contained inside the subprocess, will not be available during the handling of the exception in the parent process.

Treating business exceptions inside a business process is considered an advanced process modeling technique, and is crucial for proper implementation of successful projects. The Business Exceptions also matters for the organization improvement and the modeling of it can also lead to the creation of business monitoring dashboards.

Treating Technical Exceptions

Technical exceptions are raised within the code implementation itself and are not related to the domain flow. It can happen on script tasks, on custom code implemented on “On Entry” an “On Exit” properties of tasks and custom Work Item Handlers. See some examples of technical exception:

Can’t unmarshall an object into a specific class;
Try to execute an operation in a null object;
Try to cast an object which cannot be cast;

Integration with external components should be handled by external services and not by treated by the process design itself

This recommendation is based on the fact that processes that fail with technical exceptions are unrecoverable. To know more about technical error exception handling, refer to the official documentation:

https://docs.jboss.org/jbpm/release/latest/jbpm-docs/html_ single/#_technical_exceptions

These kinds of errors can and should be avoided by leveraging the usage of custom code to necessary scenarios, and by increasing the usage of the provided native features. Exceptions raised on script tasks, cannot be caught and handled by the error events demonstrated on the “Business Exceptions” examples.

This blog post is part of the fourth section of the jBPM Getting started series:

Effective modeling, Integration and Delivery.

How to configure notification for Human Task in jBPM

Karina Macedo Varela — Sat, 30 May 2020 14:24:14 +0000

Great post from Sudhish Nair, an expert on process and rules automation.

TechBlogs

jBPM provides options to configure notification emails to be send to any user if the human task is not started or not completed.

We will start with configuring JavaMail sessions via JNDI so that infrastructure for mail is handled.

We would be using “ jbpm-server-7.37.0.Final-dist ” version for this example.

Configure Mail Session in wildfly

In the standalone configuration for jBPM we need add below configurations.

Configure Socket binding for smtp-port

        <outbound-socket-binding name="mail-notification-smtp">
            <remote-destination host="smtp.gmail.com" port="465"/>
        </outbound-socket-binding>

host -: host name of SMTP server

port -: port no of SMTP server.

Configure Mail-Session in Mail subsystem

            <mail-session name="notification" jndi-name="java:/notificationMailSession" from="youremailid@gmail.com">
                <smtp-server outbound-socket-binding-ref="mail-notification-smtp" ssl="true" username="youremailid@gmail.com" password="yourPassw0rd"/>
            </mail-session>

from -: From address for your emails (Valid email account on SMTP server).

username -: username for the email account

password -: password for the email account.

Add below system property to standalone.xml file.

    <system-properties>      
       <property name="org.kie.mail.session" value="java:/notificationMailSession"/>
    </system-properties>

Configure user info for Human…

View original post 423 more words

jBPM: Asynchronous Execution

Karina Macedo Varela — Sat, 23 May 2020 02:43:58 +0000

By default, the flow of tasks is executed in a synchronous way: all tasks will be treated one after the other, by a single thread. This being said, if a process contains, for example, four service calls – where each call lasts around 30 seconds – this process execution will run – and allocate JVM, CPU, etc.. – for long two minutes. And worse, the caller of this instance has to wait for two minutes until getting a response. In scenarios using default configurations, this situation results in a timeout exception.

“But my process is quite simple and it should be faster. The problem is the legacy services we have to interact with. How can we improve this process design to achieve better performance, execution and resource consumption?“

The answer is: Use asynchronous capabilities when you have long-running tasks or when you want to define transaction boundaries (Transction Boundaries will be explained in upcoming posts). In this way, you can delegate the processing of this work unit to a different thread, while the process goes on with the execution.

Here are some possible ways to use asynchronous execution: async tasks, jobs, timers events. The timer and the async tasks can be included in a process diagram. The jobs, differently, are scheduled – registered – within Kie Server to be executed recurrently or not, based on the determined agenda.

Additional Information about timer events and its possible configuration can be found at https://karinavarela.me/2019/06/07/jbpm7-quicktips-timers/.

The tasks (WI) provided by jBPM have a configurable “Async” property. When a task is marked async:

The task will create a wait-state on the process;
The engine does not wait until this task finishes to trigger the next task;
This task execution will be handled in a different thread;
This task will be automatically retried by the Executor in case of failure (read the Jobs section for more details).

Let’s understand the Job feature available in jBPM which also allows asynchronous execution.

A job, simply saying, is an independent code unit that is called based on a schedule and is executed asynchronously, in background. jBPM has a generic environment for the execution of these Commands, where the Job Executor is responsible for triggering the timer events, async tasks and executing scheduled jobs.

The job executor is an out-of-the-box jBPM component responsible for resuming process executions asynchronously. It can be configured to attend custom needs from each environment. Possible configuration about job executor and details about native jobs can be found at the official documentation and additional information is available at.

The Job Executor can properly manage jobs in a clustered environment and guarantee jobs are triggered only once, even if Kie Server runs in a multiple servers architecture. Jobs are persisted and maintained in the database.

On executor start, all jobs are always loaded, regardless if there are one or more instances in the environment. That makes sure all jobs will be executed, even in cases where their fire time has already passed or was scheduled by other executor instance.

Jobs are always stored in DB, no matter what trigger mechanism is used to execute the job (JMS or thread pool). The table RequestInfo stores the jobs that need to be executed. In the expected cycle jobs should be queued, run, and completed. Additionally, it can go through the statuses represented in this diagram.

By default, a single thread pool is used, and services will be retried three times in case of failures. When the executor starts, the following log is displayed in the application server with the current configuration:

23:56:58,050 INFO [org.jbpm.executor.impl.ExecutorImpl] (EJB default - 1) Starting jBPM Executor Component ...- Thread Pool Size: 1-  Retries per Request: 3 -  Load from storage interval: 0 SECONDS (if less or equal 0 only initial sync with storage)

Native jobs, custom jobs, and async tasks execution are performed by the Executor which has the characteristics above. A good example of jobs usage in jBPM is to schedule jobs to maintain a good environment health by constantly cleaning the old database audit data.

Besides supporting the ops team by keeping a healthy environment, making good use of the async behavior and its capabilities lead the dev and BA team to perform a better process design. Additionally, it supports the lifecycle of running processes by providing good visibility of the errors that happened during process execution and allows the possibility of solving the unexpected happenings.

This blog post is part of the fourth section of the jBPM Getting started series:

Effective modeling, Integration and Delivery.

jBPM: User Tasks and Forms

Karina Macedo Varela — Sat, 23 May 2020 02:37:10 +0000

User Tasks allow the interaction of humans with a set of automated tasks. In this way, a series of automatic tasks can be triggered before – providing input for – human decisions, and the output of the user task can then be used to define further actions of a flow.

User tasks have a more elaborate lifecycle than other activity tasks. The lifecycle of a Human Task involves states and actions. The actions that can be used to interact with the human task and change its state.

The same actions can be easily identified in both Kie Rest API (detailed in the /kie-server/docs URL), as in Java Kie API. https://github.com/kiegroup/jbpm/blob/master/jbpm-services/jbpm-services-api/src/main/java/org/jbpm/services/api/admin/ProcessInstanceAdminService.java

Considering the lifecycle of a human task, let’s talk about some possibilities that can be achieved out-of-the-box by using a user task. Here is hiring process an example of a process that has a different ending based on a human decision:

Once started, the candidate should send his curriculum vitae (first user task). The next step is that someone from the Human Resource team picks this task and do an analysis over the candidate curriculum. Based on this analysis, this person should decide whether this is or not an appropriate candidate for the role. This decision is stored in a process variable, that will be evaluated by the exclusive gateway, defining if the candidate was reproved (send an email) or approved (start hiring processes).

Let’s analyze some important concepts based on this example:

The process definition says that the Validate Candidate Profile should be done by someone from the “Human Resources” team. This task is assigned to a group.
This task has an SLA , which determines 5 days as maximum expected duration to the HR group – team – to finish this task. The SLA can also be an expression which holds a process variable like #{determinedDueDate} .

User task variables can be manipulated by the human that owns the task. This is how the process variables are updated by humans involved in this execution:

The process contains two variables named CV and hr_approval. The user that interacts with this task, has access to the variables specified in “Data Inputs and Assignments“, in this case, in_CV. The user can interact with this task in many ways – a form in a web application, mobile app, business central, google home, etc – in whichever way, in the end, this interaction will be converted into a request submitted to the engine.

When the user completes this task, his outputs with the answer are stored into “Data Outputs and Assignments” fields, in this case,out_approval_._ This simple boolean which tells if the candidate was approved or not, will be automatically assigned to the process variable hr_approval in order to be used in other steps of this hiring flow.

Interacting with User Tasks via Business Central

A client application with a customized layout can interact with human tasks via the available APIs, but for now, let’s see how to interact with this task using business central. Business Central provides a Task Inbox, accessible via the menu.

It is required that the user belongs to the HR group , otherwise, he is not a potential owner and won’t be able to visualize the tasks. When the user opens the inbox, he/she will see the list of tasks which he/she is a potential owner:

There are two tasks in this list, because two candidates applied and we have two running process instances. One of the tasks is currently in progress and being executed by a user named karina. Another task is “Ready” to be executed and has no owner. Notice the possible actions for this task: Claim and Claim and Work. But what exactly does this mean?

In order to understand this, we should go back to the _ WS-HT specification _ and the lifecycle of a human task.

Human Task Lifecycle

According to the WS-HT specification, human tasks can be in the following states :

Created, Ready, Reserved, In Progress, Suspended, Completed, Failed, Error, Exited or Obsolete.

And, they can the possible actions can be used upon the human task:

suspend, resume, forward, revoke, claim, start, stop, delegate, complete, exit, skip, nominate, release.

jBPM provides Java client API and REST API available to interact with the task and move it through states. Check these states and actions represented on the following diagram:

jBPM implements an easy and comprehensible flow based on Web Services Human Task specification (a.k.a WS-HT Spec).
http://download.boulder.ibm.com/ibmdl/pub/software/dw/specs/ws-bpel4people/WS-HumanTask_v1.pdf

But how is this translated into a real example? Let’s get back to our hiring process, in the point when the candidate finishes the first task, and the second task is activated:

The engine creates the second human task “Validate Candidate Profile”;
Once the engine finishes this creation, the task will be ready for users of this group;
All the members from this group (HR) are potential owners and consequently, can see this task, but only one at a time can claim it, be the owner of it.
Once claimed , this task will be reserved for this user, and will no longer be part of the list presented to the group.
The user now has the option to start actually working in this task;
The user finishes the analysis and can complete the task, providing the required data.

As showed above, a whole lifecycle of management of user interactions is already provided out-of-the-box by jBPM. The user role also matters. It is directly related to the actions that can be executed over a task.

Form Modeler

We are now going to enhance the human interaction by using forms. The Form Modeler is a component from Business Central which allows the Business Automation Specialist to create forms in a low-code manner. It significantly shortens the time spent into forms creation.

These forms are .frm files delivered as part of the kjar and can be also consumed via rest and embedded into custom client applications. This makes it easy to consume the whole process from a single point, without propagating changes to other services and impacting their functioning.

See how simple it is to create a form for the hiring process: once all the input and output variables are properly defined for user tasks, look for the option Generate all forms in the process designer toolbar.

This option will automatically create one form for each human task present in this process definition with all the fields configured as input/output assignment variables.

All the forms are made available and are accessible via the project lateral toolbar, or in the project main page. The lateral toolbar shows the assets categorized by type.

By clicking on one of the forms, in this example, “ValidateCV-taskform”, the form modeler will open with the generated form. This generated form has a proper field for every variable configured on the input/output assignment variables of the human task. It takes in consideration the variable class type, so for example, for the document it provided a file upload component. For the boolean field, it provided a checkbox.

All the BA specialist needs to do is adjust the form according to the domain knowledge and requirements. By clicking on the three dots on the right corner, of each field, options for editing and removing are available. To reorganize items, simply drag and drop them. See the edition of the checkbox for a more appropriate label:

The HTML field type editor is a rich text editor to give more flexibility to the user. There is a whole set of components to be used into the form creation. Also, if the user adds new variables or wants to remove them, they will be displayed in the “Model Fields” tab to be used dragged into the form is necessary.

And this is how, after three minutes, a whole new reusable form got created without much coding:

In order to test it, the project needs to be deployed to kie server. Once deployed, when the task is activated, the results can be visualized via business central when clicking on the task. The same form could be embedded into a custom client application.

If you want more information about the form modeler, including a running sample, please refer to this blog post: https://karinavarela.me/2020/02/05/jbpm-form-modeler/

The form can be obtained in two ways:

XML format with plain details:

For process form: GET /server/containers/{containerId}/forms/processes/{processId}
For task form: GET /server/containers/{containerId}/forms/tasks/{taskInstanceId}

Rendered format

For process forms: GET /server/containers/{containerId}/forms/processes/{processId}/content
For case forms: GET /server/containers/{containerId}/forms/cases/{caseDefId}/content
For task forms: GET /server/containers/{containerId}/forms/tasks/{taskInstanceId}/content

This blog post is part of the fourth section of the jBPM Getting started series:

Effective modeling, Integration and Delivery.