From RunaWFE

Jump to: navigation, search

Tasks management: swimlanes, substitutors, escalation

Version 4.3.0

© 2015-2018, "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).

Source code moved from https://sourceforge.net/p/runawfe to https://github.com/processtech.


# 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.

Substitution en1.png

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.

Substitution en2.png

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

Substitution en3.png

Determing orgfunction and select substitution criterion

Substitution en4.png

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.

Substitution en6.png

When adding terminator it's necessary to choose substitution criterion.

Substitution en7.png

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.

Substitution en8.png

Here the criterion name, type and parameter are specified.

Substitution en9.png

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".

Substitution en10.png

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".

WF-system User guide ris26 1.png

# Substitution example

User julius is not active. His substutors nero, marcus and octavia are determined depending on substitution rules.

Substitution en12.png

In this case there are 3 rules and 1 terminator. Terminator is not active because "Enabled" is not checked.

Criteria used in substitution rules:

Substitution en13.png

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.

Substitution en14.png

The task goes to nero by substitution.

# Escalation

# 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:

Timer en pic1.png

Timer en pic2.png

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.

Timer en pic3.png

Timer en pic4.png

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:

Timer en pic5.png

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".

Timer en pic6.png

Timer en pic7.png

Configuration of deadline is applied in the following order:

  1. the one set in Developer Studio in task properties
  2. if not set in Developer Studio in task properties, then default tasks deadline from process properties
  3. 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

  1. default parameters from system.properties, (they can be overridden in wfe.custom.system.properties;
  2. 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.
  3. 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.

Escalation en pic1.png

To turn off task escalation select "disable escalation" from the same menu.

Escalation en pic2.png

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:

Escalation en pic3.png

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.

Escalation en pic4.png

Escalation en pic5.png

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:

Escalation en pic6.png

the measurement unit can be chosen from the list:

Escalation en pic7.png

Organization function can also be chosen from the list:

Escalation en pic8.png

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.

Escalation en pic9.png

For each task in process it's possible to set its own escalation parameters. Select task node and go to task properties

Escalation en pic10.png

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:

Escalation en pic11.png

Our example process consists of several node and one choice.

Escalation en pic12.png

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 en pic13.png

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 en pic14.png

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:

Escalation en pic15.png

Expiration time – 3 minutes

Orgfunction – chief (via file)

# Process execution

Let us start this process under “attila” user

“State 1” in task list:

Escalation en pic16.png

We don't execute task during 2 minutes:

Escalation en pic17.png

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

Escalation en pic18.png

So the number of executors for this task was extended.

As a result Nero got the “State1” in his task list.

Escalation en pic19.png

Let's execute this task by Nero user

We can see in the process history that the task was executed by Nero as substitutor:

Escalation en pic20.png

For “State 2”:

Escalation en pic21.png

After a minute escalation triggers:

Escalation en pic22.png

The number of executors has extended and the task goes also to Attila's chief

Escalation en pic23.png

Next task.

In “State 3” escalation triggers when task expires (in 3 minutes)

Escalation en pic24.png

Escalation en pic25.png

Escalation triggered:

Escalation en pic26.png

The task goes to Nero

Escalation en pic27.png

Personal tools