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

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.

Integration in Clients

>> Connection of BPM Engine