In a previous post we discussed the task process API, which dealt with tasks from a process perspective. As explained in there, the task model depends on data defined by users. But, regardless of the task related information provided by users through BPMN processes, every existing task in Kogito has some predefined fields, mainly related to security policies, which are handled by Tasks Management API.
Since Task Management API is a security-sensitive API, it is often referred as Admin API, but that name might cause confusion and should be avoided. Reason is that this API is not intended for an administrator to change all task parameters arbitrarily, but for any user with enough privileges (in future, when Kogito defines a global authentication policy, management endpoint will be available only to users with certain privileges. Administrators will be of course included among them) to modify those task parameters not exposed by Task Process API.
One important implication of this line of thought is that users with administrative privileges must use Task process API, as any other regular user, to perform phase transitions, change output parameters or add comments and attachments.
Task management information
The information that can be consulted or modified by Task Management API consist of:
- Description. Human readable description of the task
- Priority. A string field that indicates task priority.
- Potential Owners. The list of users and the list of groups which can claim ownership of the task
- Administrators. The list of users and the list of groups which are task administrators, meaning that they can perform API process calls without being the current owners.
- Input parameters. A list of key value pairs. Although it includes the input model, which as you recall is automatically calculated during process execution, from a management perspective you will probably be more interested in interacting with additional task metadata information, also incorporated here. Fields like name, actorId or skippable, which might be useful to to change in certain specific scenarios, but cannot be modified using Task process API, because they are not part of the task model.
Some readers might be wondering, what about the current task owner? Following the rationale previously exposed, since the current task owner is expected to be established by using Claim o Release transitions, it was decided to not include it in the list of parameters that can be modified by Task Management API. Again, the administrative user can use the regular Task Process API to do so.
Task management operations
Task management API consists of just one resource, which, in an outburst of originality, is called task.
Endpoint URI match this template
http://<host>:<port>/management/processes/<process id>/instances/<process instance id>/tasks/<task Id>Task management endpoint supports following HTTP methods:
- GET is used to consult task information.
- PUT is used to replace whole task information, meaning you need to pass the whole task. Therefore, if you did not include a field in the request, this field will be set to null.
- PATCH is used to replace only certain fields, meaning that you pass only those fields you want to modify. Since usually you only need to modify a subset of all the fields, this will be the method you will be employing most.
Retrieving task information
We will illustrate management API usage by employing the approval example from previous post, adding task-management add-on to the project pom
<dependency>
<groupId>org.kie.kogito</groupId>
<artifactId>task-management-quarkus-addon</artifactId>
</dependency>
Since you already have the proper process instance Id and task Id, invoking
GET http://localhost:8080/management/processes/approvals/instances/<process instance id>/tasks/<task Id>will return as response a JSON similar to this one
{
"description": null,
"priority": null,
"potentialUsers": [
"manager"
],
"potentialGroups": [
"managers"
],
"excludedUsers": [],
"adminUsers": [],
"adminGroups": [],
"inputParams": {
"TaskName": "firstLineApproval",
"NodeName": "First Line Approval",
"Skippable": "true",
"ActorId": "manager",
"traveller": {
"firstName": "John",
"lastName": "Doe",
"email": "jon.doe@example.com",
"nationality": "American",
"address": {
"street": "main street",
"city": "Boston",
"zipCode": "10005",
"country": "US"
}
},
"GroupId": "managers"
}
}
Note that inputParams field contains a traveller instance, which is the model defined for firstLineApproval task, but also includes NodeName, Skippable and ActorId, which are not part of it.
Updating task information
Let’s assume you want to add a description, change skippable input parameter to false and add user menganito to the list of potential users for that task instance, you should invoke
PATCH http://localhost:8080/management/processes/approvals/instances/<process instance id>/tasks/<task Id>providing as body
{
"inputParams" : {"Skippable":false},
"description" : " Real Betis Balompie is the best soccer team in the world",
"potentialUsers":["manager","meganito"]
}
Please note that when using PATCH you only need to specify those fields that you want to modify, but if the field data type is a JSON collection, you need to specify all the items in the collection. That’s why we only provide skippable as inputParams value (because input parameters are merged) but the complete list for potentialUsers fields (because collections are not merged).
The response of previous invocation will consist on the whole resource properly modified
{
"description": " Real Betis Balompie is the best soccer team in the world",
"priority": null,
"potentialUsers": [
"manager", “menganito”
],
"potentialGroups": [
"managers"
],
"excludedUsers": [],
"adminUsers": [],
"adminGroups": [],
"inputParams": {
"TaskName": "firstLineApproval",
"NodeName": "First Line Approval",
"Skippable": false,
"ActorId": "manager",
"traveller": {
"firstName": "John",
"lastName": "Doe",
"email": "jon.doe@example.com",
"nationality": "American",
"address": {
"street": "main street",
"city": "Boston",
"zipCode": "10005",
"country": "US"
}
},
"GroupId": "managers",
}
}
Conclusion
In this post we discussed the Task Management API, a brief (just one resource) but powerful one, which is intended to interact with task information that is not part of the process model. Next post, the last of this series, will describe how to establish task deadlines, whose main purpose is to make sure that a task does not fall into oblivion.
