Processing a user task by calling IBM BPM REST APIs

A user task is assigned to one or more teams. A team member claims the task, provides the relevant information, and then completes the task.

Before you begin

Attention: REST API calls that return a list of objects, for example, GET /processes or GET /user-tasks can include query parameters, such as the model name, container name, or process ID. If the parameter value points to an object that doesn't exist, for example, because the process ID contains a typo, an error is not thrown. Instead the JSON object returned by the call contains an empty list. For information about the API calls, see IBM BPM REST APIs resources.

Procedure

Display a list of unclaimed tasks that the current user is allowed to see. Unclaimed tasks are those tasks in the ready state:
```
GET /bpm/user-tasks?states=ready
```
To filter the tasks list to show only tasks for a specific process, include the model name, for example, OrderManagement, in the query:
```
GET /bpm/user-tasks?model=OrderManagement&states=ready 
```
Alternatively, you can display the tasks for a specific process instance by including the process ID, for example 2072.3, in the query:
```
GET /bpm/user-tasks?process_id=2072.3&states=ready 
```
The user opens a task in the list to review the business data. To display the business data, include the optional_parts=data parameter in the query. To ensure that the user is authorized to view and claim the task, include the actions property in the optional_parts parameter.
For example, if the user opens task 2078.3, you can use the following REST API call to show the task details and return the actions that the user can perform:
```
GET /bpm/user-tasks/2078.3?optional_parts=data,actions 
```
The user claims the task. For example, if the user claims task 2078.3, you can use the following REST API call:
```
POST /bpm/user-tasks/2078.3/claim?optional_parts=data 
```
The task is put into the claimed state. The returned user-task instance object includes the user ID of the task owner and the variables that are currently set.

The task owner provides the required information and completes the task.

The required data output variables for the task are passed in a JSON object in the request body of the /complete call. For example, the order processor might need to provide a confirmation that the stock is available at a warehouse and the total cost of the order.

POST /bpm/user-tasks/2078.3/complete
...
{
   "output":[
      {
         "name":"inStock",
         "data":"Yes"
       }
       {
          "name":"Price",
          "data":"1000",
       }
       {
          "name":"warehouseAddress",
          "data":{
             "street":"Mystreet", 
             "houseNo":"12", 
             "postCode":"1234", 
             "city":"Mycity" 
            }
        }]
}

Results

The task is put into the finished state. The returned user-task instance object contains the updated state information, the completion time stamp, and the updated variables.