service-omni-supervisor-permset-assign

service-omni-supervisor-permset-assign

Salesforce 提供の標準 ContactCenterSupervisor PermissionSet を、既存のスーパーバイザーユーザーに PermissionSetAssignment 経由で割り当てます。従来型の Omni-Channel Supervisor UI（Command Center）では、service-omni-supervisor-config-deploy でスーパーバイザーを紐付ける前に、スーパーバイザーがコンタクトセンターのスーパーバイザー権限を持っている必要があります。このスキルは、POST 前の検出による冪等性を確保し、DUPLICATE_VALUE は割り当て済みとして扱います。

ライセンス。 スーパーバイザーのシステム権限（IsContactCenterSupervisor、OmniSupervisorManageQueue、ViewOmnichnlAnlytDshbrd）は、権限セットライセンスによって制御されています。標準の ContactCenterSupervisor セットには独自のライセンス紐付けが含まれており、Service Cloud が有効な組織では問題なく割り当てられるため、これが既定のサポート対象の方法です。これらの権限を再宣言する手作業で作成したカスタムセットは、FIELD_INTEGRITY_EXCEPTION で失敗します。特定のユーザーのライセンスに基盤となる権利がない場合、割り当て時に同じ例外が発生するため、オペレーターはそのユーザーを該当する権利を持つプロファイル／ライセンスに変更できます。

このカスタム権限セットに関する警告は、Salesforce 提供の既存の ContactCenterSupervisor セットを割り当てるとアクセス権が削除されたり、セットが書き換えられたりするという意味ではありません。このスキルは、不足している PermissionSetAssignment のみを作成し、権限セット自体の作成、編集、置換は行いません。

入力

bash scripts/verify-and-assign.sh <org-alias> [count=1] [permission-set-names-csv=ContactCenterSupervisor]

• org-alias（必須）。
• count（任意、既定値 1、範囲 1..5）— スーパーバイザーユーザーの数と一致させる必要があります。
• permission-set-names-csv（任意、既定値 ContactCenterSupervisor）— 複数の場合はカンマ区切りで指定します。各スーパーバイザーに、指定したすべてのセットを割り当てます（直積）。

前提条件と安全性

• 対象組織が sf CLI で認証済みであり、Service Cloud ライセンスと sf CLI ≥ 2.139.6 を使用していること。
• スーパーバイザーユーザーが存在し、アクティブであること。アクティブユーザーが count 未満の場合は、対処方法を示すメッセージとともに処理をブロックします。
• ContactCenterSupervisor セットは Salesforce 提供のもので、Service Cloud が有効なすべての組織に存在します。存在しないカスタム名を指定した場合は、Setup のクリックパスを示して処理をブロックします。
• 実行ユーザーに PermissionsAssignPermissionSets があること（System Administrator では標準で付与されます）。組織管理者であっても必要です。
• 3 条件の safe_to_write 本番ガードが適用されます。本番組織での権限セット割り当ては実ユーザーの権限を昇格させる可能性があるため、上書き手段なしで処理をブロックします。

実行

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

1. safe_to_write を計算し、組織の 8 文字のサフィックスを取得します。
2. sf の呼び出し前に、指定されたすべての権限セット名が正しい形式の DeveloperName であることを検証します（SOQL インジェクション対策）。
3. supervisor{1..N}.<suffix>@example.com に一致するユーザーを IsActive=true で絞り込んで取得します。アクティブユーザーが count 未満の場合は処理をブロックします（非アクティブなユーザーは人数に含めません）。
4. 名前で各 PermissionSet を取得します。存在しないものがあれば、理由を示して処理をブロックします。
5. （ユーザー × セット）の直積に対する既存の PermissionSetAssignment をクエリし、不足している組み合わせを特定します。
6. 不足している組み合わせごとに個別の割り当てを POST します（allOrNone は使用しません）。DUPLICATE_VALUE は既存の割り当てとして扱います。
7. 再クエリして最終状態を確認し、レポートを出力します。

動作

直積。 各スーパーバイザーに、指定したすべてのセットを割り当てます。一部だけの割り当ては機能ではなく失敗です。

冪等性。 PermissionSetAssignment には（AssigneeId、PermissionSetId）の一意性制約があるため、再度 POST すると DUPLICATE_VALUE が発生します。このスキルは既存の組み合わせを先に検出し、同時実行に対する安全性を確保するため、重複を再利用として扱います。POST は個別に実行されるため、あるエラーによって他の割り当てがロールバックされることはありません。また、すべての POST 後に再クエリします。201 は書き込みが受け付けられたことを示すだけであり、有効になっていることは SOQL で確認します。

非破壊的。 作成のみを行います。スーパーバイザーが個別に付与された権限を保持している場合があるため、既存の割り当てを削除することはありません。また、明示的な ID リストではなく、スーパーバイザーのパターンからユーザーを特定します。

出力契約

status が assigned | reused | partial | blocked のいずれかである単一の JSON オブジェクト。解決済みの permission_sets、org_suffix、requested_count、expected_assignment_count（= requested_count × len(permission_sets)）、before スナップショット、assigned_this_run/assigned_count、reused_count、after スナップショット、manual_actions、blocking_issue を含みます。

• assigned — 少なくとも 1 件の新しい割り当てが作成され、予想されるすべてのペアが処理後に存在します。
• reused — 予想されるすべてのペアがすでに存在し、POST は行われませんでした。
• partial — 一部の POST が失敗し、最終件数が予想件数を下回っています。
• blocked — 前提条件を満たしていません（本番組織、セットの欠落、ユーザーの欠落／非アクティブ、または権限を許可しないライセンス）。

partial の場合を除き、assigned_count + reused_count == expected_assignment_count となります。blocking_issue が null 以外になるのは、blocked または partial の場合のみです。

制限事項

• スーパーバイザー用権限セットが必要とするユーザーライセンスのプロビジョニングは、このスキルではなく、ユーザー作成スキルの担当です。
• 個別の PermissionSet のみを割り当てます。PermissionSetGroup は別の sObject であり、対象外です。
• 作成のみです。割り当ての削除は行いません。

参考資料

ファイル	読むタイミング
references/api-notes.md	POST ループの前 — PermissionSetAssignment のスキーマ、DUPLICATE_VALUE の意味、明示的な ID リストではなくスーパーバイザーパターンからユーザーを導出する理由