service-omni-queue-routing-config-deploy

service-omni-queue-routing-config-deploy

Data API を使用して QueueRoutingConfig を作成または更新します。このレコードは、キュー上のエージェントに Omni-Channel が作業を配分する方法を指定します。ルーティングモデル（ラウンドロビン方式の MostAvailable、負荷分散方式の LeastActive）、各作業項目が消費するキャパシティ（CapacityWeight または CapacityPercentage）、プッシュのタイムアウト、ルーティングの優先度を設定します。これは Omni ルーティングされた Queue の前提条件です。service-omni-queue-deploy は、このスキルが返す設定の Id をキューに関連付けます。DeveloperName で検出するため、このスキルは新規レコードを POST するか、既存レコードを PATCH して値を一致させます。安全に再実行できます。

入力

bash scripts/upsert-and-report.sh <org-alias> [routing-model] [developer-name] [master-label] [capacity-weight] [routing-priority] [overflow-assignee] [push-timeout]
# Case_Routing_Config, preserve model / create MostAvailable:
bash scripts/upsert-and-report.sh myorg
# align the Case QRC to LeastActive:
bash scripts/upsert-and-report.sh myorg LeastActive
# Voice_Routing_Config (coordinator path):
QRC_ROUTING_TARGET=VoiceCall bash scripts/upsert-and-report.sh myorg
# set a fallback/overflow assignee (route overflow work to a supervisor):
[email protected] bash scripts/upsert-and-report.sh myorg
# Voice uses 100% capacity and a 30-second push timeout:
QRC_ROUTING_TARGET=VoiceCall QRC_CAPACITY_PERCENTAGE=100 QRC_PUSH_TIMEOUT=30 bash scripts/upsert-and-report.sh myorg MostAvailable

• org-alias（必須）。
• routing-model（省略可、または ROUTING_MODEL_INPUT）— MostAvailable | LeastActive。省略した場合、既存レコードのモデルはそのまま維持され、新規レコードは MostAvailable で作成されます。指定した場合は、作成時に書き込まれ、既存レコードの値も一致するように更新されます。
• developer-name / master-label / capacity-weight（1..100） / routing-priority（≥1）— routing-model の後に位置引数として指定するか、QRC_DEVELOPER_NAME / QRC_MASTER_LABEL / QRC_CAPACITY_WEIGHT / QRC_ROUTING_PRIORITY で指定します。ラベル、重み 5、優先度 1 は、新規レコードを作成する場合にのみデフォルトとして使われます。省略した値は既存レコードでそのまま維持されます。
• QRC_CAPACITY_PERCENTAGE（省略可、0..100）— 重みの代わりに割合でキャパシティを指定します。明示的に指定したキャパシティの重みとは併用できません。モードを切り替えると、以前のもう一方のフィールドはクリアされます。
• overflow-assignee（省略可。7 番目の位置引数、または QRC_OVERFLOW_ASSIGNEE）— キューのメンバー全員が対応できない場合に作業を受け取る予備の User（Username または 005 Id）です（OverflowAssigneeId）。書き込み前に有効な User Id に解決されます。省略した場合、既存レコードのオーバーフロー設定はそのまま維持され、新規レコードには設定されません。
• push-timeout（省略可。8 番目の位置引数、または QRC_PUSH_TIMEOUT、0..3600 秒）— プッシュされた作業をエージェントが承諾するまで Omni が待機する時間です。省略した場合、既存の値はそのまま維持されます。
• QRC_ROUTING_TARGET（環境変数）— Case | VoiceCall | Incident | MessagingSession。標準の命名デフォルトを選択します。service-omni-channel-setup-coordinate は、対象ごとにこの値を設定します。

前提条件と安全性

• 対象の組織が sf CLI で認証済みであること（My Domain URL）。Service Cloud ライセンスと sf CLI ≥ 2.139.6 が必要です。
• Omni-Channel の基本設定が有効であること（service-omni-base-settings-configure）。有効でない場合、QueueRoutingConfig への書き込みはできません（INVALID_TYPE）。
• 本番環境向けの 3 要素 safe_to_write ガードが適用されます。

実行

upsert-and-report.sh は検出 → upsert → 検証を実行します。

1. QueueRoutingConfig WHERE DeveloperName = '<target-derived-or-explicit>' をクエリし、既存の Id とフィールド値を取得します。
2. 要求された値または標準値と比較します。
3. レコードが存在しない場合は新しいレコードを POST します。すべてのフィールドがすでに一致している場合は何もせず（reused）、フィールドに差異がある場合は PATCH します。
4. 再クエリして最終状態を確認し、不一致が見つかった場合は停止します。

動作

ターゲットに基づく命名。 明示的な名前が指定されていない場合、DeveloperName はルーティングターゲット（Case_Routing_Config、Voice_Routing_Config など）に従います。そのため、再実行時やコーディネーターによる実行時にも同じレコードに収束し、重複レコードが並行して作成されることはありません。

不要な変更より既存値の維持を優先。 既存レコードでは、省略されたルーティングモデル、ラベル、ルーティング優先度、容量モード／値、オーバーフロー担当者、プッシュタイムアウト、属性ベースのフラグは維持されます。デフォルト（MostAvailable、ターゲットに基づくラベル、重み 5、優先度 1、属性ベースではない）は、新規レコードにのみ適用されます。容量にはいずれか一方のモードだけを使用します。重みからパーセンテージへ、またはその逆へ明示的に変更する場合、競合する容量設定がレコードに残らないよう、古い側のフィールドをクリアします。

フォールバック／オーバーフロールーティング。 QueueBased モデルでの「フォールバック」は、キューのオーバーフロー担当者を指します。これは、キューのメンバーが誰も対応可能でない場合に作業を受け取るユーザーであり、項目が無期限にキューに残ることを意味するものではありません。エージェントの対応可否は非同期の Omni 判定であり、ルーティングフローでは確認できないため、フローではなく QueueRoutingConfig に設定します。overflow-assignee が指定された場合、このスキルはそれを有効なユーザーに解決します（オーバーフロー先のユーザーが無効だと作業が気付かれないまま滞留するため、不明なユーザーまたは無効なユーザーの場合は処理をブロックします）。続いて OverflowAssigneeId を書き込み、書き込み後に値が一致することを検証します。

読み戻しによる報告。 報告するすべてのフィールド値は、入力値をそのまま返すのではなく、書き込み後に組織へ再クエリして取得します（values_source: "requeried"）。201／204 は書き込みが受け付けられたことを意味するだけです。このスキルは QueueRoutingConfig を削除しません（キュー、エージェント、作業スキルがその Id を参照している場合があるため）。常に PATCH で値を整合させます。

出力仕様

単一の JSON オブジェクトを返します。status は created、reused、updated、blocked のいずれかで、さらに routing_target、developer_name、id、master_label、routing_model、routing_priority、capacity_mode、capacity_weight、capacity_percentage、is_attribute_based、push_timeout、overflow_assignee_id、overflow_assignee_requested、values_source、before スナップショット、manual_actions、blocking_issue を含みます。

• created — レコードが存在せず、POST が成功しました。
• reused — すべてのフィールドが一致するレコードが存在し、変更はありません。
• updated — レコードは存在しましたが、フィールドに差異があり、PATCH が成功しました。
• blocked — 前提条件を満たしませんでした（Omni が有効でない、本番組織である、書き込み後に不一致があった、または overflow-assignee が有効なユーザー 1 人に解決されなかった）。

before.existed は、開始時に一致するレコードが存在したかどうかを記録します（存在した場合は、その時点の capacity_weight／routing_model も記録します）。id は blocked 以外のすべてのステータスで設定されます。blocking_issue は blocked の場合にのみ null 以外の値になります。

制限事項

• 属性ベースのルーティング（IsAttributeBased=true）は対象外です。追加の属性スキーマが必要です。
• v66 でサポートされるのは MostAvailable と LeastActive のみです。
• チャネルごとの容量比重付けは v66 で非推奨です（service-omni-service-channel-configure を参照）。エージェントごとの容量合計は別の場所で設定します。

参考資料

ファイル	参照するタイミング
references/api-notes.md	想定外のエラーが発生した場合、またはフィールドをカスタマイズする場合 — QueueRoutingConfig のスキーマ、RoutingModel のセマンティクス、CapacityWeight とエージェントの容量との関係
scripts/tests/test_queue_routing_config_contracts.py	変更を検証する場合 — このスキルのディレクトリから python3 scripts/tests/test_queue_routing_config_contracts.py を実行します