AWA アサイン API

  • リリースバージョン: Washingtondc
  • 更新日 2024年02月01日
  • 読む5読むのに数分

    • AWA アサイン API は、作業アイテムをエージェントに手動でアサインするためのエンドポイントを提供します。

    この API には 高度なワークアサインメント (com.glide.awa) プラグインと awa_manager ロールが必要です。

    作業アイテムは、AWA エージェントによって開始から終了まで処理される 1 件の作業のことです。たとえば、1 件のチャットまたは 1 件のケースは、エージェントにルーティングしてアサインできるオブジェクトになります。詳細については、「 Advanced Work Assignment」を参照してください。

    AWA 手動アサイン – POST /awa/workitems/{work_item_sys_id}/assignments

    利用可能な 高度なワークアサインメント エージェントに利用可能な作業アイテムをアサインします。

    このエンドポイントの主なユースケースは、外部ルーティングシステムが作業アイテムをルーティングできるようにすることです。高度なワークアサインメント が外部ルーティングを使用するように構成されている場合、キュー内の作業アイテムは AWA ではなく外部ルーティングを使用してアサインされます。このエンドポイントを呼び出すことで、作業アイテムタスクをアサインできます。詳細については、「 外部ルーティングの使用」を参照してください。

    URL 形式

    バージョニングされた URL：/now/{api_version}/awa/workitems/{sys_id}/assignments

    デフォルトの URL：/now/awa/workitems/{sys_id}/assignments

    サポートされている要求パラメーター

    表 : 1. パスパラメーター
    名前 説明
    api_version オプションアクセスするエンドポイントのバージョン。たとえば、v1 や v2。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。

    データタイプ：文字列
    work_item_sys_id 利用可能なエージェントにアサインする作業アイテムの sys_id。作業アイテム [awa_work_item] テーブルにあります。

    作業アイテムは未アサインであり、[受入処理待ち] または [キューに格納] ステータスである必要があります。詳細については、「 未割り当てタスク作業項目の確認」を参照してください。

    タイプ:文字列
    表 : 2. クエリパラメーター
    名前 説明
    なし
    表 : 3. 要求本文パラメーター (XML または JSON)
    名前 説明
    agent_sys_id 必須です。作業アイテムを受け取ることができる利用可能なエージェントの sys_id。エージェントは、ユーザー [sys_user] テーブルの awa_agent ロールを持つユーザーです。

    エージェントが利用可能かどうかを判断する方法については、 エージェントの受信ボックスの制御を参照してください。

    タイプ:文字列

    ヘッダー

    次のリクエストや応答ヘッダーは、この 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)

    名前 説明
    success

    手動作業アイテムのアサインが成功したかどうかを示すフラグ。

    有効な値：
    • true：作業アイテムのアサインに成功しました。
    • false：作業アイテムのアサインに失敗しました。

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

    デフォルト：True
    message アサインの成功または例外を確認する応答メッセージ。
    例外：
    • 「作業アイテムをアサインできません」 – 指定された作業アイテムは、[受け入れ済み] または [キャンセル] ステータスであるため、アサインできません。「作業アイテムと AWA イベントの確認」を参照してください。
    • 「<agent_sys_id> は有効なエージェントではありません」 – エージェントに awa_agent ロールがありません。
    • 「<work_item_sys_id> は有効な作業アイテムではありません」 – 指定された作業アイテム sys_id が存在しません。
    • 「作業アイテムは既に <work_item_sys_id> にアサインされています」 – 指定された作業アイテムが別のエージェントにアサインされています。
    • 「エージェントは利用できません」 – エージェントは AWA で [利用可能] ステータスではありません。エージェントの受信ボックスの制御を参照してください。

    データタイプ：文字列

    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"
  }
}