service-omni-queue-members-assign

service-omni-queue-members-assign

GroupMember Data API POST を通じて、N 人のエージェントユーザーを Salesforce Queue に追加します。キューのメンバーでない場合、Omni-Channel ルーティングではそのキューの候補が空と見なされ、作業が割り当てられません。検出には SOQL を使用するため（service-omni-queue-routing-config-deploy と同じ検出後に POST する形式）、不足しているメンバーのみが作成され、このスキルは安全に再実行できます。エージェントユーザーは service-omni-agent-users-create から、キューは service-omni-queue-deploy から、ユーザーの Omni 権限は service-omni-permission-set-assign から取得します。

入力

bash scripts/verify-and-bind.sh <org-alias> [queue-developer-name=CaseQueue] [count=3] [explicit-members-csv]
# demo agents (default):
bash scripts/verify-and-bind.sh myorg CaseQueue 3
# real agents by username/id:
bash scripts/verify-and-bind.sh myorg VoiceQueue "" "[email protected],005XX000001abcd"

• org-alias（必須）。
• queue-developer-name（任意、デフォルトは CaseQueue）。
• count（任意、デフォルトは 3、範囲は 1..10）— エージェントユーザー数と一致させる必要があります。明示モードでは無視されます。
• explicit-members-csv（任意の第 4 位置引数、または MEMBER_USERNAMES_CSV / MEMBER_USER_IDS_CSV）— 各トークンはユーザー名または 15／18 文字のユーザー ID です。件数はリストから算出されます。

前提条件と安全性

• 対象組織が sf CLI（My Domain URL）で認証済みであること、Service Cloud ライセンスがあること、sf CLI のバージョンが 2.139.6 以上であること。
• 実行ユーザーに PermissionsModifyAllData があること（標準ではシステム管理者に付与されています）。
• エージェントユーザー（service-omni-agent-users-create）とキュー（service-omni-queue-deploy）が存在すること。不足しているユーザーセットまたはキューがある場合は、適切なスキルを案内して処理をブロックします（Data API ではキューを作成できません）。
• 3 段階の safe_to_write 本番環境ガードが適用されます。本番キューにユーザーを追加すると実際の顧客業務のルーティングが誤るため、上書き手段なしでブロックされます。

実行

verify-and-bind.sh は一連の処理を実行します。

1. safe_to_write を計算し、8 文字の組織サフィックスを導出します。
2. DeveloperName と Type='Queue' を条件に、キューの Group.Id を解決します。見つからない場合はブロックします。
3. メンバーセットを解決します。生成モードでは agent{1..N}.<suffix>@example.com に一致する User をクエリし、想定されるユーザーが 1 人でも見つからない場合はブロックします。明示モードでは、指定された各トークンを解決し、すべてが ACTIVE ユーザーであることを必須とします。
4. キューの既存の GroupMember をクエリし、まだ追加されていないユーザーを算出します。
5. 不足しているユーザーごとに GroupMember を 1 件 POST します（個別の POST であり、allOrNone は使用しません）。
6. 再クエリして最終的なメンバー構成を確認し、レポートを出力します。

動作

2 つのメンバーソースを混在させません。 デフォルトの生成パターンでは、ユーザー作成からメンバー追加への引き継ぎが決定的になります。明示モードは実際のエージェント向けのオプトイン方式で、件数の算出もこのモードに切り替わります。明示モードでトークンがアクティブユーザーに解決されない場合、実行はブロックされます。入力ミスのあるユーザーや非アクティブユーザーを追加すると、キューのメンバー数が不足しても気づけないためです。

冪等性と正確性。 POST は個別に行うため、あるユーザーの追加が失敗しても（たとえば別の管理者との競合など）、成功した他の追加が取り消されることはありません。また、スキルはすべての POST の後に再クエリします。201 は書き込みが受け付けられたことを意味するだけであり、後続の SOQL によって、その行がルーティングエンジンから参照できることを確認します。before スナップショットには、すでに存在するメンバー（別の手段で追加されたデモ以外のユーザーも含む）が記録されるため、コーディネーターはメンバー構成全体を確認できます。

非破壊的。 作成のみを行い、既存のメンバーを削除したり、再割り当てしたりすることはありません。

出力仕様

status が bound | reused | partial | blocked のいずれかである単一の JSON オブジェクトを出力します。これには、解決された queue、org_suffix、member_source（generated_pattern | explicit）、requested_count、before スナップショット、bound_this_run／bound_count、reused_count、after スナップショット、manual_actions、blocking_issue が含まれます。

• bound — 1 人以上の新しいメンバーが作成され、最終状態が想定件数と一致しています。
• reused — 想定されるユーザーがすでに全員メンバーであり、POST は行われていません。
• partial — 一部の POST が失敗し、再クエリの結果、メンバー数が要求数に達していません（詳細は blocking_issue を参照）。
• blocked — 前提条件を満たしていません（本番組織、キューの欠落、ユーザーの欠落、権限の不足）。

partial でない限り、bound_count + reused_count == requested_count です。blocking_issue が null 以外になるのは、blocked または partial の場合のみです。

制限事項

• 1 回の実行では、生成モードと明示モードを併用できません。
• 作成のみ対応しています。メンバーの削除や割り当て変更は対象外です。
• キューやユーザーは作成せず、権限セットやプレゼンス設定も割り当てません。

参考資料

ファイル	確認するタイミング
references/api-notes.md	検出／バインドのサイクルを開始する前。GroupMember スキーマ、キューと公開グループの違い、UserOrGroupId が多相型である理由、よくある POST の失敗について記載されています
scripts/tests/test_queue_members_contracts.py	変更を検証するとき。このスキルのディレクトリから python3 scripts/tests/test_queue_members_contracts.py を実行してください