AWA 受信ボックスアクション API

  • リリースバージョン: Zurich
  • 更新日 2025年07月31日
  • 所要時間：16分

    • AWA 受信ボックスアクション API は、エージェントの代わりに作業アイテムを承認または却下するためのエンドポイントを提供します。この API は、却下された作業アイテムの却下理由も取得します。

    この API には 高度な作業アサイン (com.glide.awa) プラグインと awa_integration_user ロールが必要です。詳細については、「 高度なワークアサインメント」を参照してください。

    AWA 受信ボックスアクション – GET /awa/inbox/actions/reject_reasons/{channel_id}

    指定されたサービスチャネルの作業アイテムの却下理由を取得します。

    URL 形式

    バージョニングされた URL：/api/now/awa/inbox/actions/reject_reasons/{channel_id}

    デフォルトの URL：/api/now/{api_version}/awa/inbox/actions/reject_reasons/{channel_id}

    注:
    利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

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

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

    データタイプ：文字列
    channel_id サービスチャネルのSys_id。

    データタイプ：文字列

    テーブル:サービスチャネル [awa_service_channel]
    表 : 2. クエリパラメーター
    名前 説明
    なし
    表 : 3. 要求本文パラメーター (XML または JSON)
    名前 説明
    なし

    ヘッダー

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

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

    デフォルト： application/json
    表 : 5. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 6. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400 要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
    401 権限がありません。ユーザー資格情報が間違っているか、渡されていません。
    403 禁止されています。
    考えられる理由:
    • ユーザーにawa_integration_userロールがない。
    • glide.awa.enabled プロパティの値が true ではありません。Advanced Work Assignment (com.glide.awa) プラグインがインストールされている場合、このプロパティはシステムのプロパティ [sys_property] テーブルにリストされます。詳細については、「 高度なワークアサインメントとともにインストールされるコンポーネント」を参照してください。
    404 レコードが見つかりません。指定されたチャネル ID が有効ではありません。
    500 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

    応答本文のパラメーター (JSON または XML)

    名前 説明
    display_value 却下理由 [awa_reject_reason] テーブルの Reason フィールドの値を表示します。

    データタイプ：文字列
    order 却下理由をエージェントの受信ボックスに表示する順序。

    データタイプ：数値
    value データベースに保存されている却下理由フィールドの値。

    データタイプ：文字列
    Sys_id このサービスチャネルの却下理由の sys_id。

    データタイプ：文字列

    テーブル:却下理由 [awa_reject_reason]

    次の例は、チャットサービスチャネルの却下理由を取得する方法を示しています。

    curl "https://instance.service-now.com/api/now/awa/inbox/actions/reject_reasons/27f675e3739713004a905ee515f6a7c3" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

    応答本文には、却下されたタスクが却下理由とともに表示されます。

    {
  "result": [
    {
      "order": 2,
      "value": "Not my expertise",
      "display_value": "Not my expertise",
      "sys_id": "31e3fa29b38023002e7b6e5f26a8dc17"
    },
    {
      "order": 1,
      "value": "Busy",
      "display_value": "Busy",
      "sys_id": "4e93fa29b38023002e7b6e5f26a8dc20"
    }
  ]
}

    AWA 受信ボックスアクション – POST /awa/inbox/actions/accept

    エージェントの代わりに [保留中の承認] ステータスの作業アイテムを承認します。

    URL 形式

    バージョニングされた URL：/api/now/{api_version}/awa/inbox/actions/accept

    デフォルトの URL：/api/now/awa/inbox/actions/accept

    注:
    利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

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

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

    データタイプ：文字列
    表 : 8. クエリパラメーター
    名前 説明
    なし
    表 : 9. 要求本文パラメーター (XML または JSON)
    名前 説明
    agent_id リストされているエージェントのSys_id。

    データタイプ：文字列

    テーブル： ユーザー [sys_user]
    work_item_id 作業アイテムのSys_id。
    作業アイテムは次の基準を満たしている必要があります。
    • 作業アイテムは、指定されたエージェントにアサインされている必要があります。
    • 作業アイテムは、[承認保留中] ステータスになっている必要があります。

    データタイプ：文字列

    テーブル:AWA 作業アイテム [awa_work_item]

    ヘッダー

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

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

    デフォルト： application/json
    表 : 11. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 12. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400 無効な要求。
    考えられる理由：
    • エージェント ID がありません。
    • 作業アイテム ID がありません。
    • 作業アイテムが別のエージェントにアサインされています。
    • 作業アイテムが承認待ち状態ではありません。
    401 権限がありません。ユーザー資格情報が間違っているか、渡されていません。
    403 禁止されています。
    考えられる理由:
    • ユーザーにawa_integration_userロールがない。
    • glide.awa.enabled プロパティの値が true ではありません。Advanced Work Assignment (com.glide.awa) プラグインがインストールされている場合、このプロパティはシステムのプロパティ [sys_property] テーブルにリストされます。詳細については、「 高度なワークアサインメントとともにインストールされるコンポーネント」を参照してください。
    500 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

    応答本文のパラメーター (JSON または XML)

    名前 説明
    documentTable この作業アイテムにアサインされたドキュメントをリストするテーブルの名前。

    データタイプ：文字列
    documentSysId タスクにアサインされたドキュメントレコードの sys_id。

    データタイプ：文字列

    テーブル: documentTable フィールドで識別されるテーブル内。
    エラー 要求プロセス中に発生したエラーを説明する詳細。

    データタイプ：オブジェクト

    "error": {
  "detail": "String",
  "message": "String"
}
    error.detail 要求プロセス中に発生したエラーの詳細。
    可能な値：
    • エージェント ID がありません:要求本文に agent_id が指定されていません。
    • 作業アイテム ID がありません:要求本文に work_item_id が指定されていません。
    • 作業アイテムが別のエージェントにアサインされています:指定された作業アイテムが指定されたエージェントにアサインされていません。
    • 誤った作業アイテム ID:要求本文で指定された作業アイテムが不正確であるか、存在しません。
    • 作業アイテムが承認待ちステータスではありません:要求本文で指定された作業アイテムは、[ 承認待ち] 以外のステータスです。

    データタイプ：文字列
    error.message 要求プロセス中に発生したエラーのメッセージ。説明は error.detail プロパティで提供されます。

    データタイプ：文字列
    status 失敗した要求のステータス。このプロパティは、エラーが発生した場合にのみ応答に含まれます。

    有効な値： failure

    データタイプ：文字列

    cURL 要求

    次の例は、選択したエージェントの作業アイテムのステータスを [受入処理待ち] から [受入済み] に変更する方法を示しています。

    curl "https://instance.service-now.com/api/now/awa/inbox/actions/accept" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
 \"agent_id\":\"46c9e158a9fe198101d44d0d22cb640d\",
 \"work_item_id\":\"fd69abfc878b01101ae365b83cbb35fe\"
}" \
--user 'username':'password'

    応答本文には、作業アイテムに関連するドキュメントの sys_id とテーブルがリストされます。

    {
  "result": {
    "documentSysId": "57af7aec73d423002728660c4cf6a71c",
    "documentTable": "incident"
  }
}

    AWA 受信ボックスアクション – POST /awa/inbox/actions/reject

    エージェントの代わりに [承認保留中] ステータスの作業アイテムを却下します。成功すると、[アサイン先] フィールドは空になり、指定された作業アイテムの [却下] フィールドの値は true になります。

    URL 形式

    バージョニングされた URL：/api/now/{api_version}/awa/inbox/actions/reject

    デフォルトの URL：/api/now/awa/inbox/actions/reject

    注:
    利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

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

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

    データタイプ：文字列
    表 : 14. クエリパラメーター
    名前 説明
    なし
    表 : 15. 要求本文パラメーター (XML または JSON)
    名前 説明
    agent_id リストされているエージェントのSys_id。

    データタイプ：文字列

    テーブル： ユーザー [sys_user]
    reject_reason_id このサービスチャネルの却下理由の sys_id。

    データタイプ：文字列

    テーブル:却下理由 [awa_reject_reason]
    work_item_id 作業アイテムのSys_id。
    作業アイテムは次の基準を満たしている必要があります。
    • 作業アイテムは、指定されたエージェントにアサインされている必要があります。
    • 作業アイテムは、[承認保留中] ステータスになっている必要があります。

    データタイプ：文字列

    テーブル:AWA 作業アイテム [awa_work_item]

    ヘッダー

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

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

    デフォルト： application/json
    表 : 17. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 18. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400 無効な要求。
    考えられる理由：
    • エージェント ID がありません。
    • 作業アイテム ID がありません。
    • 却下理由 ID がありません。
    • 作業アイテムが別のエージェントにアサインされています。
    • 作業アイテムが承認待ち状態ではありません。
    401 権限がありません。ユーザー資格情報が間違っているか、渡されていません。
    403 禁止されています。
    考えられる理由:
    • ユーザーにawa_integration_userロールがない。
    • glide.awa.enabled プロパティの値が true ではありません。Advanced Work Assignment (com.glide.awa) プラグインがインストールされている場合、このプロパティはシステムのプロパティ [sys_property] テーブルにリストされます。詳細については、「 高度なワークアサインメントとともにインストールされるコンポーネント」を参照してください。
    404 見つかりません。要求されたアイテムが見つかりませんでした。
    考えられる理由:
    • 誤ったエージェント ID：指定されたユーザーのレコードがありません。
    • 誤った却下理由 ID：指定された却下理由のレコードがありません。
    • 誤った作業アイテム ID：指定された作業アイテムのレコードがありません。
    500 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

    応答本文のパラメーター (JSON または XML)

    名前 説明
    agent_id リストされているエージェントのSys_id。

    データタイプ：文字列

    テーブル： ユーザー [sys_user]
    error 要求プロセス中に発生したエラーを説明する詳細。

    データタイプ：オブジェクト

    "error": {
  "detail": "String",
  "message": "String"
}
    error.detail 要求プロセス中に発生したエラーの詳細。
    可能な値：
    • エージェント ID がありません : agent_id 要求本文に指定されませんでした。
    • 却下理由アイテム ID がありません : reject_reason_id が要求本文に指定されませんでした。
    • 作業アイテム ID がありません:要求本文に work_item_id が指定されていません。
    • awa_reject_reasonのレコードがありません: <reason_sys_id> – 要求本文で指定された reject_reason_id には、却下理由 [awa_reject_reason] テーブルに一致するレコードがありません。
    • awa_work_itemのレコードがありません: <work_item_sys_id> – 要求本文で指定された work_item_id 、AWA 作業アイテム [awa_work_item] テーブルに一致するレコードがありません。
    • sys_userのレコードはありません: <agent_sys_id> – 要求本文で指定された agent_id には、ユーザー [sys_user] テーブルに一致するレコードがありません。
    • 作業アイテムが承認待ちステータスではありません:要求本文で指定された作業アイテムは、[ 承認待ち] 以外のステータスです。

    データタイプ：文字列
    error.message 要求プロセス中に発生したエラーのメッセージ。説明は error.detail プロパティで提供されます。

    データタイプ：文字列
    status 失敗した要求のステータス。このプロパティは、エラーが発生した場合にのみ応答に含まれます。

    有効な値： failure

    データタイプ：文字列
    reject_reason_id このサービスチャネルの却下理由の sys_id。

    データタイプ：文字列

    テーブル:却下理由 [awa_reject_reason]
    work_item_id 作業アイテムのSys_id。

    データタイプ：文字列

    次の例は、アサインされた作業アイテムを「専門知識がありません」という理由で却下する方法を示しています。

    curl "https://instance.service-now.com/api/now/awa/inbox/actions/reject" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    \"agent_id\":\"46c9e158a9fe198101d44d0d22cb640d\",
    \"work_item_id\":\"3ed5df4d87cf01101ae365b83cbb35af\",
    \"reject_reason_id\":\"31e3fa29b38023002e7b6e5f26a8dc17\"
}" \
--user 'username':'password'

    成功した出力には、要求本文で指定されたものと同じ作業アイテム、却下理由、およびユーザー ID が表示されます。AWA 作業アイテム [awa_work_item] テーブルの指定された作業アイテムの [アサイン先] フィールドは空で、[却下] フィールドの値は true です。

    {
  "result": {
    "work_item_id": "3ed5df4d87cf01101ae365b83cbb35af",
    "reject_reason_id": "31e3fa29b38023002e7b6e5f26a8dc17",
    "agent_id": "46c9e158a9fe198101d44d0d22cb640d"
  }
}