User tasks

User tasks play an important role in business processes and are the core construct in Kogito. They are implemented as work item and their execution is defined by work item handler.

Life cycle

To allow a customisable implementation work item itself has been enhanced to support a life cycle. A life cycle is meant to move a work item across various phases that are not defined at the WorkItem interface itself but can be added on runtime.

Life cycle defines the exact behaviour of a given work item at runtime. It is usually added on top of WorkItemHandler to make it pluggable and allow for more flexible runtime characteristics.

WorkItemHandler interface has been enhanced to provide option to move between states

public void transitionToPhase(WorkItem workItem, WorkItemManager manager, Transition<?> transition)

Note	This method is a default method which does nothing when not implemented. It is done like this to keep backward compatibility with already existing work item handler implementations.

Usual implementation of the transitionToPhase will look like following

@Override
public void transitionToPhase(WorkItem workItem, WorkItemManager manager, Transition<?> transition) {

    lifeCycle.transitionTo(workItem, manager, (Transition<Map<String, Object>>) transition);
}

where lifeCycle is an implementation of org.kie.kogito.process.workitem.LifeCycle<T> that actually defined the execution semantics.

Life cycle phases

These states are defined as life cycle phases and there are several of them provided out of the box

• Active - initial state when work item is activated

• Abort - abnormal completion of the work item

• Complete - normal completion of the work item

Note	Above list applies to any work item and thus can be used not only with user tasks but any other tasks that require life cycle management.

Below is a list of life cycle phases dedicated to user tasks

• Claim - assigns given work item to particular actor, restricting access to anyone else

• Release - unassigns given work item from particular actor, making it available for any other potential user or group to work on it (by claiming or completing)

• Skip - skips given work item

Further life cycle phases can also be defined to meet business needs.

Base human task life cycle

A default implementation of the human task life cycle is provided by org.jbpm.process.instance.impl.humantask.BaseHumanTaskLifeCycle. It supports following life cycle phases

• Active

• Claim

• Release

• Complete

• Skip

• Abort

At the beginning human task enters <pre>Active</pre> phase. From there it can go to

• Claim

• Complete

• Skip

• Abort

at any time. At each phase data can be associated and by that set on work item.

Authorization

org.jbpm.process.instance.impl.humantask.BaseHumanTaskLifeCycle is equipped with few checks to make sure that work item is worked by people that are eligible to work on it.

As soon as there are any input data given that defines user/group assignment will enforce the authorisation check.

Following are the ways to pass in user/group assignments

Parameter name	Description	Example value
ActorId	Comma separated list of users to be potential owners, supports expressions	John,Mary,#{actor}
GroupId	Comma separated list of groups that members of can be potential owners, supports expressions	mangers,#{mygroup}
BusinessAdministratorId	Comma separated list of users that can administrate this task, supports expressions	Administrator,#{adminuser}
BusinessAdministratorGroupId	Comma separated list of groups that members of can be administrators of the task, supports expressions	admins,#{admingroup}
ExcludedOwnerId	Comma separated list of users that cannot work on this task, supports expressions	poul,#{lastactor}

Note	Authorization is only enforced when the method that calls the work item life cycle methods come with security context. This is dependent on the api being used.

Example

Following is an example of the API used to interact with work item using life cycle phases

// start process instance
ProcessInstance<?> processInstance = approvalsProcess.createInstance(m);
processInstance.start();

// setup security policy with identity information
StaticIdentityProvider identity = new StaticIdentityProvider("admin", Collections.singletonList("managers"));
SecurityPolicy policy = SecurityPolicy.of(identity);

// get list of work items taking security restrictions into account
List<WorkItem> workItems = processInstance.workItems(policy);

// work on a task
final String wiId = workItems.get(0).getId();
processInstance.transitionWorkItem(wiId,
                                   new HumanTaskTransition(Claim.ID, null, policy));

processInstance.transitionWorkItem(wiId,
                                   new HumanTaskTransition(Complete.ID, Collections.singletonMap("approved", false), policy));

When interacting with user tasks over REST api users can provide following query params to provide user and group information

Parameter name	Description	Multi value supported
user	User name to be used for user task authorisation check	No
group	Zero or more groups to be used for user task authorisation check	Yes

Create custom life cycle and phase

Users might want to extend the life cycle to be used for handling user tasks by implementing

• Life cycle phase(s)

• Life cycle

Implement life cycle phase(s)

To provide additional life cycle phases, you need to implement org.kie.kogito.process.workitem.LifeCyclePhase.

There are several methods to be implemented:

• id - to be unique as it is used when transitioning

• canTransition - provides a check point between phases - if this phase can be transitioned from given phase

• status - that defines human readable status for this phase

• isTerminating - that determines if this phase is a completion stage, if so it will complete work item and move on to next activity in the process

• apply - optional method that allows to perform additional updates to the work item upon transition e.g. set extra data etc

Note	You can implement as many phases as needed or extend existing ones.

Implement life cycle

Once there is a need to have additional phases covered or have another way of handling human task life cycle a custom implementation of org.kie.kogito.process.workitem.LifeCycle<Map<String, Object>> can be provided.

Note	To support human task the parameterised type of LifeCycle must be Map<String, Object>.

There are several methods to be implemented

• phaseById - retrieves phase by id - this us used to verify if given phase is supported by given life cycle implementation

• phases - returns all supported phases by given life cycle implementation

• transitionTo - provides main logic to handle phase transition

• data - returns the current state of data for given work item

Configure to use custom LifeCycle

Once the implementation for life cycle and phases is done it needs to be configured for the runtime to use it instead of the default one. This is done in exact same way as for any other work item handler via WorkItemHandlerConfig class

@ApplicationScoped
public class CustomWorkItemHandlerConfig extends DefaultWorkItemHandlerConfig {{
    register("Human Task", new HumanTaskWorkItemHandler(new CustomHumanTaskLifeCycle()));
}}

Actual work item handler is the same as used by default but instead of the default life cycle you pass as constructor argument custom implementation of the LifeCycle interface.

A complete example showing custom life cycle in action can be found

• for Quarkus

• for SpringBoot

Note	Human Tasks On Entry and On Exit actions are not yet supported.