service-omni-supervisor-users-create

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

service-omni-supervisor-users-create

Create N supervisor users on a Salesforce org for the classic Omni-Channel Supervisor Configuration (

OmniSupervisorConfig

), which binds named user records via

OmniSupervisorConfigUser

. Users follow a deterministic

supervisor{i}.<suffix>@example.com

pattern so the coordinator can rediscover them across runs. It is the supervisor counterpart to

service-omni-agent-users-create

and shares its detection, password, and idempotency model; the only differences are the username/alias prefixes and the debug-log marker. Binding these users into a config (

service-omni-supervisor-config-deploy

) and granting them supervisor access (

service-omni-supervisor-permset-assign

) are separate leaves.

为Salesforce org上的经典Omni-Channel管理员配置（

OmniSupervisorConfig

）创建N个管理员用户，该配置通过

OmniSupervisorConfigUser

绑定指定用户记录。用户采用确定性的

supervisor{i}.<suffix>@example.com

命名模式，以便协调者在多次运行中重新识别这些用户。它是

service-omni-agent-users-create

的管理员对应工具，共享其检测、密码和幂等性模型；唯一区别在于用户名/别名前缀和调试日志标记。将这些用户绑定到配置（

service-omni-supervisor-config-deploy

）以及为其授予管理员权限（

service-omni-supervisor-permset-assign

）是独立的操作环节。

Inputs

输入参数

Confirm once, up front:

```
org-alias
```
(required, no default) — must resolve via
```
sf org display
```
.
Supervisor count (optional, default
```
1
```
, range
```
1..5
```
; the coordinator typically requests 1).
Profile name (optional, default
```
Standard User
```
). The coordinator overrides this to a Service Cloud profile so supervisors consume Service Cloud licenses; supervisor access itself comes from the standard
```
ContactCenterSupervisor
```
permission set assigned later.

Usernames and passwords are never accepted from the operator — both are generated (usernames from the org suffix, passwords via Anonymous Apex).

需预先确认以下参数：

```
org-alias
```
（必填，无默认值）——必须可通过
```
sf org display
```
解析。
管理员数量（可选，默认值为
```
1
```
，范围
```
1..5
```
；协调者通常请求创建1个）。
配置文件名称（可选，默认值为
```
Standard User
```
）。协调者会将其覆盖为Service Cloud配置文件，以便管理员占用Service Cloud许可证；管理员权限本身来自后续分配的标准
```
ContactCenterSupervisor
```
权限集。

用户名和密码从不接受操作员输入——两者均为自动生成（用户名基于org后缀生成，密码通过Anonymous Apex生成）。

Preconditions and safety

前置条件与安全机制

Target org authenticated via
```
sf
```
CLI (My Domain URL, not
```
.lightning.force.com
```
), Service Cloud license present,
```
sf
```
CLI ≥ 2.139.6.
The executing user has
```
PermissionsModifyAllData
```
and
```
PermissionsManagePasswordPolicies
```
(standard on System Administrator).
Production guardrail: the detect script computes
```
safe_to_write
```
as
```
IsSandbox
```
OR
```
TrialExpirationDate != null
```
OR
```
OrganizationType
```
in {Developer Edition, Base Edition}, and the skill blocks with no override when it is false. CDOs, scratch orgs, and dev orgs are permitted.

Password handling (fail-closed). Passwords are set by Anonymous Apex

System.setPassword

(

sf user password generate

cannot target Apex-inserted users). The literal appears in the inline executeAnonymous debug log and, only when a debug-log TraceFlag is active for the running user, in a queryable

ApexLog

. The wrapper therefore fails closed before the first

System.setPassword

: it proves via a SOQL-filtered Tooling API query (

ExpirationDate > now

) that no active TraceFlag exists. If safety cannot be positively proven, it sets no password at all; the user is left ACTIVE, flagged

password_status:"reset_required"

, and a

security_warning

explains why. It never deletes logs. A user whose password could not be set is kept ACTIVE and flagged for reset — never deactivated.

目标org已通过
```
sf
```
CLI认证（使用My Domain URL，而非
```
.lightning.force.com
```
），具备Service Cloud许可证，且
```
sf
```
CLI版本≥2.139.6。
执行用户拥有
```
PermissionsModifyAllData
```
和
```
PermissionsManagePasswordPolicies
```
权限（System Administrator默认具备）。
**生产环境防护：**检测脚本会计算
```
safe_to_write
```
值，当org为
```
IsSandbox
```
或
```
TrialExpirationDate != null
```
或
```
OrganizationType
```
属于{Developer Edition, Base Edition}时，该值为真。若值为假，工具会直接阻止操作且无覆盖选项。CDO、临时org和开发org允许使用。

密码处理（故障关闭机制）。密码通过Anonymous Apex的

System.setPassword

设置（

sf user password generate

无法针对通过Apex插入的用户执行操作）。密码明文会出现在内联executeAnonymous调试日志中，且仅当运行用户存在激活的调试日志TraceFlag时，才会出现在可查询的

ApexLog

中。因此，包装器会在首次执行

System.setPassword

前触发故障关闭：通过带SOQL过滤的Tooling API查询（

ExpirationDate > now

）验证是否存在激活的TraceFlag。若无法确认安全性，则完全不设置密码；用户状态会被设为ACTIVE，标记为

password_status:"reset_required"

，并通过

security_warning

说明原因。工具绝不会删除日志。无法设置密码的用户会保持ACTIVE状态并标记为需要重置——绝不会被停用。

Run

运行方式

bash

undefined

bash

undefined

read-only preview (never writes)

只读预览模式（永不写入数据）

bash scripts/detect-and-create.sh plan <org-alias> [count] [profile-name]

detect, enforce safe_to_write, then insert only the missing supervisors

检测、强制执行safe_to_write防护，仅插入缺失的管理员用户

bash scripts/detect-and-create.sh run <org-alias> [count=1] [profile-name="Standard User"]


`detect-and-create.sh` is the canonical entry point: it re-runs detection, enforces the production guard, and only then inserts. Do not call `scripts/run-create.sh` directly — it is internal and does not enforce the guard.

bash scripts/detect-and-create.sh run <org-alias> [count=1] [profile-name="Standard User"]


`detect-and-create.sh`是标准入口：它会重新执行检测、强制执行生产环境防护，之后才会执行插入操作。请勿直接调用`scripts/run-create.sh`——它是内部工具，不执行防护校验。

Behavior

行为逻辑

Detection. The detector derives an 8-char suffix from

Organization.Id

, resolves the profile by name, and queries

User

for

supervisor{i}.<suffix>@example.com

, splitting occupied slots into active

existing_users

and

inactive_users

Insertion. The Apex loads

assets/create-supervisors.apex.template

, substitutes

__COUNT__

__PROFILE_ID__

__SUFFIX__

, and inserts only the missing indexes, re-checking inside the transaction to prevent a single run from double-inserting; across concurrent runs this check is not a guarantee (both can pass their pre-query before either commits), so duplicate protection there relies on the global username-uniqueness constraint plus the

DUPLICATE_USERNAME

retry (see references/apex-template-notes.md). Created users get the Service Cloud feature (

UserPermissionsSupportUser=true

); if the profile's license does not allow it, the Apex strips the flag and retries (the permset assign will then block until the user is on a suitable license). Each created user is reported via

SUPERVISOR_CREATED|<id>|<username>|<email>

(no password in the marker — it is set by the separate

System.setPassword

submission).

Inactive occupants. An inactive user occupying a supervisor slot is not a reusable supervisor and cannot be recreated (usernames are globally unique). It is surfaced as a required manual reactivation and never counted toward the requested slots — counting it would under-provision the config.

Verification. After insertion the detector re-runs and must show

missing_count == 0

检测。检测器会从

Organization.Id

派生一个8字符后缀，按名称解析配置文件，并查询

User

对象以查找

supervisor{i}.<suffix>@example.com

，将已占用的账号分为活跃的

existing_users

和非活跃的

inactive_users

。

插入。Apex会加载

assets/create-supervisors.apex.template

，替换其中的

__COUNT__

__PROFILE_ID__

__SUFFIX__

，仅插入缺失索引的用户，并在事务内重新校验以避免单次运行重复插入；但对于并发运行，该校验无法提供保证（两个运行可能在提交前都通过了预查询），因此重复保护依赖全局用户名唯一性约束加上

DUPLICATE_USERNAME

重试机制（详见references/apex-template-notes.md）。创建的用户会启用Service Cloud功能（

UserPermissionsSupportUser=true

）；若配置文件的许可证不允许该功能，Apex会移除该标记并重试（之后的权限集分配会被阻止，直到用户切换到合适的许可证）。每个创建的用户会通过

SUPERVISOR_CREATED|<id>|<username>|<email>

报告（标记中不包含密码——密码由单独的

System.setPassword

操作设置）。

非活跃占用者。占用管理员账号槽位的非活跃用户无法作为可复用的管理员，也无法重新创建（用户名全局唯一）。工具会将其标记为需要手动重新激活，且绝不会将其计入请求的槽位数量——若计入则会导致配置资源不足。

验证。插入操作完成后，检测器会重新运行，必须显示

missing_count == 0

。

Output contract

输出约定

detect-and-create.sh

emits a single JSON object with

status

∈

created

partial

reused

action_needed

blocked

, plus

detect

create

(

null

when nothing was created),

created_count

reused_count

total_present_after

users_needing_password_reset

action_required

, and

safe_to_write

```
created
```
— every missing index landed with a working password.
```
partial
```
— some landed but not all, any
```
System.setPassword
```
failed (kept ACTIVE, listed in
```
users_needing_password_reset
```
), or a slot is occupied by an inactive user needing reactivation.
```
reused
```
— all requested slots already existed; no DML.
```
action_needed
```
— plan mode only.
```
blocked
```
— precondition failed.

create.created_users[].password

is populated only for users created this run whose

System.setPassword

succeeded.

create.rolled_back_users

is always empty (this skill never deactivates a user). Generated passwords are a secret: the returned JSON is the only place they appear; a caller that persists stdout must write it only to a restricted

CREDENTIALS.json

(mode 0600), redact it elsewhere, and delete it after distribution — the coordinator does this automatically.

detect-and-create.sh

会输出一个JSON对象，其中

status

的取值范围为

created

partial

reused

action_needed

blocked

，同时包含

detect

、

create

（无创建操作时为

null

）、

created_count

、

reused_count

、

total_present_after

、

users_needing_password_reset

、

action_required

和

safe_to_write

字段。

```
created
```
——所有缺失索引的用户均已创建且密码设置成功。
```
partial
```
——部分用户创建成功但并非全部，或存在
```
System.setPassword
```
操作失败的情况（用户保持ACTIVE状态，列于
```
users_needing_password_reset
```
中），或存在槽位被非活跃用户占用需要重新激活的情况。
```
reused
```
——所有请求的槽位均已存在；未执行任何DML操作。
```
action_needed
```
——仅在计划模式下出现。
```
blocked
```
——前置条件未满足。

仅当本次运行创建的用户且

System.setPassword

操作成功时，

create.created_users[].password

才会被填充。

create.rolled_back_users

始终为空（本工具绝不会停用用户）。生成的密码为敏感信息：返回的JSON是其唯一出现的位置；若调用者需要持久化标准输出，必须仅写入受限制的

CREDENTIALS.json

文件（权限模式0600），在其他地方需脱敏处理，并在分发后删除——协调者会自动执行这些操作。

Limitations

限制条件

Username pattern and org suffix are fixed and never operator-configurable — that determinism is what enables idempotent re-runs.
Creates only supervisor users; it never deletes or deactivates users, including orphaned supervisors from prior runs.
Common User errors (
```
DUPLICATE_USERNAME
```
,
```
INVALID_EMAIL
```
,
```
LICENSE_LIMIT_EXCEEDED
```
) are translated into operator-friendly messages rather than surfaced raw.

用户名模式和org后缀是固定的，不支持操作员配置——这种确定性是实现幂等性重复运行的基础。
仅创建管理员用户；绝不会删除或停用用户，包括之前运行遗留的孤立管理员。
常见的用户错误（
```
DUPLICATE_USERNAME
```
、
```
INVALID_EMAIL
```
、
```
LICENSE_LIMIT_EXCEEDED
```
）会转换为操作员友好的提示信息，而非直接暴露原始错误。

References

参考文档

File	When to read
`references/apex-patterns.md`	Before running the Apex — Apex structure, User field defaults, password policy, and the profile-localization risk
`references/apex-template-notes.md`	When creation returns a duplicate, license, password, or trace-safety error
`assets/create-supervisors.apex.template`	Loaded by `scripts/run-create.sh` when missing supervisor users must be inserted
`scripts/detect-existing.sh`	Loaded by `scripts/detect-and-create.sh` for the read-only org, profile, safety, and existing-user checks
`scripts/run-create.sh`	Internal writer loaded by `scripts/detect-and-create.sh` only after guard checks pass

文件	阅读时机
`references/apex-patterns.md`	运行Apex前——了解Apex结构、用户字段默认值、密码策略和配置文件本地化风险
`references/apex-template-notes.md`	当创建操作返回重复、许可证、密码或跟踪安全错误时
`assets/create-supervisors.apex.template`	当需要插入缺失的管理员用户时，由 `scripts/run-create.sh` 加载
`scripts/detect-existing.sh`	由 `scripts/detect-and-create.sh` 加载，用于只读org校验、配置文件校验、安全校验和现有用户校验
`scripts/run-create.sh`	内部写入工具，仅在防护校验通过后由 `scripts/detect-and-create.sh` 加载