KIE Server Task Assigning

Introduction to business processes

Business process management systems (BPMS) products such as jBPM have the ability to model and execute multiple business processes. A business process is typically composed of nodes such as events, gateways, and tasks that are connected to each other for defining the process flow. Every type of node has a specific semantic and is instantiated by the process runtime engine when a process instance is executed. Business processes that require human interaction are modelled by using human task nodes. The following image shows a process where three tasks require human interaction:

Example process It is usual for a system that executes several process instances to have many human task instances that are waiting for an external human action.

Default task list This is referred to as task assigning integration.

BPM standard task assigning

In general, business process runtime engines assign human tasks to users on a group basis. The target audience is usually included as part of the human task configuration. The following image shows how the Review Purchase Order human task is configured with the PurchaseDepartment group:

Human task configuration At runtime, every time a new instance of the Review Purchase Order task is created it is automatically assigned to the PurchaseDepartment group with the status Ready. This makes the task automatically available to all users that belong to the group. All users in the group see it on their respective Task Inbox but none are the actual owner or responsible for the task. To be able to work with a particular task, a user must execute the claim operation to reserve the task for that user. The following image shows an example of the claim operation execution for the task #152:

User claims a task When the claim operation is executed, the task status is changed to Reserved and the task is assigned to the claiming user. In the preceding example, the claimer of the task is the wbadmin user. After the user claims the task, he is known as the task “actual owner”.

Task claimed by wbadmin Although this is the standard procedure for most BPMS products, it is not flexible enough for all use cases. For example, this procedure does not work well with scenarios where an optimal distribution of a huge set of tasks between users by given criteria is required. In these cases, users usually find a large list of tasks up-front but do not have the knowledge to claim and execute them in the best way. All of the configuration parameters that are defined in the next topics are defined through the Java system properties. In Wildfly and Red Hat Enterprise Application Server (EAP) installations, these parameters are usually configured in the <system-properties> section of the selected configuration file, for example:

<server xmlns="urn:jboss:domain:8.0">
...
    <system-properties>
        ...
        <property name="org.kie.server.taskAssigning.runtime.ext.disabled" value="false"/>
        ...
    </system-properties>
...
</server>

You can also use other methods of setting system properties, for example passing JVM parameters on the command line:

-Dorg.kie.server.taskAssigning.runtime.ext.disabled=false

It is recommended to use the same configuration method for all KIE Server required parameters.

Process Runtime kie-server configuration

The following table shows the only parameter that must be configured in all of the Process Runtime kie-servers in the target topology.

Parameter	Requirement	Description
org.kie.server.taskAssigning.runtime.ext.disabled	Not required	The default value is “true”, meaning that the task assigning integration is always disabled. Must be set to “false” for making it work.

Process Runtime kie-server Wildfly/EAP configuration example

<server>
...
    <system-properties>
       ...
        <property name="org.kie.server.taskAssigning.runtime.ext.disabled" value="false"/>
       ...
    </system-properties>
...
</server>

Planning kie-server configuration

The following topics explain the parameters that you must configure in the Planning kie-server. Whatever the target topology is, only one instance of this server will exist.

The parameters tagged as “Required” must be set only in cases where the task assigning integration is enabled. Some of them have a default value that automatically applies when not set.

Global configuration parameters

Parameter	Requirement	Description
org.kie.server.taskAssigning.planning.ext.disabled	Not required	The default value is “true”, meaning that the task assigning integration is always disabled. Must be set to “false” for making it work.
org.kie.server.services.taskAssigning.core.model.planningUserId	Required	The default value is “planninguser”. This value configures the user for being assigned with the tasks that no other user in the system can be assigned to. For example, if a task has a required skill “astronaut” and no user can be found with this skill, it will be assigned to the planninguser. But it is not only restricted to skills, another example might be a task configured for a users group “Finance”. If no user exists in that group it will be assigned to the planning user. It is strongly recommended that the planning user has the required human tasks administration grants in all of the target Process Runtime kie-servers. By doing so it can easily proceed to track and eventually re-assign the tasks that couldn’t be managed by the tasks assigning integration. Note: it is recommended to keep this name.
org.kie.server.taskAssigning.processRuntime.url	Required	The default value is http://localhost:8080/kie-server/services/rest/server This value configures the URL for connecting to the Process Runtime kie-server rest services. In a clustered environment a list of ”\|” separated urls can be used for doing load balancing between the different Process Runtime kie-servers.
org.kie.server.taskAssigning.processRuntime.user	Required	The default value is wbadmin This value configures the user id for connecting to the Process Runtime kie-server. In a clustered environment it must exist in all of the configured target servers. The configured user must belong to the human tasks administration group. This group is usually found by looking at the target Process Runtime kie-server configuration parameter: `<property name="org.jbpm.ht.admin.group" value="process-admin"/>` Following the example above the configured user must belong to the group “process-admin”
org.kie.server.taskAssigning.processRuntime.pwd	Required	No default value is set. This value configures the password for the user configured in org.kie.server.taskAssigning.processRuntime.user parameter.
org.kie.server.taskAssigning.processRuntime.targetUser	Required	No default value is set. This value configures the user ID used to execute the process runtime operations “on behalf of”, and is usually the same as the value of the org.kie.server.taskAssigning.processRuntime.user parameter
org.kie.server.taskAssigning.processRuntime.key.alias	Not Required	No default value is set. This parameter can be used in cases where it is required to get the runtime user password from the KIE Server keystore and represents the alias for locating it.
org.kie.server.taskAssigning.processRuntime.key.pwd	Not Required	No default value is set. This parameter must be used in cases where the runtime user password is stored in the KIE Server keystore, and represents the password for accessing the corresponding keystore entry.
kie.keystore.keyStoreURL	Not Required	No default value is set. URL for the JCEKS that you want to use, for example file:///home/kie/keystores/keystore.jceks
kie.keystore.keyStorePwd	Not Required	No default value is set. Password for the JCEKS
org.kie.server.taskAssigning.processRuntime.timeout	Not Required	The default value is 90000. This value configures the timeout in milliseconds for the operation invocations on the Process runtime kie-server.
org.kie.server.taskAssigning.runtimeDelegate.pageSize	Not Required	The default value is 3000. This value configures the page size for the paged queries. The default value is good for most scenarios and it’s not recommended to be modified unless specific fine tunings are required.
org.kie.server.taskAssigning.solutionSyncInterval	Required	The default value is “PT2S” (two seconds). This value configures the time interval for the tasks information refreshing from the Process Runtime kie-server. The accepted format is based on the ISO-8601 duration format PnDTnHnMn.nS with days considered to be exactly 24 hours. For example: “PT1.500S”: configures 1500 milliseconds. ”PT0.500S”: configures 500 milliseconds. ”PT3S”: configures 3000 milliseconds.
org.kie.server.taskAssigning.solutionSyncQueriesShift	Required	The default value is “PT10M” This value configures a timeshift for adjusting the tasks information refreshing queries. In most cases it should never be modified and should not be less than PT5M (five minutes). The accepted format is based on the ISO-8601 duration format PnDTnHnMn.nS with days considered to be exactly 24 hours.
org.kie.server.taskAssigning.publishWindowSize	Required	The default value is 2. This value configures the maximum amount of tasks per user that will be assigned to it in the Process Runtime kie-server when an optimized plan is calculated. See “published tasks” This value should usually be low, 2, 3, or 4, since it is expected that the tasks will be assigned to the users according to an optimized plan that is changing over time. High values might lead to the BPM Standard task assigning which could make the tasks assigning integration senseless.
org.kie.server.taskAssigning.usersSyncInterval	Required	The default value is “PT2H” (two hours) This value configures the time interval for the user’s information refreshing from the UserSystemService integration component. The accepted format is based on the ISO-8601 duration format PnDTnHnMn.nS with days considered to be exactly 24 hours.
org.kie.server.taskAssigning.waitForImprovedSolutionDuration	Not Required	The default value is “PT0S” (no wait) This value configures the time interval to improve a solution before the corresponding optimized plan is sent to the Process Runtime kie-server. Because this wait time is applied every time a new set of changes is processed it should usually be short, for example “PT0.500” (500 milliseconds). Use it in cases when early improvements are desired. The accepted format is based on the ISO-8601 duration format PnDTnHnMn.nS with days considered to be exactly 24 hours.
org.kie.server.taskAssigning.improveSolutionOnBackgroundDuration	Not Required	The default value is “PT1M” (one minute) This value configures the time interval for doing a background optimization of the current solution after the corresponding optimized plan is sent to the Process Runtime kie-server. In situations where no changes in the processes are produced and a better solution is calculated during that period, the new optimized plan is automatically sent to the Process Runtime kie-server. The accepted format is based on the ISO-8601 duration format PnDTnHnMn.nS with days considered to be exactly 24 hours.

Planning kie-server Wildfly/EAP configuration example

Below is an extract of the task assigning configuration parameters for a Wildfly/EAP server.

<server>
...
<system-properties>
...
  <!-- the following kie-server extensions must be disabled in the Planning kie-server -->
  <property name="org.jbpm.server.ext.disabled" value="true"/>
  <property name="org.jbpm.ui.server.ext.disabled" value="true"/>
  <property name="org.jbpm.case.server.ext.disabled" value="true"/>
  <property name="org.kie.dmn.server.ext.disabled" value="true"/>
  <property name="org.kie.swagger.server.ext.disabled" value="true"/>

  <!-- enable the TaskAssigningPlanningKieServerExtension -->
  <property name="org.kie.server.taskAssigning.planning.ext.disabled" value="false"/>

  <property name="org.kie.server.taskAssigning.processRuntime.url"
            value="http://localhost:8080/kie-server/services/rest/server"/>
  <property name="org.kie.server.taskAssigning.processRuntime.user" value="wbadmin"/>
  <property name="org.kie.server.taskAssigning.processRuntime.pwd" value="wbadmin"/>
  <property name="org.kie.server.taskAssigning.processRuntime.targetUser" value="wbadmin"/>
  <property name="org.kie.server.taskAssigning.solutionSyncInterval" value="PT2S"/>

  <!-- example of a Solver configuration based on a user provided kjar -->
  <!--
  <property name="org.kie.server.taskAssigning.solver.configResource" value="org/kie/server/services/taskassigning/solver/taskAssigningDefaultSolverConfig.xml"/>
  <property name="org.kie.server.taskAssigning.solver.container.id"
            value="kie-server-task-assigning-default-planner-kjar-container"/>
  <property name="org.kie.server.taskAssigning.solver.container.groupId" value="org.kie.server"/>
  <property name="org.kie.server.taskAssigning.solver.container.artifactId"
            value="kie-server-task-assigning-default-planner-kjar"/>
  <property name="org.kie.server.taskAssigning.solver.container.version" value="X.XX.XXX"/>
  -->

  <!-- default SimpleUserSystemService configuration -->
  <property name="org.kie.server.taskAssigning.userSystem.name" value="SimpleUserSystemService"/>
  <property name="org.kie.server.services.taskassigning.user.system.simple.users"
            value="${jboss.server.config.dir}/roles.properties"/>

  <!-- un-comment and configure if skills information will be loaded -->
  <!--
  <property name="org.kie.server.services.taskassigning.user.system.simple.skills"
            value="${jboss.server.config.dir}/skills.properties"/>
  -->

  <!-- un-comment and configure if affinities information will be loaded -->
  <!--
  <property name="org.kie.server.services.taskassigning.user.system.simple.affinities"
            value="${jboss.server.config.dir}/affinities.properties"/>
  -->
  <!-- end of default SimpleUserSystemService configuration -->

  <!-- example of a UserSystemService configuration based on a user provided kjar -->
  <!--
  <property name="org.kie.server.taskAssigning.userSystem.name"
            value="SimpleUserSystemServiceByKjar"/>
  <property name="org.kie.server.taskAssigning.userSystem.container.id"
            value="task-assigning-user-system-service-simple-by-kjar-container"/>
  <property name="org.kie.server.taskAssigning.userSystem.container.groupId"
            value="org.kie.server"/>
  <property name="org.kie.server.taskAssigning.userSystem.container.artifactId"
            value="kie-server-task-assigning-user-system-simple-kjar"/>
  <property name="org.kie.server.taskAssigning.userSystem.container.version" value="X.XX.XXX"/>
  -->
...
</system-properties>
...
</server>

Spring Boot configuration

When the KIE Server Spring Boot Starter version is used the following configuration parameters are used to configure the task assigning integration. These parameters are usually configured in the corresponding Spring Boot application.properties file. The same statements as for standard KIE Server topologies apply in this case.

Parameter	Requirement	Description
kieserver.taskAssigning.runtime.enabled	Required	Must be set to “true” in order to enable the task assigning integration in the Process Runtime kie-server
kieserver.taskAssigning.planning.enabled	Required	Must be set to “true” in order to enable the task assigning integration in the Planning kie-server
taskassigning.core.model.planningUserId	Required	This value is analogous to the org.kie.server.services.taskAssigning.core.model.planningUserId configuration parameter, see Global configuration parameters
taskassigning.processRuntime.url	Required	This value is analogous to the org.kie.server.taskAssigning.processRuntime.url configuration parameter, see Global configuration parameters
taskassigning.processRuntime.user	Required	This value is analogous to the org.kie.server.taskAssigning.processRuntime.user configuration parameter, see Global configuration parameters
taskassigning.processRuntime.pwd	Required	This value is analogous to the org.kie.server.taskAssigning.processRuntime.pwd configuration parameter, see Global configuration parameters
taskassigning.processRuntime.targetUser	Required	This value is analogous to the org.kie.server.taskAssigning.processRuntime.targetUser configuration parameter, see Global configuration parameters
taskassigning.processRuntime.key.alias	Not Required	This value is analogous to the org.kie.server.taskAssigning.processRuntime.key.alias configuration parameter, see Global configuration parameters
taskassigning.processRuntime.key.pwd	Not Required	This value is analogous to the org.kie.server.taskAssigning.processRuntime.key.pwd configuration parameter, see Global configuration parameters
taskassigning.processRuntime.timeout	Not Required	This value is analogous to the org.kie.server.taskAssigning.processRuntime.timeout configuration parameter, see Global configuration parameters
taskassigning.runtimeDelegate.pageSize	Not Required	This value is analogous to the org.kie.server.taskAssigning.runtimeDelegate.pageSize configuration parameter, see Global configuration parameters
taskassigning.solutionSyncInterval	Required	This value is analogous to the org.kie.server.taskAssigning.solutionSyncInterval configuration parameter, see Global configuration parameters
taskassigning.solutionSyncQueriesShift	Required	This value is analogous to the org.kie.server.taskAssigning.solutionSyncQueriesShift configuration parameter, see Global configuration parameters
taskassigning.publishWindowSize	Required	This value is analogous to the org.kie.server.taskAssigning.publishWindowSize configuration parameter, see Global configuration parameters
taskassigning.usersSyncInterval	Required	This value is analogous to the org.kie.server.taskAssigning.usersSyncInterval configuration parameter, see Global configuration parameters
taskassigning.waitForImprovedSolutionDuration	Not Required	This value is analogous to the org.kie.server.taskAssigning.waitForImprovedSolutionDuration configuration parameter, see Global configuration parameters
taskassigning.improveSolutionOnBackgroundDuration	Not Required	This value is analogous to the org.kie.server.taskAssigning.improveSolutionOnBackgroundDuration configuration parameter, see Global configuration parameters
taskassigning.solver.configResource	Required	This value is analogous to the org.kie.server.taskAssigning.solver.configResource configuration parameter, see Solver configuration parameters
taskassigning.solver.moveThreadCount	Not Required	This value is analogous to the org.kie.server.taskAssigning.solver.moveThreadCount configuration parameter, see Solver configuration parameters
taskassigning.solver.moveThreadBufferSize	Not Required	This value is analogous to the org.kie.server.taskAssigning.solver.moveThreadBufferSize configuration parameter, see Solver configuration parameters
taskassigning.solver.threadFactoryClass	Not Required	This value is analogous to the org.kie.server.taskAssigning.solver.threadFactoryClass configuration parameter, see Solver configuration parameters
taskassigning.solver.container.id	Not Required	This value is analogous to the org.kie.server.taskAssigning.solver.container.id configuration parameter, see Container based solver configuration
taskassigning.solver.container.groupId	Required if the container configuration is activated	This value is analogous to the org.kie.server.taskAssigning.solver.container.groupId configuration parameter, see Container based solver configuration
taskassigning.solver.container.artifactId	Required if the container configuration is activated	This value is analogous to the org.kie.server.taskAssigning.solver.container.artifactId configuration parameter, see Container based solver configuration
taskassigning.solver.container.version	Required if the container configuration is activated	This value is analogous to the org.kie.server.taskAssigning.solver.container.version configuration parameter, see Container based solver configuration
taskassigning.solver.configResource	Required if the container configuration is activated	This value is analogous to the org.kie.server.taskAssigning.solver.configResource configuration parameter, see Container based solver configuration
taskassigning.userSystem.name	Required	This value is analogous to the org.kie.server.taskAssigning.userSystem.name configuration parameter, see UserSystemService configuration
taskassigning.userSystem.container.id	Not Required	This value is analogous to the org.kie.server.taskAssigning.userSystem.container.id configuration parameter, see Container based UserSystemService configuration
taskassigning.userSystem.container.groupId	Required if the container configuration is activated	This value is analogous to the org.kie.server.taskAssigning.userSystem.container.groupId configuration parameter, see Container based UserSystemService configuration
taskassigning.userSystem.container.artifactId	Required if the container configuration is activated	This value is analogous to the org.kie.server.taskAssigning.userSystem.container.artifactId configuration parameter, see Container based UserSystemService configuration
taskassigning.userSystem.container.version	Required if the container configuration is activated	This value is analogous to the org.kie.server.taskAssigning.userSystem.container.version configuration parameter, see Container based UserSystemService configuration
tastaskassigning.userSystem.simple.users	Required if the Simple User System is configured	This value is analogous to the org.kie.server.services.taskassigning.user.system.simple.users configuration parameter, see SimpleUserSystemService
taskassigning.userSystem.simple.skills	Not Required	This value is analogous to the org.kie.server.services.taskassigning.user.system.simple.skills configuration parameter, see SimpleUserSystemService
taskassigning.userSystem.simple.affinities	Not Required	This value is analogous to the org.kie.server.services.taskassigning.user.system.simple.affinities configuration parameter, see SimpleUserSystemService

Default Constraints

The following table gives a high level description of the set of constraints that are included in the task assigning integration. These constraints are used for the construction of the optimized plan, in other words “for determining which tasks should be assigned to whom”. In general a large set of use cases can be covered by using them and no extensions are required, but it is possible to work with a user-provided customized set of constraints if needed, see Container based solver configuration. Optimized solutions construction is made by using a BendableLongScore with two levels of Hard constraints and six levels of Soft constraints. These constraint levels can be customized by following a set of restrictions.

Constraint	Level/Requirement	Description
Required Potential Owner	Hard Constraint 0 (required)	Determines that a task must be assigned to one of its “Potential Owners”, or to the “Planning User” in cases where no “Potential Owners” are found. User provided customizations must always include this constraint as the first level hard constraint. Otherwise the business process semantics won’t be considered by the task assigning integration, i.e., tasks might be assigned to users that are not “Potential Owners” for it. In cases where this constraint is still customized, it must always consider assigning the “Planning User” when no other user fits the customized condition.
Required Skills	Hard Constraint 1	Determines that a task can only be assigned to a user that has all of the task’s configured skills, see Skills and Affinities. If a task has configured skills but no user with all of these skills can be found it’ll be assigned to the “Planning User”. If the task doesn’t have configured skills the constraint has no effect. In cases where this constraint is customized, it must always consider assigning the “Planning User” when no other user fits the customized condition.
PlanningUser assignment	Soft Constraint 0 (required)	Penalizes the “Planning User” assignment. This constraint enforces the minimization of the “Planning User” assignment and ensures it’ll be assigned as the “last available option”. Do not customize or change this constraint.
High level priority	Soft Constraint 1	Enforces the assignment of higher priority tasks first whenever it is possible.
Desired Affinities	Soft Constraint 2	Makes a best effort for assigning tasks according to its configured affinities, see Skills and Affinities If a task has configured affinities, whenever it is possible, a user with the most of them will be picked for its assignment. If the task doesn’t have configured affinities the constraint has no effect.
Minimize makespan	Soft Constraint 3 (required)	Reduce the time to complete all tasks. This constraint must always be included.
Medium level priority	Soft Constraint 4	Medium level priority tasks are assigned after higher priority tasks whenever it is possible.
Low level priority	Soft Constraint 5	Low level priority tasks are assigned last whenever it is possible.

The current TaskAssigningSolution implementation is based on a BendableLongScore scoring function and thus any potential extension of the provided constraints, etc., typically by using a user provided KJAR, will be based on it. However this scoring function as well as the core model classes might change in future releases.

Constraints configuration by using a DRL file

The following example shows the key parts of the DRL file that contains the constraints configurations.

// ############################################################################
// Hard constraints
// ############################################################################

// A task can only be assigned to one of its potential owners or to the PlanningUser
rule "Required Potential Owner"
   when
       $task : Task(user != null, !TaskAssigningConditions.userMeetsPotentialOwnerOrPlanningUserCondition($task, user))
   then
       scoreHolder.addHardConstraintMatch(kcontext, 0, -1);
end

// A task with defined skills can only be assigned to users that has all of the of them or to the PlanningUser
rule "Required Skills"
   when
       $task : Task(user != null, !TaskAssigningConditions.userMeetsRequiredSkillsOrPlanningUserCondition($task, user))
   then
       scoreHolder.addHardConstraintMatch(kcontext, 1, -1);
end

// ############################################################################
// Soft constraints
// ############################################################################

// First level soft constraint for penalizing the assignment of the PLANNING_USER.
rule "PlanningUser assignment"
   when
       Task(user != null, ModelConstants.IS_PLANNING_USER.test(user.getEntityId()))
   then
       // a penalization is added each time the PLANNING_USER is assigned.
       scoreHolder.addSoftConstraintMatch(kcontext, 0, -1);
end

// Second level soft constraint for penalizing the assignment of the PLANNING_USER.
rule "High level priority"
   when
       $task : Task(user != null, PriorityHelper.isHighLevel(priority))
   then
       scoreHolder.addSoftConstraintMatch(kcontext, 1, PriorityHelper.calculateWeightedPenalty($task.getPriority(), $task.getEndTimeInMinutes()));
end


// Third level soft constraint, when a task has defined affinities consider assigning users that match
// the most of them as possible.
rule "Desired Affinities"
   when
       $task : Task(user != null, user.isEnabled())
   then
       scoreHolder.addSoftConstraintMatch(kcontext, 2, TaskHelper.countMatchingLabels($task, $task.getUser(), DefaultLabels.AFFINITIES.name()));
end

// Fourth level soft constraint.
rule "Minimize makespan (starting with the latest ending user first)"
   when
       Task(user != null, nextTask == null, $endTimeInMinutes : endTimeInMinutes)
   then
       scoreHolder.addSoftConstraintMatch(kcontext, 3, - ($endTimeInMinutes * $endTimeInMinutes));
end

// Fifth level soft constraint.
rule "Medium level priority"
   when
       $task : Task(user != null, PriorityHelper.isMediumLevel(priority))
   then
       scoreHolder.addSoftConstraintMatch(kcontext, 4, PriorityHelper.calculateWeightedPenalty($task.getPriority(), $task.getEndTimeInMinutes()));
end

// Sixth level soft constraint.
rule "Low level priority"
   when
       $task : Task(user != null, PriorityHelper.isLowLevel(priority))
   then
       scoreHolder.addSoftConstraintMatch(kcontext, 5, PriorityHelper.calculateWeightedPenalty($task.getPriority(), $task.getEndTimeInMinutes()));
end

The current default DRL might change in future versions and thus cannot be considered as part of the product public API. Any potential customization of the provided constraints might use this DRL as a starting point or could also use other mechanisms such as the constraints streams for implementing them.

Skills and Affinities

The use of skills and affinities implements the ability of declaring business related data for being considered by the default provided constraints or any other user defined ones. This is a fine grained decision mechanism that you can use on top of the groups-based assignment semantics defined in the business process. Internally, this mechanism is based on the ability to label the human tasks generated by the business processes runtime and the users information. Labeling mechanism The following procedure shows how the labeling mechanism converts information in human tasks and users information to labels:

Tasks Labeling

Any human task is created in the processes runtime.
When the new task is detected by the task assigning solution refreshing mechanism, a set of LabelValueExtractors is applied.
These LabelValueExtractors can transform any piece of information in the human task or user into a label.
The default constraints consider these labels.

In the preceding example, the following labels are produced:

The input data “skills”, with the value “skill1, skill2” resulted in the label SKILLS with the following set of values {“skill1”, “skill2”}
The input data “affinities” with the value “affinity1” resulted in the label AFFINITIES with the following set of values {“affinity1”}

Task labels are calculated only the first time the task is identified by the task assigning integration and can use any of the information present in the task.

User labeling works in a similar way:

Users Labeling

Default HumanTask and User LabelValueExtractors

Four label value extractors are provided to manage the SKILLS and AFFINITIES labels.

Extractor Name	Description
DefaultTaskDataSkillsValueExtractor	Processes the human task “skills” input value as a string of comma separated values, and creates a java `Set<Object>` with tokenized String values. The resulting set is assigned to the label SKILLS. For example, the “skills” input value “english,finance” is extracted as a set with the values {“english”, “finance”} and assigned to the label with name SKILLS. By default extraction can be customized by using the following system property for defining the task input value from where the SKILLS will be extracted. For example: org.kie.server.services.taskassigning.planning.data.DefaultTaskDataSkillsValueExtractor.skills=someOtherName
DefaultTaskDataAffinitiesValueExtractor	Processes the human task “affinities” input value, as a string of comma separated values, and creates a java `Set<Object>` with tokenized String values. The resulting set is assigned to the label AFFINITIES. For example, the “affinities” input value “news,history” is extracted as a set with the values {“news”, “history”} and assigned to the label with name AFFINITIES. By default extraction can be customized by using the following system property for defining the task input value from where the AFFINITIES will be extracted. For example: org.kie.server.services.taskassigning.planning.data.DefaultTaskDataAffinitiesValueExtractor.affinities=someOtherName
DefaultUserSkillsValueExtractor	Analogous to the DefaultTaskDataSkillsValueExtractor. By default extraction can be customized by using the following system property for defining the user attribute from where the SKILLS will be extracted. For example: org.kie.server.services.taskassigning.planning.data.DefaultUserSkillsValueExtractor.skills=someOtherName
DefaultUserAffinitiesValueExtractor	Analogous to the DefaultTaskDataAffinitiesValueExtractor. By default extraction can be customized by using the following system property for defining the user attribute from where the AFFINITIES will be extracted. For example: org.kie.server.services.taskassigning.planning.data.DefaultUserAffinitiesValueExtractor.affinities=someOtherName

The current core model classes like the TaskAssigningSolution, Task and User might change in future releases.

Linking the human tasks inputs with the labels

A simple approach for labeling tasks with business related information is implemented using the task inputs configuration. The following image shows an example of such a configuration.

Skills and affinities configuration The example above links the process variable “variableWithTheSkills” with the task input name “skills”, and the corresponding value will be processed by the “DefaultTaskDataSkillsValueExtractor” and automatically associated with the label name SKILLS. This mechanism can be used for any other user provided LabelValueExtractor.

Custom extractors

Installations that require the definition of customized LabelValueExtractors can add them by providing their implementations in the customized KJARs with the UserSystemIntegration implementation or the Solver configuration.

Add a component in the specified KJAR that implements the following interface: org.kie.server.api.model.taskassigning.data.LabelValueExtractor Note: Ensure that the following dependency is added to the given KJAR:

<dependency>
  <groupId>org.kie.server</groupId>
  <artifactId>kie-server-api</artifactId>
  <version>corresponding version</version>
  <scope>provided</scope>
</dependency>

Declare the component implementation by using the Java standard service provider mechanism in the following resource: project_home/src/main/resources/META-INF/services/org.kie.server.api.model.taskassigning.data.LabelValueExtractor

When configured, the LabelValueExtractor will be processed accordingly. The following example shows a custom LabelValueExtractor:

import org.kie.server.api.model.taskassigning.data.LabelValueExtractor;
import org.kie.server.services.taskassigning.user.system.api.User;

public class UserExampleValueExtractor implements LabelValueExtractor<User> {

   public Class<User> getType() {
       // consider this extractor for processing users information.
       return org.kie.server.services.taskassigning.user.system.api.User.class;
   }

   public String getLabelName() {
       return "PASSPORT";
   }

   public int getPriority() {
       return 1;
   }

   public Set<Object> extract(User source) {
       Map<String, Object> attributes = source.getAttributes();
       Object value = attributes != null ? attributes.get("passport_number") : null;
       return value != null ? new HashSet<Object>(Collections.singleton(value)) : null;
   }
}

Ensure that the following dependency is added to the specified KJAR:

<dependency>
  <groupId>org.kie.server</groupId>
  <artifactId>kie-server-services-task-assigning-user-system-api</artifactId>
  <version>corresponding version</version>
  <scope>provided</scope>
</dependency>

Extractors for processing the human tasks information must use the class org.kie.server.api.model.taskassigning.TaskData as source type.

The current core model classes like the TaskAssigningSolution, Task and User might change in future releases.

Integration alternatives

System integrators usually consume the human tasks available in the Process Runtime kie-server for different purposes. One example is the Business Central “Task Inbox”. In this case, Business Central acts as an “integrator” which means that the human tasks are consumed from the Process Runtime kie-server by using the kie-server queries APIs and applying different filtering criterias. Finally these tasks are listed in the “Task Inbox” UI, etc. In this way, Business Central is decoupled from the Process Runtime kie-server, etc. The next topics present a set of queries similar to queries used by the Business Central “Task Inbox”. These queries might facilitate integrations in cases where the task assigning integration is enabled.

Task Assigning Human Tasks Query

This query facilitates the consumption of the available human tasks. The task can integrate additional information depending on the query variant. It is up to the “integrator” to select the query variant that best supports its needs.

Filtering parameters

The available filtering parameters are defined in the following kie-server-api enums:

org.kie.server.api.model.definition.TaskField
org.kie.server.api.model.taskassigning.PlanningTaskField

Both classes are found in the following maven artifact:

<dependency>
    <groupId>org.kie.server</groupId>
    <artifactId>kie-server-api</artifactId>
</dependency>

The following table shows the parameter name and the expected type.

Parameter	Type	Description
ACTIVATIONTIME	Date	Time when this task was activated.
ACTUALOWNER	String	Actual owner assigned to this task - only set when task is claimed.
CREATEDBY	String	User who created this task.
CREATEDON	Date	Date when task was created.
DEPLOYMENTID	String	Deployment id this task is part of, typically the KIE Server container.
DESCRIPTION	String	Description of the task if any.
DUEDATE	Date	Due date set on this task if any.
NAME	String	Name of the task.
PARENTID	Long	Parent task id if any.
PRIORITY	Integer	Priority of the task.
PROCESSID	String	Process definition id that this task belongs to.
PROCESSINSTANCEID	Long	Process instance id that this task is associated with.
PROCESSSESSIONID	Long	KieSession id used to create this task.
STATUS	String	Current status of the task.
TASKID	Long	Identifier of task.
WORKITEMID	Long	Identifier of work item assigned on process side to this task id.
PTTASKID	Long	Same value as TASKID.
ASSIGNEDUSER	String	Same value as the ACTUALOWNER for published tasks.
PUBLISHED	Integer	Indicates if the task is published. For example “published = 1” can be used as filtering criteria in cases of filtering by the task that are currently assigned by the task assigning integration.

Querying the human tasks as TaskData instances

This query execution variant enables getting the result values as instances of:

org.kie.server.api.model.taskassigning.TaskData

The following example shows how to use this variant: Example 1)

// Create the kie-server query services client.
QueryServicesClient queryServices = createQueryServicesClient();

// Set the filtering and ordering criteria and consider only the currently published tasks.
QueryFilterSpec filter = new QueryFilterSpecBuilder()
    .equalsTo(TaskField.STATUS.toString(), "Reserved", "InProgress", "Completed")
    .equalsTo(PlanningTaskField.PUBLISHED.toString(), 1)
    .oderBy(TaskField.TASKID.toString(), true)
    .get();

// Execute the query
List<TaskData> result = queryServices.query(TaskAssigningQueries.JBPM_HUMAN_TASKS_QUERY,
                                            TaskAssigningQueries.TASK_DATA_QUERY_MAPPER,
                                            filter,
                                            0,    // staring page
                                            30,   // page size
                                            TaskData.class);

In this case, only the tasks currently assigned by the task assigning integration will be considered. This is the usual scenario when task assigning integration is enabled, because it is expected that the tasks are consumed and executed according to the generated planning.

The task inputs and potential owners are not loaded by this query.

Example 2)

// Create the kie-server query services client.
QueryServicesClient queryServices = createQueryServicesClient();

// Set the filtering and ordering criteria and consider all of the tasks.
QueryFilterSpec filter = new QueryFilterSpecBuilder()
    .equalsTo(TaskField.STATUS.toString(), "Ready”, Reserved", "InProgress", "Completed")
    .oderBy(TaskField.TASKID.toString(), true)
    .get();

// Execute the query
List<TaskData> result = queryServices.query(TaskAssigningQueries.JBPM_HUMAN_TASKS_QUERY,
                                            TaskAssigningQueries.TASK_DATA_QUERY_MAPPER,
                                            filter,
                                            0,    // staring page
                                            30,   // page size
                                            TaskData.class);

In this case all of the tasks will be considered but only the tasks assigned by the task assigning integration will have the TaskData.planningTask filled. It means that non-assigned tasks or tasks not yet managed by the task assigning integration might be included in the results. This alternative facilitates a more advanced processing of the “potential” tasks, however it is strongly encouraged to make available to the users only the tasks that are currently assigned by the task assigning integration, i.e. the ones with TaskData.planningTask != null, otherwise the integration becomes senseless.

The task inputs and potential owners are not loaded by this query.

See KIE Server API documentation for more information on how to create the KIE Server clients and the query API general functioning.

Examples

Credit dispute process

The following credit dispute process example is intended to show a simple use case where you can use the “skills” configuration to influence the way tasks are assigned according to the solver constraints and the process data.

Credit dispute process

Process start

When the process starts, the user is asked to complete the information in the following image. In particular, the credit card brand for which the dispute is related to and the preferred language for receiving the process notifications are requested. This information is used for assigning the process tasks.

Start credit dispute process form

Process configuration

The following image shows the process variables that are used for holding the card brand and language respectively.

Credit dispute process variables The process start form populates these variables with the user inputs.

Resolve dispute task configuration

The following image shows the ResolveDispute task configuration, which establishes that the task input parameter skills is assigned with the value of the process variable cardType.

Notify customer task configuration

The following image shows the NotifyCustomer task configuration, which establishes that the task input parameter skills is assigned with the value of the process variable language.

Process execution (example users)

Let’s assume that the following user configurations are used for executing the process. users.properties file:

john=analyst,admin,user,Accounting,PM,ClientRelations
mary=analyst,admin,user,ClientRelations
katy=analyst,admin,user,HR,CreditAnalyst
maciek=admin,analyst,user,PM,HR,CreditAnalyst

skills.properties file:

john=ES,EN                     (has skills in the Spanish and English languages)
mary=ZH                        (has skills in the Chinese language)
katy=CITI,MASTER               (has skills in the CITI and MASTER cards)
maciek=VISA,AMERICAN_EXPRESS   (has skills in the VISA and AMERICAN EXPRESS cards)

Process execution (example instances)

With the preceding configurations the following execution scenarios are expected: Process instance #1:

Start process

Start credit dispute process instance #1

ResolveDispute task

ResolveDisputeTaskForProcessInstance1WasCreated

Resolve dispute task for process instance #1 The ResolveDispute task is assigned to the user maciek since it requires VISA skills.

NotifyCustomer task

NotifyCustomerTaskForProcessInstance1WasCreated

Notify customer task for process instance #1 When the ResolveDispute task is completed, a new task NotifyCustomer is created and assigned to the user john because that task requires skills in Spanish. Process instance #2:

Start process

Start credit dispute process instance #2

ResolveDispute task

ResolveDisputeTaskForProcessInstance2WasCreated

Resolve dispute task for process instance #2 The ResolveDispute task is assigned to the user katy since it requires CITI skills.

NotifyCustomer task

NotifyCustomerTaskForProcessInstance2WasCreated

Notify customer task for process instance #2 When the ResolveDispute task is completed, a new task NotifyCustomer is created and assigned to the user mary because that task requires skills in Chinese. Process instance #3:

Start process

Start credit dispute process instance #3

ResolveDispute task

ResolveDisputeTaskForProcessInstance3WasCreated

Resolve dispute task for process instance #3 The ResolveDispute task is assigned to the user katy because that task requires skills in the MASTER card.

NotifyCustomer task

NotifyCustomerTaskForProcessInstance3WasCreated

Notify customer task for process instance #3 When the ResolveDispute task is completed, a new task NotifyCustomer is created and assigned to the planninguser because none of the users has the required skills in Hindi. In this case, an external interaction is required to determine the best suited user to complete the task. The planninguser must perform this action by delegating the task.

The planninguser assignment is used to cover edge cases and should not be part of the modelling strategy. In the preceding example, if it is known that no user will have skills in Hindi, a similar but softer constraint can be configured by using affinities.

Customized User System Service

For creating a custom user system service implementation follow these steps:

Create a KJAR project structure
Add the following dependency

<dependency>
  <!-- Kie Server and other product dependencies must use provided scope -->
  <groupId>org.kie.server</groupId>
    <artifactId>kie-server-services-task-assigning-user-system-api</artifactId>
    <version>configure the proper version number aligned with the target kie-server</version>
    <scope>provided</scope>
</dependency>

Provide your UserSystemService implementation, see the following example:

public class MyDBUserSystemService implements UserSystemService {

    private DataSource dataSource;

    public String getName() {
        return "MyDBUserSystemService";
    }

    public void start() {
        String dataSourceName = System.getProperty("org.example.DBUserSystemService.ds",
                                                   "java:jboss/datasources/ExampleDS");
        try {
            InitialContext initialContext = new InitialContext();
            dataSource = (DataSource) initialContext.lookup(dataSourceName);
        } catch (NamingException e) {
             // throw an exception if there are unrecoverable errors that prevent
             // the service to start.
            throw new DBUserSystemServiceException("Unable to find data source under name " +
                                                   dataSourceName, e);
       }
    }

    public void test() throws Exception {
         // test your database queries etc.
    }

    public List<User> findAllUsers() {
        try (Connection conn = dataSource.getConnection()) {
            List<User> myUsers;
            // query the users information from the database.
           return myUsers;
       } catch (SQLException e) {
           throw new DBUserSystemServiceException("An error was produced finding all users: " +
                                                  e.getMessage(), e);
       }
   }

    public User findUser(String userId) {
        if (userId == null) {
            return null;
        }
        try (Connection conn = dataSource.getConnection()) {
            User user;
            // query the user information from the database.
            return user;
        } catch (SQLException e) {
          throw new DBUserSystemServiceException("An error was produced finding user: "+
                                                  e.getMessage(), e);
        }
    }
}

Add the following resource to the project and declare your user system service provider class on it.

src/main/resources/META-INF/services/org.kie.server.services.taskassigning.user.system.api.UserSystemService

org.example.MyDBUserSystemService

Finally, for using it in the Planning kie-server follow these steps:

Build your KJAR and be sure the corresponding maven generated artifact is installed in the maven repository used by your Planning kie-server.
Add a datasource configuration to your Planning kie-server pointing to the target DB (this step is only required for the example above). For example with JNDI name java:jboss/datasources/db-user-system-datasource
Finally add the following items to the Planning kie-server configuration file:

<server>
...
<system-properties>
  <property name="org.kie.server.taskAssigning.userSystem.name"
            value="MyDBUserSystemService" />
  <property name="org.kie.server.taskAssigning.userSystem.container.id"
            value="my-db-user-system-container" />
  <property name="org.kie.server.taskAssigning.userSystem.container.groupId"
            value="your KJARs groupId" />
  <property name="org.kie.server.taskAssigning.userSystem.container.artifactId"
            value="your KJARs artifactId" />
  <property name="org.kie.server.taskAssigning.userSystem.container.version"
            value="your KJARs version number" />
  <property name="org.example.DBUserSystemService.ds"
            value="java:jboss/datasources/db-user-system-datasource" />
</system-properties>
...
</server>

​Introduction to business processes

​BPM standard task assigning

​Process Runtime kie-server configuration

​Process Runtime kie-server Wildfly/EAP configuration example

​Planning kie-server configuration

​Global configuration parameters

​Planning kie-server Wildfly/EAP configuration example

​Spring Boot configuration

​Default Constraints

​Constraints configuration by using a DRL file

​Skills and Affinities

​Default HumanTask and User LabelValueExtractors

​Linking the human tasks inputs with the labels

​Custom extractors

​Integration alternatives

​Task Assigning Human Tasks Query

​Filtering parameters

​Querying the human tasks as TaskData instances

​Examples

​Credit dispute process

​Process start

​Process configuration

​Resolve dispute task configuration

​Notify customer task configuration

​Process execution (example users)

​Process execution (example instances)

​Customized User System Service

Introduction to business processes

BPM standard task assigning

Process Runtime kie-server configuration

Process Runtime kie-server Wildfly/EAP configuration example

Planning kie-server configuration

Global configuration parameters

Planning kie-server Wildfly/EAP configuration example

Spring Boot configuration

Default Constraints

Constraints configuration by using a DRL file

Skills and Affinities

Default HumanTask and User LabelValueExtractors

Linking the human tasks inputs with the labels

Custom extractors

Integration alternatives

Task Assigning Human Tasks Query

Filtering parameters

Querying the human tasks as TaskData instances

Examples

Credit dispute process

Process start

Process configuration

Resolve dispute task configuration

Notify customer task configuration

Process execution (example users)

Process execution (example instances)

Customized User System Service