service-omni-permission-set-assign

service-omni-permission-set-assign

PermissionSetAssignment Data API POST を介して、N 人のエージェントユーザーに 1 つ以上の PermissionSet を割り当てます。デフォルトの対象は Omni_Agent です。この権限セットは、OmniChannel ウィジェット、プレゼンスステータスへのアクセス、デモキューの表示を許可します。割り当てレコードがなければ、エージェントはウィジェットを開いたり、ルーティングされた作業を受け取ったりできません。SOQL ベースで検出するため、このスキルは不足している割り当てのみを作成します。エージェントユーザーは service-omni-agent-users-create で作成し、割り当てたエージェントがウィジェットを開いてステータスも選択できるように、service-omni-presence-status-deploy と併せて実行します。

入力

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

• org-alias（必須）。
• count（省略可、デフォルトは 3、範囲は 1..10）— エージェントユーザーの数と一致させる必要があります。
• permission-set-names-csv（省略可、デフォルトは Omni_Agent）— 複数の場合はカンマ区切りで指定します。各ユーザーにリストされたすべてのセットが割り当てられます（直積）：count=3 × 2 セット = 最大 6 件の割り当て。

前提条件と安全性

• 対象の組織が sf CLI で認証済みであり、Service Cloud ライセンスがあること。sf CLI は 2.139.6 以上であること。
• エージェントユーザーが存在すること（service-omni-agent-users-create）。数が一致しない場合は、このスキルを参照するよう案内して処理をブロックします。
• 実行ユーザーに PermissionsAssignPermissionSets があること（System Administrator に標準で付与されます）。組織管理者であっても必要です。ModifyAllData だけでは不十分です。
• Omni_Agent の自己修復を行う前に、少なくとも 1 つの Omni プレゼンスステータスが存在すること。バンドルされたセットは、デプロイ時に生成される servicePresenceStatusAccesses を介して、存在するキュレーション済みステータス（例：Available_Case／Available_Voice と Busy）に対するエージェント機能を付与します。先に service-omni-presence-status-deploy を実行してください。このため、コーディネーターはプレゼンスの後に権限セットを実行します。
• 3 要素の safe_to_write ガードが適用されます。本番組織で権限セットを割り当てると、実ユーザーの権限が昇格するおそれがあるため、上書き手段はなく、処理をブロックします。

自己修復（実行モードのみ）。 デフォルトの Omni_Agent セットが存在しない場合、このスキルはバンドルされた Omni_Agent メタデータを一度デプロイしてから割り当てます。--plan モードではデプロイせず、action_needed を報告して読み取り専用で終了します。これはバンドルされた Omni_Agent アセットのみが対象です。それ以外の権限セットは事前に存在している必要があり、存在しない場合はクリックパスを示して実行をブロックします。

実行

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

1. safe_to_write を計算し、8 文字の組織サフィックスを導出します。
2. agent{1..N}.<suffix>@example.com パターンでエージェントユーザーを特定します。ユーザーが 1 人でも見つからない場合は処理をブロックします。
3. 名前で各 PermissionSet を特定します。存在しない場合は Omni_Agent を自己修復し、それ以外は不足しているセットを明示して処理をブロックします。
4. （ユーザー × セット）の直積に対する既存の PermissionSetAssignment をクエリし、不足している組み合わせを算出します。
5. 不足している組み合わせごとに割り当てを 1 件 POST します（個別の POST であり、allOrNone は使用しません）。
6. 再クエリで最終状態を確認し、レポートを出力します。

動作

直積。 各ユーザーにリストされたすべてのセットが割り当てられます。一部のみの割り当ては機能ではなく失敗です。

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

非破壊。 このスキルは作成のみを行い、既存の割り当ては削除しません（ユーザーが他の管理者から個別に権限を付与されている場合があるため）。また、明示的なユーザー ID のリストを受け取らず、エージェントのパターンからユーザーを導出するため、実在する名前付きユーザーにデモ用の権限を割り当てることはありません。

出力契約

status が assigned | reused | partial | blocked のいずれかであり、解決済みの 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 を含む単一の JSON オブジェクトです。

• assigned — 少なくとも 1 件の新しい割り当てが作成され、すべての想定ペアが作成後に存在します。
• reused — すべての想定ペアがすでに存在しており、POST は行われません。
• partial — 一部の POST が失敗し、最終件数が想定件数を下回ります。
• blocked — 前提条件を満たしていません（本番組織、セットの不足、ユーザーの不足、権限の不足）。

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

制限事項

• 個別の PermissionSet のみを割り当てます。PermissionSetGroup は別の sObject であり、対象外です。
• 自己修復の対象は同梱の Omni_Agent のみです。汎用的な権限セット作成機能ではありません。
• 作成のみを行い、割り当ては削除しません。

参照資料

ファイル	読むタイミング
assets/package.xml	デフォルトの Omni_Agent 権限セットが見つからず、実行モードの自己修復パスで同梱メタデータをデプロイする必要がある場合に読み込みます
references/api-notes.md	POST ループの前。PermissionSetAssignment のスキーマ、その DUPLICATE_VALUE の動作、ユーザーが明示的な ID リストではなくエージェントのパターンから導出される理由を確認します