service-omni-agent-users-create

service-omni-agent-users-create

通过 Anonymous Apex 在 Salesforce 组织中创建 N 个 Agent 用户，让 Omni-Channel 有可分配工作的 Agent。用户名遵循按组织确定的模式，通过 SOQL 检测，且此技能仅插入缺少的用户，因此可以安全地重复运行。service-omni-base-settings-configure 启用 Omni-Channel 后，由 service-omni-channel-setup-coordinate 调用此技能；分配权限集（service-omni-permission-set-assign）和将用户添加到队列（service-omni-queue-members-assign）是单独的叶节点。主管用户由 service-omni-supervisor-users-create 创建。

输入

开始时一次性确认：

• org-alias（必需，无默认值）——必须能够通过 sf org display 解析。
• 用户数量（可选，默认值为 3，范围为 1..10）。
• 配置文件名称（可选，默认值为 Standard User，以提高可移植性）。协调器会将其覆盖为 Service Cloud 配置文件，这样 Agent 会占用 Service Cloud 许可证；在许多 CDO 中，Salesforce 许可证池已满，而 Service Cloud 仍有空闲名额。

不会接受操作员提供的用户名和密码——两者都会自动生成（用户名根据组织后缀生成，密码通过 Anonymous Apex 生成）。由操作员提供的凭据会破坏重复运行检测，并带来弱密码或密钥泄露风险。

前提条件与安全性

• 目标组织已通过 sf CLI 认证（使用 My Domain URL，而非 .lightning.force.com），且有 Service Cloud 许可证；sf CLI 版本 ≥ 2.139.6。
• 执行用户具有 PermissionsModifyAllData 和 PermissionsManagePasswordPolicies 权限（System Administrator 的标准权限）。
• **生产环境防护机制：**检测脚本会将 safe_to_write 计算为 IsSandbox OR TrialExpirationDate != null OR OrganizationType 属于 {Developer Edition、Base Edition}；如果结果为 false，技能会阻止操作，且不提供绕过选项。CDO、临时组织和开发组织均允许操作。

**密码处理（失败时默认拒绝）。**密码通过 Anonymous Apex 的 System.setPassword 设置（sf user password generate 无法针对通过 Apex 插入的用户——会失败并报错 NamedOrgNotFoundError）。密码字面值会出现在 inline executeAnonymous 调试日志中；只有当运行用户存在活动的调试日志 TraceFlag 时，才会出现在可查询的 ApexLog 中。因此，包装器会在首次调用 System.setPassword 之前失败时默认拒绝：通过经过 SOQL 筛选的 Tooling API 查询（ExpirationDate > now），确认不存在活动的 TraceFlag。如果无法确切证明安全——运行用户无法解析、查询失败或结果无法解析，或者存在任何活动的 TraceFlag——则完全不会生成密码；用户将保持 ACTIVE，并标记为 password_status:"reset_required"，同时通过 security_warning 说明原因。它绝不会删除日志，因此明文不会进入 ApexLog，也不会影响无关的审计日志。如果某个用户的 System.setPassword 本身失败，该用户也会保持 ACTIVE，并标记为需要重置密码。

运行

# 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 users
bash scripts/detect-and-create.sh run  <org-alias> [count=3] [profile-name="Standard User"]

detect-and-create.sh 是规范入口：它会重新运行检测、执行生产环境防护检查，然后才进行插入。不要直接调用 scripts/run-create.sh——它是内部脚本，本身不会执行防护检查。

行为

检测。 检测器从 Organization.Id 派生一个 8 字符后缀（substring(10,18)，转换为小写），按名称解析配置文件，并查询 User，查找 agent{i}.<suffix>@example.com，以确定 count 个槽位索引中哪些已被占用。稳定且确定的模式是重跑能够实现幂等的关键——后缀绝不会是时间戳或 UUID。

插入。 Apex 加载 assets/create-users.apex.template，替换 __COUNT__/__PROFILE_ID__/__SUFFIX__，并且只插入缺失的索引。它会在事务内重新检查现有用户，从而避免单次运行重复插入；但在并发运行中，事务内检查并不能保证这一点（两个运行都可能在任一方提交前通过预查询），因此这里的重复保护依赖全局用户名唯一性约束以及 DUPLICATE_USERNAME 重试（参见 references/apex-template-notes.md）。它会启用 Service Cloud 功能（UserPermissionsSupportUser=true），以便用户能在 Omni 中上线；如果配置文件的许可证不允许启用此功能，Apex 会移除该标志并重试（用户仍会创建，但要完整使用 Omni，需要使用 Service Cloud 许可证配置文件）。每个创建的用户都会通过 AGENT_USER_CREATED|<id>|<username>|<email> 报告（标记中不包含密码——密码由单独的 System.setPassword 提交设置）。

验证。 插入后，检测器会再次运行，且必须显示 missing_count == 0；否则此技能会失败（Apex 报告成功，但用户未能持久化）。

输出约定

detect-and-create.sh 会输出一个 JSON 对象，其中 status ∈ created | partial | reused | action_needed | blocked，还包括 detect（与检测器输出一致）、create（与插入器输出一致；未创建任何内容时为 null）、顶层字段 reused_users、created_count、reused_count、total_present_after、users_needing_password_reset、action_required 和 safe_to_write。协调器会将 reused_users 与新创建的用户合并，以便为本次请求的完整 Agent 集配置在线状态和技能。

• created — 所有缺失的索引均已创建，且对应用户拥有可用密码。
• partial — 部分用户已创建但并非全部，或任何用户需要手动重置密码，或发现了非活动占用者。
• reused — 所有请求的用户都已存在；未创建任何用户。
• action_needed — 仅适用于计划模式；报告缺失的索引，不进行写入。
• blocked — 前置条件不满足（safe_to_write=false、无法解析配置文件/后缀，或未插入任何用户）。

create.created_users[].password 仅会填入本次运行创建且 System.setPassword 成功的用户密码；password_status:"reset_required" 表示该用户处于活动状态，但尚无可用密码。created/partial/action_needed/reused 的退出代码为 0，blocked 的退出代码为 1。

生成的密码属于机密：它们只会出现在返回的 JSON 中。任何会持久化标准输出的调用方，都必须仅将其写入受限的 CREDENTIALS.json（权限模式为 0600），从其他所有产物中删除密码，并在分发后删除该文件——协调器会自动执行这些操作；独立调用方需自行负责。无法取回已复用用户的密码；请通过 Setup → Users → Reset Password 进行恢复。

限制

• 用户名模式和组织后缀固定，操作员无法配置——正是这种确定性使幂等重跑成为可能。
• 仅会在给定配置文件上创建 Agent 用户；绝不会删除、停用或修改现有用户。
• 常见的 User 错误（DUPLICATE_USERNAME、INVALID_EMAIL、LICENSE_LIMIT_EXCEEDED）会转换为便于操作员理解的消息，而不会原样显示。

参考资料

文件	阅读时机
references/apex-patterns.md	运行 Apex 前 — Apex 结构、User 字段默认值、密码策略和配置文件本地化风险
references/apex-template-notes.md	用户创建返回重复项、许可证或密码错误时 — 说明模板替换和重试行为
assets/create-users.apex.template	插入缺失的 Agent 用户时，由 scripts/run-create.sh 加载
scripts/detect-existing.sh	由规范入口加载，用于检查只读 org、配置文件、安全性和现有用户
scripts/tests/test_user_create_security.py	更改用户创建脚本后运行，以验证生产环境拒绝策略和密码处理约定