AWA 수동 할당 API

  • 릴리스 버전: Zurich
  • 업데이트 날짜 2025년 07월 31일
  • 소요 시간: 9분

    • AWA 수동 할당 API는 사용 가능 고급 작업 할당 한(AWA) 에이전트에게 사용 가능한 작업 항목을 수동으로 할당할 수 있는 엔드포인트를 제공합니다.

    작업 항목은 에이전트가 처음부터 끝까지 처리하는 AWA 단일 작업입니다. 예를 들어 하나의 채팅 또는 하나의 케이스는 에이전트에게 라우팅되고 할당될 수 있는 객체입니다. 자세한 내용은 고급 작업 할당을 참조하십시오.

    이 API에는 (com.glide.awa) 플러그인이 고급 작업 할당 필요합니다. 이 API를 호출하려면 awa_manager 또는 awa_integration_user 역할이 있어야 합니다.

    AWA 수동 할당 – POST /now/awa/workitems/{work_item_sys_id}/assignments

    사용 고급 작업 할당 가능한(AWA) 에이전트에 사용 가능한 작업 항목을 할당합니다.

    이 엔드포인트의 기본 사용 사례는 외부 라우팅 시스템이 작업 항목을 라우팅할 수 있도록 하는 것입니다. 가 외부 라우팅을 사용하도록 구성된 경우 고급 작업 할당 큐의 작업 항목은 가 아닌 AWA외부 라우팅을 사용하여 할당됩니다. 이 끝점을 호출하여 작업 항목 작업을 할당할 수 있습니다. 자세한 내용은 외부 라우팅 사용을 참조하십시오.

    URL 형식

    버전이 지정된 URL: /now/{api_version}/awa/workitems/{sys_id}/assignments

    기본 URL: /now/awa/workitems/{sys_id}/assignments

    주:
    사용 가능한 버전은 REST API 탐색기에 지정됩니다. 스크립트 기반 REST API의 경우 스크립트 기반 REST 서비스 양식에 추가 버전 정보가 있습니다.

    지원되는 요청 매개변수

    표 1. 경로 매개변수
    이름 설명
    api_version 옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들어 v1 또는 v2입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하려면 이 값만 지정합니다.

    데이터 유형: 문자열
    work_item_sys_id 사용 가능한 에이전트에 할당할 작업 항목의 Sys_id입니다.

    작업 항목이 할당되지 않은 상태여야 하며 보류 중, 수락 또는 대기 중 상태여야 합니다. 자세한 내용은 할당되지 않은 작업 항목 확인을 참조하십시오.

    데이터 유형: 문자열

    테이블: 작업 항목 [awa_work_item]
    표 2. 쿼리 매개변수
    이름 설명
    없음
    표 3. 요청 본문 매개변수(XML 또는 JSON)
    이름 설명
    after_timeout_presence 매개변수가 만료될 경우 timeout 에이전트가 전환할 현재 상태의 Sys_id입니다.

    timeout 매개 변수가 전달되지 않으면 이 매개 변수가 무시됩니다.

    현재 상태에 대한 자세한 내용은 다음 문서를 참조하십시오 Configure agent presence states.

    데이터 유형: 문자열

    기본값: ""(빈 문자열)

    테이블: AWA 현재 상태[awa_presence_state]
    agent_sys_id 필수 작업 항목을 수신할 수 있는 에이전트의 Sys_id입니다. 에이전트는 awa_agent 역할이 있는 사용자입니다.

    에이전트를 사용할 수 있는지 확인하는 방법에 대한 자세한 내용은 에이전트 받은 편지함 컨트롤을 참조하십시오.

    데이터 유형: 문자열

    테이블: 사용자 [sys_user]
    allowed_to_decline 에이전트가 작업 항목을 거부할 수 있는지 여부를 나타내는 플래그입니다. 이 매개변수가 true이면 받은 편지함 카드에 수락 및 거부 버튼이 모두 표시됩니다.
    유효한 값은 다음과 같습니다.
    • 예/예/1: 에이전트가 작업 항목을 거부할 수 있습니다.
    • false/no/0: 에이전트가 작업 항목을 거부할 수 없습니다.

    데이터 유형: 부울

    기본값: true
    display_option 작업 항목이 자동으로 할당될 때 카드 및 탭에 대한 표시 옵션입니다.

    이 매개변수는 the enable_auto_assign 가 true로 전달된 경우에만 유효합니다.

    유효한 값은 다음과 같습니다.
    • card_and_tab: 카드와 탭을 모두 표시합니다.
    • card_only: 카드만 표시합니다.

    데이터 유형: 문자열

    기본값: card_only
    enable_auto_assign 작업 항목을 자동으로 수락해야 하는지 또는 에이전트가 작업 항목을 수동으로 수락하거나 거부할 수 있도록 허용해야 하는지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true/yes/1: 자동으로 수락합니다.
    • false/no/0: 에이전트가 수동으로 수락하거나 거부할 수 있도록 허용합니다.

    데이터 유형: 부울

    기본값: false
    offered_on 작업 항목 제공 시간입니다. 제공 시간은 에이전트가 받은 편지함의 작업 항목을 수락할 때까지 남은 남은 시간을 계산하는 데 사용됩니다. 이는 API 요청이 처리되는 시간과 타사 라우팅 시스템이 API 요청을 호출하는 시간 간의 불일치를 설명하는 데 도움이 됩니다. 이 매개 변수를 사용하면 이 엔드포인트를 호출하는 외부 시스템에서 작업 항목의 제공 시간을 구성하여 작업 항목에 대한 외부 시스템의 내부 추적과 동기화 상태를 유지할 수 있습니다.

    예를 들어 작업 항목이 11:30:30에 제공되고 시간 제한이 30초이고 현재 시간이 11:30:45인 경우 카운트다운 타이머는 00:15(남은 15초)를 표시합니다.

    이 값은 작업 항목의 offered_on 필드에 저장됩니다.

    매개 변수가 전달되지 않으면 이 매개 변수는 무시됩니다 timeout .

    데이터 유형: 문자열

    형식: UTC 타임스탬프(yyyy-MM-dd'T'HH:mm:ss. SSS)
    시간 제한 에이전트가 작업 할당을 수락할 때까지 작업 항목이 에이전트의 받은 편지함에 남아 있는 시간입니다.

    데이터 유형: 숫자

    단위: 초

    헤더

    다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 이 작업에 고유한 방식으로 적용됩니다. REST API에 사용되는 일반 헤더 목록은 지원되는 REST API 헤더를 참조하세요.

    표 4. 요청 헤더
    헤더 설명
    수용 응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다.

    기본값: application/json
    콘텐츠-형식 요청 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다.

    기본값: application/json
    표 5. 응답 헤더
    헤더 설명
    없음

    상태 코드

    다음 상태 코드는 이 HTTP 작업에 적용됩니다. REST API에서 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하세요.

    표 6. 상태 코드
    상태 코드 설명
    200 성공입니다. 요청이 성공적으로 처리되었습니다.
    401 승인되지 않았습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
    404 찾을 수 없습니다. 요청한 항목을 찾을 수 없습니다.
    409 상충됩니다. 제공된 작업 항목 또는 에이전트 sys_id 오류로 인해 요청을 통과할 수 없습니다.
    500 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다.

    응답 본문 매개변수(JSON 또는 XML)

    이름 설명
    성공 수동 작업 항목 할당이 성공했는지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 작업 항목 할당에 성공했습니다.
    • false: 작업 항목 할당에 실패했습니다.

    데이터 유형: 부울
    메시지 할당 성공 또는 예외를 확인하는 응답 메시지입니다.

    성공: "수동 할당이 성공적으로 요청되었습니다."

    예외:
    • "<work_item_sys_id> 유효한 작업 항목이 아님" – 제공된 작업 항목 sys_id 없습니다.
    • "호출자 <API_caller_sys_id>에 awa_manager 또는 awa_integration_user 역할이 없습니다." – API 요청을 하는 인증된 사용자는 awa_manager 또는 awa_integration_user 역할이 있어야 합니다.
    • "작업 항목 <work_item_sys_id> 할당할 수 없습니다." - 제공된 작업 항목이 수락 됨 또는 취소 됨 상태이므로 할당할 수 없습니다. 작업 항목 및 AWA 이벤트 확인을 참조하십시오.
    • "<agent_sys_id> 유효한 에이전트가 아닙니다." – 에이전트에 awa_agent 역할이 없습니다.
    • "작업 항목이 이미 <agent_sys_id>에 할당됨" - 제공된 작업 항목이 다른 에이전트에 할당되어 있습니다.
    • "에이전트를 사용할 수 없음" - 에이전트가 AWA에서 사용 가능한 상태가 아닙니다. 에이전트 받은 편지함 통제를 참조하십시오.
    • "시간 제한 값은 음수가 될 수 없습니다." - 제공된 시간 제한 값은 음수 값일 수 없습니다.
    • "<presence_state_sys_id> 유효한 현재 상태가 아님" – 제공된 현재 상태 sys_id가 AWA 현재 상태 [awa_presence_state] 테이블에 없습니다.
    • "제공된 시간(<offered_on_timestamp>)은 yyyy-MM-dd'T'HH:mm:ss 형식이어야 합니다. SSS" - 제공된 offered_on 타임스탬프는 지정된 형식이어야 합니다.
    • "제공된 시간(<offered_on_timestamp >)은 현재 시간 이전이어야 하며, 그렇지 않으면 에이전트가 작업 항목을 수락하는 데 더 많은 시간을 갖게 됩니다." - 제공된 offered_on 타임스탬프는 요청이 이루어진 시간 이전일 수 없습니다.
    • "시간 초과 후 타임스탬프(<offered_on_timestamp >)는 현재 시간 이후여야 하며, 그렇지 않으면 에이전트가 작업 항목을 수락할 시간이 없습니다." – 제공된 offered_on 타임스탬프에 시간 제한 값을 추가한 후의 타임스탬프는 요청이 이루어진 시간 이후여야 합니다.
    • "<display_option> is not a valid display option" – 제공된 display_option "card_only" 또는 "card_and_tab" 값 중 하나여야 합니다.
    • "%s은(는) 유효한 부울 값이 아닙니다." - 제공된 부울 형식 값은 "예"/"아니오", "예"/"아니오", "1"/"0" 부울 형식 중 하나여야 합니다.

    데이터 유형: 문자열

    cURL 요청

    다음 예제에서는 필수 매개변수만 사용하여 사용 가능한 AWA 에이전트에 작업 항목을 할당하는 방법을 보여줍니다.

    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'

    결과는 작업이 에이전트에 성공적으로 할당되었음을 보여줍니다. 작업 항목 [awa_work_item] 테이블의 할당 대상 필드에서 결과를 확인할 수 있습니다.

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

    cURL 요청

    다음 예제에서는 선택적 매개변수를 포함하여 사용 가능한 AWA 에이전트에 작업 항목을 할당하는 방법을 보여줍니다.

    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": "46d44a23a9fe19810012d100cca80666",
    "timeout":"10",
    "offered_on":"2024-04-03T23:09:31.000"
  }'
--user 'username':'password'

    결과는 작업이 에이전트에 성공적으로 할당되었음을 보여줍니다. 작업 항목 [awa_work_item] 테이블의 할당 대상 필드에서 결과를 확인할 수 있습니다.

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