AWA 手動アサイン API

  • リリースバージョン: Australia
  • 更新日 2026年03月12日
  • 所要時間：11分

    • AWA 手動アサイン API は、利用可能な作業アイテムを利用可能な 高度な作業アサイン (AWA) エージェントに手動でアサインするためのエンドポイントを提供します。

    作業アイテムは、 AWA エージェントによって最初から最後まで処理される 1 つの作業です。たとえば、1 つのチャットまたは 1 つのケースは、ルーティングしてエージェントにアサインできるオブジェクトです。詳細については、「 高度なワークアサインメント」を参照してください。

    この 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 の場合、受信ボックスカードの受信ボックスカードには [承認 ] ボタンと [ 却下 ] ボタンの両方が表示されます。
    有効な値：
    • true/yes/1:エージェントは作業アイテムを却下できます。
    • false/no/0:エージェントは作業アイテムを却下できません。

    データタイプ：ブーリアン

    デフォルト：true
    display_option 作業アイテムが自動的にアサインされるときのカードとタブの表示オプション。

    このパラメーターは、 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 の場合、カウントダウンタイマーには (残り 15 秒と同様) 00:15 と表示されます。

    この値は、作業アイテムの [offered_on] フィールドに格納されます。

    timeoutパラメーターが渡されない場合、このパラメーターは無視されます。

    データタイプ：文字列

    形式:UTC タイムスタンプ (yyyy-MM-dd'T'HH:mm:ss.SSS)
    timeout エージェントがワークアサインメントを受け入れるのを待機して、作業アイテムをエージェントの受信ボックスに保持する時間。

    データタイプ：数値

    単位：秒

    ヘッダー

    次の要求ヘッダーと応答ヘッダーは、この HTTP アクションにのみ適用されるか、別の方法でこのアクションに適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 4. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    Content-Type 要求本文のデータ形式。サポートされるタイプ：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>は有効な表示オプションではありません」:指定されたdisplay_optionは、「card_only」または「card_and_tab」のいずれかの値である必要があります
    • "%s is not a valid boolean value" – 指定されたブール型の値は、次のいずれかのブール形式である必要があります:「yes」/「no」、「true」/「false」、「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."
  }
}