Configure task assign management using OptaPlanner

Environment

• OS: Linux Fedora 32
• RHPAM 7.11.1
• JBoss EAP 7.3.7

Install and configure the environment

To execute the KIE Server Task Assigning we need to install run two Kie Servers, one dedicated to Process Runtime and another to Planning

We will use the folders runtime and planning as path location to install our environment.

Process Runtime configuration

For this tutorial, we will use a complete installation of the RHPAM 7.11.1, including the Kie Server and the Business Central in a typical configuration.

Install RHPAM

First, we need the EAP installed in the runtime folder.

To install the RHPAM using the installer jar, follow the steps below

NOTE: To follow these steps assume that you downloaded the rhpam-installer-7.11.1.jar in downloads folder $HOME/Downloads

1. Run the installer

   $ java -jar $HOME/Downloads/rhpam-installer-7.11.1.jar
   

2. Accept the terms of use

3. Put the path to runtime EAP installation (e.g. /home/roribeir/rhpam-planning/runtime)

4. Keep Business Central and Kie Server marked to install

5. Create a user and password and keep admin, kie-server, and rest-all marked (E.g. user=rhpamAdmin password=redhat#1)

6. Finish the installation, next, next, next, and done.

Define the standalone file

The RHPAM need the standalone-full.xml to work correctly, to avoid passing this configuration all times we start the server (./standalone.sh -c standalone-full.xml), go to change the default standalone configuration file

1. Go to $RUNTIME/standalone/configuration where $RUNTIME is the path to the EAP installation

2. Run the commands to rename the default standalone and copy the standalone full to default one.

   $ cp standalone.xml standalone.xml.OLD
   $ cp standalone-full.xml standalone.xml
   

Include required property

To make the runtime kie server work with the planning kie server we will include the property org.kie.server.taskAssigning.runtime.ext.disabled to the standalone file

1. Go to $RUNTIME/standalone/configuration

2. Open the standalone.xml file

   $ vim standalone.xml
   

3. Go to the properties block and include the line “““

   $ vim standalone.xml
   

   
       ...output ommited...
       
   
   

Planning configuration

The Planning needs only a Kie Server running, we will use the same rhpam installer used in the Runtime installation to configuring it.

Install Kie Server

First, we need the EAP installed in the planning folder.

To install the RHPAM using the installer jar, follow the steps below

1. Run the installer

   $ java -jar $HOME/Downloads/rhpam-installer-7.11.1.jar
   

2. Accept the terms of use

3. Put the path to runtime EAP installation (e.g. /home/roribeir/rhpam-planning/planning)

4. Keep only Kie Server marked to install

5. Create a user and password and keep admin, kie-server, and rest-all marked (E.g. user=rhpamAdmin password=redhat#1)
6. Finish the installation, next, next, next, and done.

Define the standalone file

The RHPAM need the standalone-full.xml to work correctly, to avoid passing this configuration all times we start the server (./standalone.sh -c standalone-full.xml), go to change the default standalone configuration file

1. Go to $PLANNING/standalone/configuration where $PLANNING is the path to the EAP installation

2. Run the commands to rename the default standalone and copy the standalone full to default one.

   $ cp standalone.xml standalone.xml.OLD
   $ cp standalone-full.xml standalone.xml
   

Define port to run the planning

The default port of the EAP is 8080, but we can’t run two or more EAP instances in the same machine with the same port. As the Runtime will use the default port here we will change the port for the Planning EAP

1. Open the standalone.xml file in a text editor

   $ vim standalone.xml
   

2. Go to the end of the file and change the port-offset from 0 to 100

Include required properties

To make the planning kie server work with the runtime kie server we will include some properties as listed bellow

To include these properties in the standalone follow the steps below

1. Go to $PLANNING/standalone/configuration

2. Open the standalone.xml file

   $ vim standalone.xml
   

3. Go to the properties block and include the required lines. The system-properties will be as below

   $ vim standalone.xml
   

Properties that deserve attention

Some of these properties define important things about the task assigned and will be explained here

• org.kie.server.services.taskAssigning.core.model.planningUserId

  Define a user to assign all tasks that have no user that met the required skills. In summary, if no the planner can’t find a valid user to assign a task, the task will be assigned to the user-defined in this property

• org.kie.server.taskAssigning.publishWindowSize

  Define the maximum number of tasks assigned at the same time to users.

Disable other extensions from Kie Server

To the Planning work properly, all other Kie Server extensions must be disabled. To do that, include the following properties in the planning standalone file:

Configuring the SimpleUserSystemService

The UserSystemService is the application that will run in the planning to do the task assignments. It implements the UserSystemService API, but for this tutorial, we will use a simple one provided with the documentation.

This UserSystemService loads the user definitions, skills, and affinities from Java properties file in the same format used by EAP, eg:

katy=analyst,HR
john=IT,Developer

UserSystemService properties

The UserSystemService could be used in two ways, as the container, kjar, based, and path-based. We will cover only the path based here. To use this configuration, including the following properties to the planning standalone file

Create required files

In this example, we will use two files, the roles.properties and the skills.properties each will be placed at the same path jboss.server.config.dir that is, by default, $PLANNING/standalone/configuration

1. Create the roles.properties and include the content:

   rhpamAdmin=admin,kie-server,rest-all
   katy=rest-all,kie-server,admin,HR,analyst
   john=admin,rest-all,kie-server,IT,Developer
   bill=admin,rest-all,kie-server,manager,HR
   sarah=admin,rest-all,kie-server,IT,Consultant
   

2. Create the skills.properties and include the content:

   katy=analyst,HR
   bill=manager,HR
   john=IT,Developer
   sarah=IT,Consultant
   

Create required users

We need to create the four users in the Runtime environment. Follow the steps below to create it

1. Go to $RUNTIME/bin/

2. Run the commands below

   $ ./add-user.sh -a katy redhat#1 -g 'admin,rest-all,kie-server'
   $ ./add-user.sh -a bill redhat#1 -g 'admin,rest-all,kie-server'
   $ ./add-user.sh -a sarah redhat#1 -g 'admin,rest-all,kie-server'
   $ ./add-user.sh -a john redhat#1 -g 'admin,rest-all,kie-server'
   

   The output will be like this

   Updated user 'katy' to file '/home/roribeir/rhpam-planning/runtime/standalone/configuration/application-users.properties'
   Updated user 'katy' to file '/home/roribeir/rhpam-planning/runtime/domain/configuration/application-users.properties'
   Updated user 'katy' with groups admin,rest-all,kie-server to file '/home/roribeir/rhpam-planning/runtime/standalone/configuration/application-roles.properties'
   Updated user 'katy' with groups admin,rest-all,kie-server to file '/home/roribeir/rhpam-planning/runtime/domain/configuration/application-roles.properties'
   

It creates the users katy, john, bill, and sarah all with the same password redhat#1

Create the example project

To test the task assignment we will use a simple project with only one process that will represent a new hire interview with two steps, one for HR interview and another for Tech interview.

With the rhpamAdmin user logged, create a new project, download the BPMN file in the references [2] and import it to the project. It has the design and all the needed configurations. Here we will cover the most important configuration to you can reproduce it on any project

In this process we will not use assign by Actors, we will use only skills to assign the tasks, and to do that we need to create a Process Variable named variableWithSkills with type String and map these variable in the user tasks:

The skills variable in the Data Inputs and Assignments will be extracted and converted to a Label by the DefaultTaskDataSkillsValueExtractor. So, when you input a list string "," separated like: "HR,manager", the extractor will convert it in a label as skill: {HR, manager}.

Using the project

After creating the project, deploy it and we will start to create process instances to see the task assign working.

When we start a new instance of this process, we will pass the skill needed to the first user task, HR Interview, the required skill is the HR.

As we have two users with the skill HR, we need to check what user receives the task generated, in this case, the user as katy. The next step is to approve the task and pass the new skill, IT, required to the next user task.

Test can be done

To test the Task Assign function and see it working, you can create a lot of process instances, passing the HR skill to see that each time the users katy and bill will have two tasks reserved all the time and all other tasks will be in Ready status while waiting one of the users complete one task. You can test the same with the IT skills to tech interview.

Another test is to include more skills in one task, eg. star a new process with the skills "HR,manager" and see that the task will only be assigned to bill. The same is true if you use IT,Developer or only Developer

References

1. KIE Server Task Assigning – docs.jboss.org/jbpm/release/7.39.0.Final/jbpm-docs/html_single/#_ch.taskAssigning
2. newHireProcess.bpmn
3. GitHub repository of the project – newHire