Bulk operations

Summary

1. A first user issues POST with the operation specification.
2. The API responds with the URL of the job status.
3. The user can query this URL with GET to check the operation status (for example to update progress bar).
4. When the user recognizes that the operation has completed (processed=total), resources should be released with DELETE.
5. Issuing DELETE when a bulk operation is still in progress aborts it, but does not roll back already modified interactions.

Methods

• POST
• GET
• DELETE

POST

Syntax

POST /gtl/tasks/<solution_dbid>/<page>?entity_dbid=<dbid>&entity_type=<department/process/capturePoint/solution>&filter=<filter_name>&order_by=<qualified_attribute_name>&order_direction=<ascending/descending>&snapshot_id=<snapshot_id>

Request Body: up to 9.0.012

{
  "action": "<hold/resume/cancel/modify/modify_restart>",
  "include": [ <task_id1>, <task_id2>, ...],
  "exclude": [ <task_id1>, <task_id2>, ...],
  "attributes":
    {
      "core":
      {
        <attribute definitions>
      },
      "ext":
      {
        <attribute definitions>
      },
      "data":
      {
        <attribute definitions>
      }
    },
}

Request Body: from 9.0.013

{
    "content": {
            "action": "<hold/resume/cancel/modify/modify_restart>",
            "include": [ <task_id1>, <task_id2>, ...],
            "exclude": [ <task_id1>, <task_id2>, ...],
            "attributes":
            {
                "core":
                {
                    <attribute definitions>
                },
                "ext":
                {
                    <attribute definitions>
                },
                "data":
                {
                    <attribute definitions>
                }
            }
    },
    "qlExpression": [<ql_item>, <ql_item>, ...]
}

Notes

• include and exclude cannot both be present in one request.
• If include is present, only the selected tasks from the query will be affected.
• If exclude is present, all tasks from the query except for those selected will be affected.
• If neither include nor exclude is present, then all tasks from the snapshot will be affected.
• The attributes section should contain new values of attributes to be modified. It will be ignored for actions other than modify or modify_restart.
• The <page> path attribute is ignored in this case. All tasks that matches the query and the include/exclude list will be affected, regardless of the page.
• snapshot_id is mandatory.
• The value for the qlExpression field is the same object as request body from Fetch paginated list of tasks.

Result

HTTP 202 Accepted
Location: <URL of the job status>

Response Body

{
  "location": "<URL of the job status>"
}

Example URL:

/gtl/tasks/jobs/statuses/1234

GET

Syntax

GET <job status URL>

Response Body

HTTP 202 Accepted
 {
   "processed": <number of processed tasks>,
   "total": <total number of tasks to process>,
   "wait": <number of milliseconds>
 }

• "wait" is a suggested number of milliseconds to wait before asking again for the status.

HTTP 200 OK
 [
   {
     "task_id": "<task_id>",
     "status": "OK",
     "message": <message definition>
   },
   {
     "task_id": "<task_id>",
     "status": "ERROR",
     "message": <message definition>
   },
   ...
 ]

Notes

• <message definition> has the same format as message. Can be skipped if there is no message.
• For status = "OK" there may be a warning message when the operation succeeded, but an update to UCS failed.
• Or, if there is no remembered snapshot ID for the requested query:

HTTP 404 Not Found

The last option may occur if the request was sent without first sending a request for a tasks list, or the snapshot was released in the meantime. When this happens, the client should download the tasks list again, allow the user to review the tasks selection and submit the modification request again.

DELETE

Syntax

When bulk operation results have been read, they should be removed to release resources:

DELETE <job status URL>

Response Body

HTTP 204 No Content

regardless of whether the job was found or not.

If the given job is still running, calling DELETE will stop it as soon as possible. Results can also be removed automatically after some (configurable) time after finishing.