AWA Assignment API

The AWA Assignment API provides endpoints to manually assign work items to agents.

This API requires the Advanced Work Assignment (com.glide.awa) plugin and awa_manager role.

A work item is a single piece of work handled by an AWA agent from start to finish. For example, one chat or one case is an object that can be routed and assigned to agents. For more information, refer to Advanced Work Assignment.

AWA Manual Assign – POST /awa/workitems/{work_item_sys_id}/assignments

Assigns an available work item to an available Advanced Work Assignment agent.

The primary use case for this endpoint is to enable external routing systems to route work items. If Advanced Work Assignment is configured to use external routing, work items in the queue are assigned using external routing and not AWA. The work item task can be assigned by calling this endpoint. For information, refer to Use external routing.

URL format

Versioned URL: /now/{api_version}/awa/workitems/{sys_id}/assignments

Default URL: /now/awa/workitems/{sys_id}/assignments

Supported request parameters

Table 1. Path parameters

Name	Description
api_version	Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String
work_item_sys_id	Sys_id of the work item to assign to an available agent. Located in the Work Items [awa_work_item] table. The work item must be unassigned and in the Pending Accept or Queued state. For information, refer to Check unassigned task work items. Type: String

Table 2. Query parameters

Name	Description
None

Table 3. Request body parameters (XML or JSON)

Name	Description
agent_sys_id	Required. Sys_id of the available agent to receive the work item. Agents are users with the awa_agent role in the User [sys_user] table. For information on how to determine if an agent is available, refer to Agent Inbox controls. Type: String

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 4. Request headers

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json
Content-Type	Data format of the request body. Supported types: application/json or application/xml. Default: application/json

Table 5. Response headers

Header	Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Table 6. Status codes

Status code	Description
200	Successful. The request was successfully processed.
401	Unauthorized. The user credentials are incorrect or have not been passed.
404	Not found. The requested item wasn't found.
409	Conflict. The request could not pass due to an error with the provided work item or agent sys_id.
500	Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

Name	Description
success	Flag that indicates whether the manual work item assignment is successful. Valid values: true: Work item assignment successful. false: Work item assignment unsuccessful. Data type: Boolean Default: True
message	Response message acknowledging successful assignment or exception. Exceptions: "Work item can not be assigned" – Work item provided cannot be assigned because it is in Accepted or Canceled state. Refer to Check work items and AWA events. "<agent_sys_id> is not a valid agent" – Agent does not have the awa_agent role. "<work_item_sys_id> is not a valid work item" – Provided work item sys_id does not exist. "Work Item is already assigned to <work_item_sys_id>" – Provided work item is assigned to another agent. "Agent is not available" – Agent is not in the Available state in AWA. Refer to Agent Inbox controls. Data type: String

cURL request

The following example shows how to assign a work item to an available AWA agent.

curl "https://instance.servicenow.com/api/now/awa/workitems/<work_item_sys_id>/assignments" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{\"agent_sys_id\":\"<agent_sys_id>\"}" \
--user 'username':'password'

The result shows that the task has been successfully assigned to the agent. You can verify results in the Assigned to field of the Work Items [awa_work_item] table.

{
  "result": {
    "success": true,
    "message": "Manual assignment successfully requested"
  }
}