Handling of process instances and their corresponding tasks via the BPM-ENGINE service.

Introduction

A process can be instantiated based on a process definition that refers to a process model created via Flowable Modeler UI and deployed to the BPM-ENGINE service. Especially, the concrete tasks included in the process instance are determined by the process model referenced via the process definition.
>> Flowable Documentation

The follow-up process model is included as an example in our installations. It is supported by yuuvis® Momentum client as reference implementation and is also compatible with our developer libraries.

Creating Process Instances

Processes instances are created by starting a process based on a specified process definition. All deployed and thus available process definitions can be retrieved via the GET /bpm-engine/api/process-definitions endpoint. Reference one of the listed process definition objects for your concrete process instance creation by its key. Use the value for the processDefinitionKey in the request body.
>> POST /bpm-engine/api/processes

The (first) task included in the process instance is now available for the assignee (if already pre-defined) or all referenced candidate users.

Retrieving Process Instances

Users can only retrieve process instances that they have started themselves.

There are two endpoints available:

GET /bpm-engine/api/processes - Retrieves a list of processes of the currently active user that are matching the conditions defined in various query parameters.
GET /bpm-engine/api/processes/{processInstanceId} - Retrieves the process instance specified by processInstanceId.

Working on Tasks

Retrieving Tasks

Users can only retrieve tasks that are assigned to them or for which they are a candidate user.

There are two endpoints available:

GET /bpm-engine/api/tasks - Retrieves a list of tasks of the currently active user that are matching the conditions defined in various query parameters.
GET /bpm-engine/api/tasks/{taskId} - Retrieves the task specified by taskId.

Responsibilities

Assignee

Only the assignee of a task can take an action on it. An exception is the complete action as described below.

Candidate Users

In order to specify multiple users that should be able to take an action on a specific task, those users can be set as so-called candidate users. It is possible to assign candidate groups as well by specifying a role. Each user with this role will be a candidate user for the corresponding task.

All candidate users are allowed to claim the task and thereby assign it to themselves. As soon as the task is assigned to one of them, it will no longer be available for all other candidate users until the assignee returns it to them. All candidate users are allowed to complete the task without assigning it to themselves when no assignee is specified.

Owner

When the first assignee delegates the task to another user, the first assignee becomes the owner. The owner is not overwritten if further delegations are applied to the task. Whenever a subsequent assignee resolves the task, the owner will be set as assignee again. Thus, the owner is responsible for the task completion.

Actions and Identity Links

Users can take an action on a task specified by its ID via the POST /bpm-engine/api/tasks/{taskId} endpoint. In the request body, the type of action is set as value for the action property. The following actions are available for the user(s) with the corresponding responsibility.

Value for 'action'	Responsibility	Effect on the Task
`complete`	assignee, candidate users	The values for the task variables specified in the request body are updated. The updated task will be a historic task. No further action can be taken on it.
`claim`	if assignee is `null`: candidate users	The first candidate user who claims the task becomes the assignee.
`claim`	if assignee is not `null`: assignee	The assignee can return the task to all candidate users by setting the `assignee` property back to `null`.
`delegate`	assignee	The user specified in the request body replaces the previous assignee. The original assignee is set as owner of the task. The task property `delegationState` is updated.
`resolve`	assignee (if appointed via delegation)	The previous assignee who called the delegation will again be assignee. The task property `delegationState` is updated.

Each action that is applied to a task triggers the creation of a new identity link referring to the acting user in the individual task's history, e.g.:

{
     "type": "assignee",
     "userId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
     "groupId": null,
     "timestamp": "2021-11-01T12:28:46.447Z"
}

Comments

In order to add messages to a task, comments can be created and assigned via the POST /bpm-engine/api/tasks/{taskId}/comment endpoint. They will be included in the process history in a separate section. The following code block shows an example comment vizualising the corresponding stored data set.

{
     "id": "00000001-0001-0001-0001-000000000001",
     "author": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
     "message": "This is the first example comment for the first task.",
     "time": "2021-11-02T13:05:29.099Z",
     "processInstanceId": "00000000-0000-0000-0000-000000000000",
     "taskId": "00000000-0000-0000-0000-000000000123"
}

Process Instance History

The process history is available for active tasks as well as for completed tasks. It can be retrieved via the GET /bpm-engine/api/processes/{processInstanceId}/history endpoint.

The response body is a JSON structure containing the following properties.

Parameter			Description
`tasks`			List of data sets, one for each task within the process. Each data set contains the following parameters:
	`id`		ID of the task instance.
	`name`		Task name.
	`description`		Task description.
	`assignee`		User ID of the current assignee. If the task is currently not assigned to a user, the value is `null`.
	`owner`		User ID of the owner.
	`createTime`		Date and time of task creation.
	`claimTime`		Date and time of last `claim` action on the task. If the task has not been claimed so far, the value is `null`.
	`endTime`		Date and time of task completion (action `complete`). If the task has not been claimed so far, the value is `null`.
	`identityLinks`		List of identity links stored for the corresponding task.
		`type`	Type of identity link, e.g., `candidate`.
		`userId`	ID of the user to which the identity link refers. If multiple users are involved, the value is `null`.
		`groupId`	Role that defines the group of users to which the identity link refers. If only one user is involved, the value is `null`.
		`timestamp`	Date and time of identity link creation.
`comments`			List of data sets, one for each comment that has been assigned to the process.
	`id`		ID of the comment.
	`author`		User ID of the user who assigned the comment to the process.
	`message`		Comment messsage.
	`time`		Date and time of the comment's assignment.
	`processInstanceId`		ID of the process instance containing the task to which the comment was assigned.
	`taskId`		ID of the task instance to which the comment was assigned.

Integration in Clients

>> Connection of BPM Engine

yuuvis® Momentum

Handling of Process Instances and Tasks

Table of Contents