*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*
***OptaPlanner integrates with jBPM to provide the ability to assign human tasks to users as part of an optimized plan.*** {/* TODO: Review this */}
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.
### OptaPlanner driven task assigning
OptaPlanner and jBPM integration provides the ability to assign the human tasks produced by the process runtime engine between users according to an optimized plan. {/* TODO: Review this */}
Instead of users having to claim the tasks, the tasks are assigned to them.
The following image shows how the tasks are assigned when integration is enabled.
*Assignments produced by OptaPlanner* {/* TODO: Review this */}
The following assignments are shown:
* User katy is assigned to tasks #150 and #148
* User john is assigned to tasks #151 and #149
* Tasks #152, #153, #154, #155, #156 and #157 are left un-assigned (these tasks will be analysed later)
Behind the scenes the following actions took place:
1. All of the available tasks with the status "Ready" were consumed by OptaPlanner. {/* TODO: Review this */}
2. The users john and katy were identified as belonging to the "PurchaseDepartment" users group.
3. The "Review Purchase Order" tasks were identified as defined for the "PurchaseDepartment" group.
4. An optimized plan was calculated and all of the tasks (including the "un-assigned" tasks) were assigned according to their configuration, for example group condition and OptaPlanner optimization rules. The resulting plan stated that: {/* TODO: Review this */}
* Tasks #150 and #148 must be assigned to katy
* Tasks #151 and #149 must be assigned to john
5. OptaPlanner executed the correct process runtime actions to make these assignments happen. Note that the users were not required to execute the "claim" operation. Instead they can focus on completing their respective assigned work and leave the distribution and assignment work to OptaPlanner. {/* TODO: Review this */}
This simple example shows the main concept behind integration:
***"OptaPlanner analyses the available work, calculates an optimized plan, and produces the necessary assignments in the process runtime. Users then rely on that plan and focus on executing their assigned work".*** {/* TODO: Review this */}
**Unassigned tasks**
Usually, a running BPM creates many process instances and many human tasks.
At the same time, users are working and completing these human tasks.
This cycle is repeated over and over.
OptaPlanner addresses this situation by re-calculating the optimized plan when new human tasks are created and/or completed and producing "new assignments" to reflect the new optimized plan. {/* TODO: Review this */}
This is often achieved by combining different "Repeated Planning and Real Time Planning" techniques. For detailed information see the OptaPlanner documentation. {/* TODO: Review this */}
Additionally it might be the case that a plan that was optimal at time N is no longer optimal at time N+1.
For example, a higher priority task has arrived and must be performed as soon as possible.
The direct impact of this situation is that the programmed assignments at time N might change at time N+1, which means that tasks are routinely re-assigned many times when the new optimized plans are calculated. One of OptaPlanner’s strengths is the ability to react to a changing context. {/* TODO: Review this */}
**User impact**
If not controlled, continuous task re-assignment might negatively impact the user’s experience because they might feel that tasks come in and out of their workload randomly.
This situation is present in other types of optimization problems as well and is usually managed by combining different repeated and continuous planning techniques.
For detailed information see the "Repeated Planning" section of the OptaPlanner documentation. {/* TODO: Review this */}
A simple strategy is to introduce the concept of a planning window which is a defined subset of the available work that will not be changed or re-assigned even when new plans are calculated.
Only this subset is available to users. The tasks in the planning window are called published tasks.
The previous example contains a planning window with a size of two. This means that only two tasks from the optimized plan are assigned in the processes runtime for each user so that users have at most two tasks assigned to them and they must focus on those two tasks.
As soon as they start completing these tasks OptaPlanner assigns them additional tasks according to the last optimized plan. {/* TODO: Review this */}
However, internally OptaPlanner maintains information about the best assignments for all of the tasks and not only the published tasks. {/* TODO: Review this */}
This is how the assignments are distributed in the preceding example:
* User katy is assigned to tasks #150 and #148 which belong to the planning window
* User john is assigned to tasks #151 and #149 which belong to the planning window
* The un-assigned tasks are outside of the planning window which means they are assigned only internally by OptaPlanner. As long as these tasks remain unpublished they can be reassigned if necessary during the different optimized plans calculation. {/* TODO: Review this */}
## Configuring the integration
### Product version
The current task assigning integration implementation is provided for the OptaPlanner, jBPM, and KIE Server 7.38.x+ series. {/* TODO: Review this */}
*Simplified architecture*
#### Process Runtime kie-server
This is the KIE Server instance where the business processes execute. In clustered and high-availability configurations, multiple instances can be used.
| 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. |
| 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](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: ` 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. |
| Parameter | Requirement | Description |
|---|---|---|
| org.kie.server.taskAssigning.solver.configResource | Required |
The default value is: "org/kie/server/services/taskassigning/solver/taskAssigningDefaultSolverConfig.xml" This value configures the path to a class-path resource with the Solver configuration. If the resource can’t be found or the configuration is wrong, a controlled error will be added to the Planning kie-server error messages and the task assigning integration won’t be initialized. The KIE Server APIs can be used for querying these error messages and checking the status. |
| org.kie.server.taskAssigning.solver.moveThreadCount | Not Required |
The default value is AUTO. This value configures the solver’s ability of using multithreaded incremental solving. For more information see OptaPlanner documentation. Note: when the container based solver configuration is used this value is not considered, the configuration provided in the KJAR is used instead. |
| org.kie.server.taskAssigning.solver.moveThreadBufferSize | Not Required |
No default value is set. This value power tweaks the number of moves that are selected but won’t be foraged when multithreaded incremental solving is used. Setting it too low reduces performance, but setting it too high too. Unless you’re deeply familiar with the inner workings of multithreaded solving, don’t configure this parameter. For more information see OptaPlanner documentation. Note: when the container based solver configuration is used this value is not considered, the configuration provided in the KJAR is used instead. |
| org.kie.server.taskAssigning.solver.threadFactoryClass | Not Required |
No default value is set. The threadFactoryClass allows you to plug in a custom ThreadFactory for environments where arbitrary thread creation should be avoided. For more information see OptaPlanner documentation. Note: when the container based solver configuration is used this value is not considered, the configuration provided in the KJAR is used instead. |
| Parameter | Requirement | Description |
|---|---|---|
| org.kie.server.taskAssigning.solver.container.id | Not Required |
No default value is set. This value configures the Identifier of the container to use. When set the container based configuration will be activated and the following container related parameters are required. |
| org.kie.server.taskAssigning.solver.container.groupId | Required if the container configuration is activated |
No default value is set. This value configures the Maven groupId of the artifact to use for creating the container when needed. |
| org.kie.server.taskAssigning.solver.container.artifactId | Required if the container configuration is activated |
No default value is set. This value configures the Maven artifactId for the artifact to use for creating the container when needed. |
| org.kie.server.taskAssigning.solver.container.version | Required if the container configuration is activated |
No default value is set. This value configures the Maven version for the artifact to use for creating the container when needed. |
| org.kie.server.taskAssigning.solver.configResource | Required if the container configuration is activated |
This value configures the path to the resource with the Solver configuration in the container class-path. |
| Parameter | Requirement | Description |
|---|---|---|
| org.kie.server.taskAssigning.userSystem.name | Required |
No default value is set. This value configures the name of the UserSystemService provider instance to use. See: UserSystemService.getName() All of the configured providers are loaded from the application class-path and the one that matches with the configured name will be used. A simple user system service implementation is provided, see SimpleUserSystemService. |
| Parameter | Requirement | Description |
|---|---|---|
| org.kie.server.taskAssigning.userSystem.name | Required |
No default value is set. This value configures the name of the UserSystemService provider instance to use. See: UserSystemService.getName() |
| org.kie.server.taskAssigning.userSystem.container.id | Not Required |
No default value is set. This value configures the Identifier of the container to use. When set the container based configuration will be activated and all of the potential UserSystemService providers that might be defined in the container class-path will be considered for selection, additionally to the ones in the application class-path. The following parameters will be required. |
| org.kie.server.taskAssigning.userSystem.container.groupId | Required if the container configuration is activated. |
No default value is set. This value configures the Maven groupId of the artifact to use for creating the container when needed. |
| org.kie.server.taskAssigning.userSystem.container.artifactId | Required if the container configuration is activated. |
No default value is set. This value configures the Maven artifactId for the artifact to use for creating the container when needed. |
| org.kie.server.taskAssigning.userSystem.container.version | Required if the container configuration is activated. |
No default value is set. This value configures the Maven version for the artifact to use for creating the container when needed. |
| Parameter | Requirement | Description |
|---|---|---|
| org.kie.server.taskAssigning.userSystem.name | Required |
Must be the value SimpleUserSystemService |
| org.kie.server.services.taskassigning.user.system.simple.users | Required |
This value configures a Planning kie-server web application accessible path with the user definitions file. For example, in Wildfly/EAP installations it can be like this. `${jboss.server.config.dir}/roles.properties` Note: the configured file must have the same values as the roles.properties files of the Process Runtime kie-servers in the target topology. |
| org.kie.server.services.taskassigning.user.system.simple.skills | Not Required |
This value configures a Planning kie-server web application accessible path with the users skills definitions if desired, see Skills and Affinities. For example, in Wildfly/EAP installations it can be like this. `${jboss.server.config.dir}/skills.properties` Note: the format is analogous to the user definitions file. katy=skill1,skill2 |
| org.kie.server.services.taskassigning.user.system.simple.affinities | Not Required |
This value configures a Planning kie-server web application accessible path with the users affinities definition if desired, Skills and Affinities. For example, in Wildfly/EAP installations it can be like this. `${jboss.server.config.dir}/affinities.properties` Note: the format is analogous to the user definitions file. katy=affinity1,affinity4 |
| 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. |
*Tasks Labeling*
1. Any human task is created in the processes runtime.
2. When the new task is detected by the task assigning solution refreshing mechanism, a set of LabelValueExtractors is applied.
3. These LabelValueExtractors can transform any piece of information in the human task or user into a label.
4. 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"}
*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 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 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 |
*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](#container-based-usersystemservice-configuration) or the [Solver configuration](#container-based-solver-configuration).
1. 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:
```xml theme={null}