service-omni-permission-set-assign

service-omni-permission-set-assign

通过 PermissionSetAssignment Data API POST 请求，为 N 个 Agent 用户分配一个或多个 PermissionSet。默认目标是 Omni_Agent，该权限集授予 OmniChannel 小组件、在线状态访问权限和演示队列可见性——没有分配记录，Agent 就无法打开小组件或接收路由的工作。检测基于 SOQL，因此此技能只会创建缺失的分配。Agent 用户来自 service-omni-agent-users-create；此技能与 service-omni-presence-status-deploy 配合运行，让已分配权限的 Agent 既能打开小组件，也能选择状态。

输入

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

• org-alias（必需）。
• count（可选，默认值为 3，范围为 1..10）——必须与 Agent 用户数量一致。
• permission-set-names-csv（可选，默认值为 Omni_Agent）——多个权限集以逗号分隔。每个用户都会获得所有列出的权限集（笛卡尔积）：count=3 × 2 个权限集 = 最多 6 项分配。

前提条件和安全性

• 目标组织已通过 sf CLI 验证身份，具备 Service Cloud 许可证，且 sf CLI 版本 ≥ 2.139.6。
• Agent 用户已存在（service-omni-agent-users-create）；数量不匹配时会阻止执行，并提示返回该技能。
• 执行用户拥有 PermissionsAssignPermissionSets（System Administrator 通常默认具备）——即使是组织管理员也必须拥有此权限；仅有 ModifyAllData 不够。
• 在 Omni_Agent 自动修复之前，至少要存在一个 Omni 在线状态。随附的权限集会通过 servicePresenceStatusAccesses 授予 Agent 能力，适用于当前存在的已精选状态（例如 Available_Case/Available_Voice 和 Busy），并在部署时生成。请先运行 service-omni-presence-status-deploy；协调器会因此先执行在线状态部署，再执行权限集分配。
• 三项 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 模式查找 Agent 用户；如果有用户缺失，则阻止执行。
3. 按名称查找每个 PermissionSet；如果 Omni_Agent 不存在，则自动修复，否则阻止执行并指出缺失的权限集。
4. 查询（用户 × 权限集）笛卡尔积中现有的 PermissionSetAssignment；计算缺失的配对。
5. 对每个缺失配对 POST 一项分配（逐项 POST，不使用 allOrNone）。
6. 重新查询以确认最终状态并生成报告。

行为

笛卡尔积。 每个用户都会获得所有列出的权限集；部分分配属于失败，而不是功能。

幂等性。 PermissionSetAssignment 对（AssigneeId、PermissionSetId）设有数据库唯一性约束，因此重新 POST 会引发 DUPLICATE_VALUE；此技能会先检测已有配对，并将 DUPLICATE_VALUE 作为并发竞态的安全保障。它会逐项 POST，因此一项重复或出错都不会回滚其他成功项；所有 POST 完成后，它会重新查询——201 仅表示 Salesforce 接受了写入，后续 SOQL 查询才能确认分配已生效。

非破坏性。 此技能仅创建分配，从不删除现有分配（用户可能持有其他管理员在技能之外授予的权限）；它会根据 Agent 模式推导用户，而不接受明确的用户 ID 列表，因此绝不会将演示权限分配给使用真实姓名的用户。

输出约定

单个 JSON 对象，包含 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。

• assigned — 至少创建了一项新分配；所有预期的配对在完成后均已存在。
• reused — 所有预期的配对此前均已存在；未执行任何 POST。
• partial — 部分 POST 失败；最终数量低于预期。
• blocked — 前置条件未满足（生产组织、缺少权限集、缺少用户、缺少权限）。

除 partial 外，assigned_count + reused_count == expected_assignment_count；仅当状态为 blocked 或 partial 时，blocking_issue 才非空。

限制

• 仅分配单个 PermissionSet；PermissionSetGroup 是不同的 sObject，不在范围内。
• 自愈仅适用于随附的 Omni_Agent；这不是通用的权限集编写界面。
• 仅创建；不会移除分配。

参考资料

文件	何时阅读
assets/package.xml	默认的 Omni_Agent 权限集缺失，且运行模式下的自愈路径必须部署随附元数据时加载
references/api-notes.md	POST 循环之前 — PermissionSetAssignment 架构、其 DUPLICATE_VALUE 语义，以及为何根据 Agent 模式推导用户，而非使用显式 ID 列表