Tasks management: swimlanes, substitutors, escalation
© 2015-2019, "Process Technologies" Ltd, this document is available under GNU FDL license. RUNA WFE is an open source system distributed under a LGPL license (http://www.gnu.org/licenses/lgpl.html).
# Swimlanes and tasks
Business process task is generated when control flow reaches an Activity node. Swimlanes are used to determine executors to whom task is sent.
Swimlane is a special kind of business process variables.
During business process development all necessary swimlanes are created. Then for each Activity node (and Start node) a correspondent swimlane is chosen. During business process execution swimlanes are assigned with executors. This assignment is called swimlane initialization.
Before Activity node is executed a corresponding swimlane must be initialized with an executor (a group or a user). If it's a group then before Activity node execution swimlane must be additionally initialized with a member of the group. The Activity node task is sent to all group members but the swimlane is additionally initialized by the user who takes task for the execution. After it the task disappears from the task list of all other members of the group.
In the Start node swimlane is automatically initialized by the user who starts the business process. The rules of the rest of the swimlanes initialization are set during swimlane creation while developing business process. Besides in Activity node a swimlane can be initialized by a special component - role initializer, handler, bot or in graphical element of a form.
# Executors substitution
Every user in the system can become inactive because s/he departs to a business trip or falls ill. To change user status go to the user properties and uncheck the checkbox "Active" then click "Apply".
Note. If there's no "Status" section in the user's page then the logged in user doesn't have permission to view/change user status. RunaWFE administrator can help with this problem.
Inactive user's tasks can be redirected to his/her substitutors. Substitution rules are used to identify substitutors. They can be added on the user's properties page. Tasks that are received by substitutor are highlighted with yellow color.
There are substitution rules of two types:
- ”Rule” – specifies an Executor’s substitute for a certain case.
- ”Terminator” – specifies that in a certain case the Executor is not to be replaced.
If a rule is set, it is necessary to define a function on the organizational structure and select substitution criteria from a list.
Note. In order to be able to perform task as substitutor the substitutor must have read permissions on the substituted user. This permission can be set on the substituted user properties page (permission owners link in the right upper corner of the page). Add substitutor or his/her group in the list and then check the read permissions checkbox fot him/her.
# Substitution rule addition
Click "Add rule" to begin with rule addition
Determing orgfunction and select substitution criterion
The following orgfunctions are available:
ru.runa.wfe.extension.orgfunction.GetActorsByCodesFunction – “Executor by code" function takes one parameter (executor of executor code) and returns executor.
ru.runa.wfe.extension.orgfunction.ExecutorByNameFunction – “Executor by name”, function takes one parameter (executor of executor name) and returns executor.
ru.runa.wfe.extension.orgfunction.DemoChiefFunction – “Chief (demo)” function takes one parameter (user of user code) and returns chief defined in demo.chief.properties.
ru.runa.wfe.extension.orgfunction.SQLChiefFunction - “Chief” function takes one parameter (user of user code) and returns chief from result of DB query defined in sql.orgfunction.properties.
ru.runa.wfe.extension.orgfunction.SQLDirectorFunction – “Director” function takes one parameter (user of user code) and returns director from result of DB query defined in sql.orgfunction.properties.
The selected criterion corresponds to either business process and swimlane (criteria are created separately on "System" page) or is "always substitute" criterion.
"Apply" option is used to turn on/off the current rule.
# Substitution terminator addition
There's "Add terminator" option in "Substitutors" section of user properties.
When adding terminator it's necessary to choose substitution criterion.
There's a "Always substitute" criterion and the rest created on "System" page.
# Chief subsitution criteria
It's possible to add other criteria besides "Always substitute". Go to "System" page and click on "Add" in "Substitution criteria" section.
Here the criterion name, type and parameter are specified.
Possible criterion types:
This creteria type configuration includes process name and swimlane. This parameter is set in "Process.Swimlane" format. The substitution rule with this criteria type can be used on tasks with correspondent business process name and swimlane.
ru.runa.wfe.ss.SubstitutionCriteriaNotEquals The configuration for this type contains either a variable of type Executor, User, Group or a swimlane (with swimlane: prefix). The value of this parameter is used to determine if the substitution rule can be applied. The parameter (variable of swimlane) is used to form a list of users and substitution rule is applied if this list doesn't include the user for whom the task list is created.
The following problems benefits from this type of criteria. Let's consider a task of approving subordinate's actions by his/her chief. When chief is absent one of the subordinates can substitute him/her with this criteria type. It will prevent the situation when chief substitutor can approve his/her own actions.
The criteria are available both in substitution rules and in terminators.
# How substitution works
Substitution rules are iterated from top to bottom and first enabled rule (or terminator) with matched criterion is applied.
If "Enable" checkbox is not checked the rule (or terminator) is ignored.
For every active rule (or terminator):
- for terminator if substitution criterion matches then no substitution is done and no further rules are considered.
- for substitution rule if criterion matches and orgfunction returns and active executor, then this executor is used as substitutor and no further rules are considered.
- if none of the above is true, then next rule (or terminator) from the list is considered. If there's no further rules (or terminators), then no substitution is made.
In order to move rules (or terminators) up and down in the list and change their priority use triangular in "Enable" column. In order to delete rule (or terminator) select it and then click "Remove".
Note. If swimlane is initialized by group (or temporary group), then the task is sent to substitutor/substitutors only if all group users are not active. So if there's only one inactive user in the group his/her substitutor will not receive task. If all group users are inactive all substitutors will receive tasks.
# Ignoring substitution rules
Sometimes there are tasks that by their essence cannot be performed by substitute. Especially for this case it is possible to set ignore substitution rules option when creating business process. In order to do so select the state in question in Developer Studio on the business process graph and right click on the state to see the menu. Select Roles > Ignore substitution for this state. When ignore is on this option is checked in the menu and in the state properties you can see "Ignore substitution for this state - Yes".
# Substitution example
User julius is not active. His substutors nero, marcus and octavia are determined depending on substitution rules.
In this case there are 3 rules and 1 terminator. Terminator is not active because "Enabled" is not checked.
Criteria used in substitution rules:
Here's how the substitution works in the given example:
Julius is away on a business trip and is inactive. Julius receives task from "sub2" business process with "Swimlane1" swimlane in it. The substitution rules are iterated from top to bottom. The second rule from the list is applied in this case because "business trip" criteria of "SubstitutionCriteriaSwimlane" type has the parameter "sub2.Swimlane1" that matches the business process name and swimlane of the current task.
This means that nero is the substitutor in this case.
The task goes to nero by substitution.
# Task expiration time
# General description
For each task in RunaWFE it is possible to set expiration time. The task is "almost expired" if the definite part of expiration time has expired. When the full amount of set expiration time is up the task becomes expired.
The almost expired task is highlighted by lilac color in tasks list and on the process instance graph. For the expired task pink(red) color is used:
The task expiration time property is used to set the task deadline. If it is not set the value from system.properties configuration file is used. It is the value set for all tasks by default.
# Configurations in file
According to Base properties (system.properties) the following parameters are used to determine task deadline:
- task.default.deadline - task default deadline is used if the value is not set explicitly for the task during process development. When deadline is passed the task is considered expired. Default value is 2 hours
- task.almostDeadlinePercents – the task is considered "almost expired" after this percent of dealine time is expired. The default value is 90 percent.
If you want to redefine default values of these parameters follow the guidelines from Overriding properties and create wfe.custom.system.properties file in wfe.custom folder.
# Configurations in Developer Studio
In order to set expiration time to a node select it, go to its properties, and click on the button for expiration time property.
The period of waiting time is set here, it starts from the moment when control flow enters task and the measure unit can be selected from the list:
Also it is possible to set default expiration time for all tasks in process. In order to do it go to the process properties and click on button for "Expiration time for each task by default".
Configuration of deadline is applied in the following order:
- the one set in Developer Studio in task properties
- if not set in Developer Studio in task properties, then default tasks deadline from process properties
- if not set in the above cases, WFE Server configuration task.default.deadline parameter from system.properties (wfe.custom.system.properties) is used
# Mechanism of task escalation
# General description
Escalation is a way to extend the number of task executors after certain amount of time since the control flow enters the task. First time of escalation can be set as well as periodic escalation repeat time.
Escalation settings are taken from
- default parameters from system.properties, (they can be overridden in wfe.custom.system.properties;
- configurations from Developer Studio in menu Escalation configuration. By changing it's value you don't change anything for existing escalation, this configuration is used to get default value when escalation is created in the process definition.
- configurations from task properties in Developer Studio (escalation must be switched on for this task)
# Escalation configuration in file
There are two settings in system.properties for escalation:
- escalation.enabled – can be "true" or "false", is used to enable/disable escalation globally. If set to "false" then escalation will not work even if it is enabled in business process definition. Default value is "true".
- escalation.default.hierarchy.loader (Before 4.1.1 - escalation.default.orgFunction) - orgfunction or relation4.1.1+ for escalation on task. It is used if none is set in Developer Studio. Default value is ru.runa.wfe.extension.orgfunction.TestOrgFunction (dummy orgfunction). The value is fully qualified orgfunction class name or relation name in format @relationName. Inversed relation is in format @!relationName.
Note. If you want to redefine parameter values from system.properties, use override rules, and edit wfe.custom.system.properties by adding overridden parameters if they are not present yet.
# Escalation configuration in Developer Studio
The following parameters are used to configure escalation for a process task in Developer Studio:
- “escalation timeout” – optional parameter that determines when escalation is triggered; Note. If this parameter is not set then “task deadline” value is used;
- “orgfunction or relation 4.1.1+)” – organization function that is called when escalation triggers to extend the number of task executors;
- “escalation repeat timeout” – the repeat timeout for escalation can be set, by default there's no repeats;
It's possible to configure escalation for the whole process or/and for individual tasks. The parameters may differ.
To turn on task escalation right-click on the task and select "enable escalation" from menu.
To turn off task escalation select "disable escalation" from the same menu.
To turn on/off escalation for the whole process (for all process tasks) left-click on white field of the process graph and choose correspondent option from the popup menu:
When you turn on the process escalation (for the whole process or individual task) the initial parameters values are taken from Developer Studio settings and are put to task(s) properties. If initial parameters are not set in Developer Studio they are taken from system.properties/wfe.custom.system.properties.
To set escalation initial parameters in Developer Studio choose "Properties > Preferences > Escalation (default settings)" in the main Developer Studio menu.
Each parameter can be changed with the help of correspondent button.
The escalation timeout is amount of time between the moment when the control flow enters the node and the moment when escalation is triggered:
the measurement unit can be chosen from the list:
Organization function can also be chosen from the list:
Orgfunctions GetActorsByCodesFunction, ExecutorByNameFunction are not used for escalation, because they return the executor him/herself and don't expand the circle of executors.
"SQL orgfunction" also is not used for escalation.
"Chief (demo)" orgfunction is for demo purposes only and is not recommended for use in production environment.
Default parameters for orgfunctions SQLChiefFuntion and SQLDirectorFunction are set in sql.orgfunction.properties' file. (See more). Use wfe.custom.sql.orgfunction.properties (see How to override parameters in configuration") to override parameters. datasource parameter is datasource name (it can be current Runa DB or external DB with company orgstructure). If external DB is used the datasource must be registered in standalone.xml, but without installing corresponding dialect(see more about adding new datasource).
It's possible to write custom handlers (written similar to existing ones). TODO: an example of relation choice.
Note. Since 4.1.1 it's possible to use relations for escalation.
Repeat timeout form is the same as for escalation timeout form.
For each task in process it's possible to set its own escalation parameters. Select task node and go to task properties
Here you can set escalation timeout, orgfunction and repeat timeout. The parameters input is the same as described earlier.
# Escalation and substitution
Escalation expands temporary executors group. A standard way of substitution for group is used then. (See Substitutions. Note about groups).
Note. There's a drawback in substitution work in connection with escalation.
Department head goes on vacation and leaves a substitutor. While substitution is registered in the system, some department head tasks are escalated with temporary group which includes company director. Department head is inactive and has a substitutor, but director is active and substitution rule is not triggered. So director is left to do the task instead of substitutor.
In future versions escalation will be changed. By plan substitution will occur on escalation layers. In the above example we have a temporary group with 2 users, first layer - department head, then expanded to second layer - director. So substitution rule will discover that in first layer there's inactive user and substitutor for department head will be added to temporary group.
# An example of process with escalation and expiration time
# Process description
Let us consider a simple example of process that illustrates escalation.
Note. In this example "Chief (via file)" function is used. It is not recommended for production usage and works only for demo purposes.
At first let's configure default escalation parameters in Developer Studio:
Our example process consists of several node and one choice.
Select “State 1” and turn the escalation on for it. The escalation parameters for the task will be automatically set to the Developer Studio defaults
Escalation timeout – 2 minutes
Orgfunction – DemoChiefFunction - chief function (via file)
Repeat timeout is not set
“State 2” – escalation enabled, escalation timeout is set in task settings (it differs from default), orgfunction is DemoChiefFunction:
Escalation timeout – 1 minute
Orgfunction – chief (via file)
“State 3” – escalation enabled, escalation timeout is not set, but expiration time is set, so escalation must be triggered when task expires:
Expiration time – 3 minutes
Orgfunction – chief (via file)
# Process execution
Let us start this process under “attila” user
“State 1” in task list:
We don't execute task during 2 minutes:
As we can see from the process instance history the escalation was triggered and a temporary group (with attila and nero in it) was created
Nero is Attila's chief
So the number of executors for this task was extended.
As a result Nero got the “State1” in his task list.
Let's execute this task by Nero user
We can see in the process history that the task was executed by Nero as substitutor:
For “State 2”:
After a minute escalation triggers:
The number of executors has extended and the task goes also to Attila's chief
In “State 3” escalation triggers when task expires (in 3 minutes)
The task goes to Nero