service-omni-permission-set-assign

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

service-omni-permission-set-assign

Assign one or more PermissionSets to N agent users via

PermissionSetAssignment

Data API POSTs. The default target is

Omni_Agent

, the permission set granting the OmniChannel widget, presence-status access, and demo-queue visibility — without an assignment row, agents cannot open the widget or receive routed work. Detection is SOQL-based, so the skill only creates the assignments that are missing. Agent users come from

service-omni-agent-users-create

, and it runs alongside

service-omni-presence-status-deploy

so assigned agents can both open the widget and select a status.

通过

PermissionSetAssignment

数据API的POST请求，为N个代理用户分配一个或多个PermissionSet。默认目标是

Omni_Agent

权限集，该权限集授予OmniChannel组件、在线状态访问权限以及演示队列可见性——如果没有分配记录，代理将无法打开组件或接收路由任务。检测基于SOQL实现，因此该技能仅创建缺失的权限分配。代理用户来自

service-omni-agent-users-create

服务，并且该服务会与

service-omni-presence-status-deploy

服务一同运行，以便已分配权限的代理既能打开组件，又能选择在线状态。

Inputs

输入参数

bash

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

```
org-alias
```
(required).
```
count
```
(optional, default
```
3
```
, range
```
1..10
```
) — must match the agent user count.
```
permission-set-names-csv
```
(optional, default
```
Omni_Agent
```
) — comma-separated for multiple. Every user gets every listed set (cross-product):
```
count=3
```
× 2 sets = up to 6 assignments.

bash

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个分配记录。

Preconditions and safety

前置条件与安全机制

Target org authenticated via
```
sf
```
CLI, Service Cloud license,
```
sf
```
CLI ≥ 2.139.6.
The agent users exist (
```
service-omni-agent-users-create
```
); a count mismatch blocks with a pointer back to that skill.
The executing user has
```
PermissionsAssignPermissionSets
```
(standard on System Administrator) — required even for org admins;
```
ModifyAllData
```
alone is insufficient.
At least one Omni presence status exists before
```
Omni_Agent
```
self-heals — the bundled set grants agent capability via
```
servicePresenceStatusAccesses
```
for whichever curated statuses exist (e.g.
```
Available_Case
```
/
```
Available_Voice
```
+
```
Busy
```
), generated at deploy time. Run
```
service-omni-presence-status-deploy
```
first; the coordinator sequences presence before permset for this reason.
The three-way
```
safe_to_write
```
guard applies — assigning permission sets on a production org can escalate a real user's privileges, so it blocks with no override.

Self-heal (run mode only). When the default

Omni_Agent

set is absent, the skill deploys the bundled

Omni_Agent

metadata once, then assigns. In

--plan

mode it never deploys — it reports

action_needed

and exits read-only. This covers only the bundled

Omni_Agent

asset; any other permission set must already exist or the run blocks with a click-path.

目标组织已通过
```
sf
```
CLI完成身份验证，拥有Service Cloud许可证，且
```
sf
```
CLI版本≥2.139.6。
代理用户已存在（由
```
service-omni-agent-users-create
```
服务创建）；如果数量不匹配，将阻止操作并提示回到该服务。
执行用户拥有
```
PermissionsAssignPermissionSets
```
权限（系统管理员默认拥有）——即使是组织管理员也需要该权限；仅拥有
```
ModifyAllData
```
权限是不够的。
在
```
Omni_Agent
```
权限集自修复前，至少存在一个Omni在线状态——捆绑的权限集通过
```
servicePresenceStatusAccesses
```
为部署时生成的所有预设状态（如
```
Available_Case
```
/
```
Available_Voice
```
+
```
Busy
```
）授予代理能力。请先运行
```
service-omni-presence-status-deploy
```
服务；出于此原因，协调器会先处理在线状态，再处理权限集。
启用三重
```
safe_to_write
```
防护机制——在生产组织中分配权限集可能会提升真实用户的权限，因此会直接阻止操作且无法覆盖。

自修复（仅运行模式） 当默认的

Omni_Agent

权限集不存在时，该技能会部署一次捆绑的

Omni_Agent

元数据，然后进行分配。在

--plan

模式下，它绝不会部署——只会报告

action_needed

并以只读模式退出。此功能仅覆盖捆绑的

Omni_Agent

资源；任何其他权限集必须已存在，否则运行将被阻止并提供操作路径。

Run

运行流程

verify-and-assign.sh

performs the whole cycle:

Compute
```
safe_to_write
```
; derive the 8-char org suffix.
Resolve the agent users by the
```
agent{1..N}.<suffix>@example.com
```
pattern; block if any are missing.
Resolve each
```
PermissionSet
```
by name; self-heal
```
Omni_Agent
```
if absent, else block naming which is missing.
Query existing
```
PermissionSetAssignment
```
for the (user × set) cross-product; compute the missing pairs.
POST one assignment per missing pair (individual POSTs, no
```
allOrNone
```
).
Re-query to confirm final state and emit the report.

verify-and-assign.sh

脚本执行完整流程：

计算
```
safe_to_write
```
值；提取8位字符的组织后缀。
通过
```
agent{1..N}.<suffix>@example.com
```
模式解析代理用户；如果有任何用户缺失，则阻止操作。
按名称解析每个
```
PermissionSet
```
；如果
```
Omni_Agent
```
缺失则进行自修复，否则阻止操作并指出缺失的权限集名称。
查询现有
```
PermissionSetAssignment
```
记录，获取（用户×权限集）的笛卡尔积；计算缺失的配对。
为每个缺失的配对发送一个POST请求（单独发送POST，不使用
```
allOrNone
```
参数）。
重新查询以确认最终状态并生成报告。

Behavior

行为特性

Cross-product. Every user gets every listed set; a partial assignment is a failure, not a feature.

Idempotency.

PermissionSetAssignment

has a database uniqueness constraint on (AssigneeId, PermissionSetId), so a re-POST raises

DUPLICATE_VALUE

; the skill detects existing pairs first and treats

DUPLICATE_VALUE

as a safety net for concurrent races. It POSTs individually so one duplicate or error never rolls back its successful siblings, and it re-queries after all POSTs — a 201 only means Salesforce accepted the write; a subsequent SOQL confirms the assignment is active.

Non-destructive. The skill is create-only; it never deletes existing assignments (users may hold out-of-band permissions from other admins) and derives users from the agent pattern rather than accepting an explicit user-id list, so it never assigns demo permissions to real named users.

笛卡尔积分配 每个用户都会获得列表中的所有权限集；部分分配视为失败，而非功能特性。

幂等性

PermissionSetAssignment

在（AssigneeId, PermissionSetId）上有数据库唯一性约束，因此重复POST会触发

DUPLICATE_VALUE

错误；该技能会先检测现有配对，并将

DUPLICATE_VALUE

视为并发竞争的安全防护。它单独发送每个POST请求，因此单个重复或错误不会回滚其他成功的请求，并且在所有POST完成后会重新查询——201状态码仅表示Salesforce接受了写入操作；后续的SOQL查询会确认分配是否生效。

非破坏性 该技能仅支持创建操作；绝不会删除现有分配记录（用户可能拥有其他管理员授予的额外权限），并且通过代理模式推导用户，而非接受显式的用户ID列表，因此绝不会将演示权限分配给真实的命名用户。

Output contract

输出约定

A single JSON object with

status

∈

assigned

reused

partial

blocked

, the resolved

permission_sets

org_suffix

requested_count

expected_assignment_count

requested_count × len(permission_sets)

), a

before

snapshot,

assigned_this_run

assigned_count

reused_count

, an

after

snapshot,

manual_actions

, and

blocking_issue

```
assigned
```
— at least one new assignment created; all expected pairs exist after.
```
reused
```
— all expected pairs already existed; nothing POSTed.
```
partial
```
— some POSTs failed; final count is below expected.
```
blocked
```
— precondition failed (production org, missing set, missing users, missing permissions).

assigned_count + reused_count == expected_assignment_count

unless

partial

;

blocking_issue

is non-null only for

blocked

partial

返回单个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

不为空。

Limitations

局限性

Assigns individual PermissionSets only — a
```
PermissionSetGroup
```
is a different sObject and is out of scope.
Self-heal covers only the bundled
```
Omni_Agent
```
; it is not a general-purpose permission-set authoring surface.
Create-only; it does not remove assignments.

仅支持分配单个PermissionSet —
```
PermissionSetGroup
```
是不同的sObject，不在本技能的范围内。
自修复仅覆盖捆绑的
```
Omni_Agent
```
权限集；它不是通用的权限集创建工具。
仅支持创建操作；不支持删除分配记录。

References

参考文档

File	When to read
`assets/package.xml`	Load when the default `Omni_Agent` permission set is missing and the run-mode self-heal path must deploy the bundled metadata
`references/api-notes.md`	Before the POST loop — PermissionSetAssignment schema, its `DUPLICATE_VALUE` semantics, and why users are derived from the agent pattern rather than an explicit id list

文件	阅读时机
`assets/package.xml`	当默认的 `Omni_Agent` 权限集缺失，且运行模式下的自修复路径需要部署捆绑元数据时阅读
`references/api-notes.md`	在执行POST循环前阅读——了解PermissionSetAssignment的架构、 `DUPLICATE_VALUE` 的语义，以及为何通过代理模式推导用户而非使用显式ID列表