AWA 手動アサイン API

Xanadu API リファレンス

Release

xanadu

ft:locale

ja-JP

ft:publication_title

Xanadu API リファレンス

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

AWA 手動アサイン API

リリースバージョン: Xanadu

更新日 2024年08月01日

所要時間：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

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

表 : 1. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。たとえば、`v1` や `v2`。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列
work_item_sys_id	対応可能なエージェントにアサインする作業アイテムのsys_id。作業アイテム [awa_work_item] テーブルにあります。作業アイテムは未アサインであり、[受入処理待ち] または [キューに格納] ステータスである必要があります。詳細については、「未アサインタスク作業アイテムの確認」を参照してください。タイプ：文字列

表 : 2. クエリパラメーター
名前	説明
なし

表 : 3. 要求本文パラメーター (XML または JSON)
名前	説明
after_timeout_presence	timeoutパラメーターの有効期限が切れた場合にエージェントが切り替える在席ステータスのSys_id。AWA プレゼンスステータス [awa_presence_state] テーブルにあります。 timeout パラメーターが渡されない場合、このパラメーターは無視されます。在席状況の詳細については、「 Configure agent presence states」を参照してください。データタイプ：文字列デフォルト: "" (空の文字列)
agent_sys_id	必須です。作業アイテムを受け取ることができる利用可能なエージェントの sys_id。エージェントは、ユーザー [sys_user] テーブルの awa_agent ロールを持つユーザーです。エージェントが対応可能かどうかを判断する方法については、「エージェント受信ボックスのコントロール」を参照してください。データタイプ：文字列
allowed_to_decline	エージェントが作業アイテムを却下できるかどうかを示すフラグ。このパラメーターが `true` の場合、受信ボックスカードには [承認 ] ボタンと [却下 ] ボタンの両方が表示されます。有効な値 (値の大文字と小文字を区別しない)： true/yes/1:エージェントは作業アイテムを却下できます。 false/no/0:エージェントは作業アイテムを却下できません。データタイプ：ブーリアンデフォルト：true
display_option	作業アイテムが自動的にアサインされたときのカードとタブの表示オプション。このパラメーターは、 enable_auto_assign が `true` として渡された場合にのみ有効です。有効な値： card_only:カードのみを表示します。 card_and_tab:カードとタブの両方を表示します。データタイプ：文字列デフォルト: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
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：作業アイテムのアサインに失敗しました。データタイプ：ブーリアン
メッセージ	アサインの成功または例外を確認する応答メッセージ。成功:「手動割り当てが正常に要求されました。」例外：「<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 >) は現在の時間より前にする必要があります。そうしないと、エージェントが作業アイテムを受け入れる時間が長くなります」 - 指定した<c0/>タイムスタンプを要求が行われた時間より前にすることはできません。offered_on 「タイムアウト後のタイムスタンプ (<offered_on_timestamp >) は現在時刻より後にする必要があります。それ以外の場合、エージェントは作業アイテムを受け入れる時間がありません」 – 指定された<c0/>タイムスタンプにタイムアウト値を追加した後のタイムスタンプは、要求が行われた時刻より後である必要があります。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'

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