Bulk Operations
Bulk Add
Bulk Add Permissions
Required permissions:
- Workitems > BulkAddJob > Add, Delete, Edit, View
- Workitems > BulkAddJobResults > View
Division Awareness:
- To create: Requesting user must have
workitems:bulkaddjob:addpermission in the division(s) containing all the worktypes supplied in the request. - To view/edit/delete/view results: Requesting user must have the respective permission in the division(s) that contained the worktypes supplied in the creation request.
Restrictions
A bulk add request can contain a minimum of 1 and a maximum of 50 workitem entities. Wrap up codes, utilization labels, scored agents and preferred agents cannot be added through the bulk add workitems api. These attributes can be added individually to the workitems after they have been created.
Create bulk add job
Example API call to create a bulk add job:
{
"entities": [
{
"name": "workitem name",
"typeId": "31fa2652-1023-4461-a854-6edf8d384716",
"priority": 1,
"dateDue": "2024-12-18T00:00:00.000Z",
"description": "bulk add workitems"
},
{
"name": "workitem name 2",
"typeId": "00000000-0000-0000-0000-000000000000",
"queueId": "00000000-0000-0000-0000-000000000000",
"priority": 10,
"dateExpires": "2025-01-02T00:00:00.000Z"
}
]
}This creates a bulk add job in Idle state. To execute the bulk add job you must update the state of the job to Queued.
{
"state": "Queued"
}A bulk add job can only be terminated when its state is Idle. The job is terminated by updating its state to Terminated. A bulk add job can also be deleted if the job's state is Idle.
DELETE /api/v2/taskmanagement/workitems/bulk/add/jobs/{bulkJobId}Get bulk add job
GET /api/v2/taskmanagement/workitems/bulk/add/jobs/{bulkJobId}Response
The response returns information about job, including the count of successful/failed workitem creations and the job's state.
{
"id": "9901b8fc-6812-4131-9cbd-1db2a8ae45f1",
"state": "Succeeded",
"action": "AddWorkitems",
"totalCount": 2,
"successfulCount": 1,
"failedCount": 1,
"dateStarted": "2024-12-02T12:18:56.067Z",
"dateFinished": "2024-12-02T12:18:56.315Z",
"dateModified": "2024-12-02T12:18:28.426Z",
"selfUri": "/api/v2/taskmanagement/workitems/bulk/add/jobs/9901b8fc-6812-4131-9cbd-1db2a8ae45f1"
}Once a job reaches the Succeeded state, you can retrieve detailed information about the created and failed workitems using the results API endpoint.
Get bulk add job results
GET /api/v2/taskmanagement/workitems/bulk/add/jobs/{bulkJobId}/resultsResponse
The response contains the outcome of each workitem create operation in the bulk job as well as the error count and error indexes.
{
"results": [
{
"entity": {
"id": "cbc8e98a-0747-42a2-be96-4288829454cc",
"name": "workitem name",
"workbin": {
"id": "58de1397-695d-4342-9df2-9ba94456e50a",
"selfUri": "/api/v2/taskmanagement/workbins/58de1397-695d-4342-9df2-9ba94456e50a"
},
"type": {
"id": "344ed193-ae31-4b10-bbf5-7edaf9a82980",
"selfUri": "/api/v2/taskmanagement/worktypes/344ed193-ae31-4b10-bbf5-7edaf9a82980"
},
"selfUri": "/api/v2/taskmanagement/workitems/cbc8e98a-0747-42a2-be96-4288829454cc"
}
},
{
"error": {
"message": "worktype with ID 00000000-0000-0000-0000-000000000000 is not found.",
"code": "not.found.error"
},
"entity": {
"name": "workitem name 2",
"type": {
"id": "00000000-0000-0000-0000-000000000000",
"selfUri": "/api/v2/taskmanagement/worktypes/00000000-0000-0000-0000-000000000000"
}
}
}
],
"errorCount": 1,
"errorIndexes": [
1
]
}Bulk Terminate
A bulk terminate request can contain a minimum of 1 and a maximum of 100 workitem ids.
Bulk Terminate Permissions
Required permissions:
- Workitems > BulkTerminateJob > Add, Delete, Edit, View
- Workitems > BulkTerminateJobResults > View
Division Awareness:
- To create: Requesting user must have
workitems:bulkterminate:addpermission in the division(s) containing all the workitems supplied in the request. - To view/edit/delete/view results: Requesting user must have the respective permission in the division(s) that contained the workitems supplied in the creation request.
Create bulk terminate job
Example API call to create a bulk terminate job:
{
"entities": [
{
"id": "fb2a61f2-27aa-40c1-b979-0e7ed3ba5df9"
},
{
"id": "1263e8c6-e26a-4b43-a056-6a3f5954b07a"
}
]
}This creates a bulk terminate job in Idle state. To execute the bulk terminate job you must update the state of the job to Queued.
{
"state": "Queued"
}A bulk job can only be terminated when its state is 'Idle'. The job is terminated by updating its state to 'Terminated'. A bulk terminate job can also be deleted if the job's state is Idle.
DELETE /api/v2/taskmanagement/workitems/bulk/terminate/jobs/{bulkJobId}Get bulk terminate job
GET /api/v2/taskmanagement/workitems/bulk/terminate/jobs/{bulkJobId}Response
The response returns information about job, including the count of successful/failed workitem terminations and the job's state.
{
"id": "183918b7-3032-4107-820d-179d095ad30a",
"state": "Succeeded",
"action": "TerminateWorkitems",
"totalCount": 2,
"successfulCount": 2,
"failedCount": 0,
"dateStarted": "2024-12-04T21:20:52.361Z",
"dateFinished": "2024-12-04T21:20:52.979Z",
"dateModified": "2024-12-04T21:20:28.399Z",
"selfUri": "/api/v2/taskmanagement/workitems/bulk/terminate/jobs/183918b7-3032-4107-820d-179d095ad30a"
}Get bulk terminate job results
GET /api/v2/taskmanagement/workitems/bulk/terminate/jobs/{bulkJobId}/resultsResponse
The response contains the outcome of each workitem terminate operation in the bulk job as well as the error count and error indexes.
{
"results": [
{
"error": {
"message": "Invalid workitem assignment state: Terminated.",
"code": "invalid.input.bulk.job.workitem.not.applicable.assignment.state"
},
"entity": {
"id": "3a2751cc-f7de-4e62-8f7e-3d838c840f45",
"selfUri": "/api/v2/taskmanagement/workitems/3a2751cc-f7de-4e62-8f7e-3d838c840f45"
}
},
{
"entity": {
"id": "eddac991-f477-4d65-921c-478cc17a7cd2",
"selfUri": "/api/v2/taskmanagement/workitems/eddac991-f477-4d65-921c-478cc17a7cd2"
}
}
],
"errorCount": 1,
"errorIndexes": [
0
]
}Get all bulk jobs for user
Permissions
- Workitems > BulkJob > View
GET /api/v2/taskmanagement/workitems/bulk/jobs/users/meResponse
The response returns all jobs created by the current user including bulk add and bulk terminate jobs.
{
"entities": [
{
"id": "183918b7-3032-4107-820d-179d095ad30a",
"state": "Succeeded",
"action": "TerminateWorkitems",
"totalCount": 2,
"successfulCount": 2,
"failedCount": 0,
"dateStarted": "2024-12-04T21:20:52.361Z",
"dateFinished": "2024-12-04T21:20:52.979Z",
"dateModified": "2024-12-04T21:20:28.399Z",
"selfUri": "/api/v2/taskmanagement/workitems/bulk/terminate/jobs/183918b7-3032-4107-820d-179d095ad30a"
},
{
"id": "9f5d749d-5e1e-4eaf-8f33-7ba86c58e280",
"state": "Succeeded",
"action": "AddWorkitems",
"totalCount": 1,
"successfulCount": 1,
"failedCount": 0,
"dateStarted": "2024-12-04T11:00:15.329Z",
"dateFinished": "2024-12-04T11:00:16.132Z",
"dateModified": "2024-12-04T10:59:42.462Z",
"selfUri": "/api/v2/taskmanagement/workitems/bulk/add/jobs/9f5d749d-5e1e-4eaf-8f33-7ba86c58e280"
}
]
}Limits
There are several limits to be aware of:
- Bulk terminate concurrent jobs limit: The maximum number of bulk terminate jobs allowed to execute concurrently per organisation.
- Bulk add concurrent jobs limit: The maximum number of bulk add jobs allowed to execute concurrently per organisation.
- Create bulk add jobs per minute limit: The maximum number of bulk add jobs created per minute for a user.
- Create bulk add jobs per day limit: The maximum number of bulk add jobs created per day for an organization.
- Bulk add execute limit: The maximum number of bulk add executions allowed per minute.
- Detail on limits can be viewed here.
