service-omni-channel-setup-coordinate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

service-omni-channel-setup-coordinate

Align an org toward a working Omni-Channel setup: detect what already exists and create or deploy only the missing pieces, up to a routed environment with agents, queues, presence statuses, and permissions. Full create-and-bind routing (queue +

QueueRoutingConfig

+ outbound routing flow) is provided for

Case

and

VoiceCall

;

Incident

and

MessagingSession

are verified/adopted only by this coordinator — it reports their state and reuses existing config but does not create a missing queue/QRC/flow for them (use

service-agentforce-human-escalation-configure

for a created-and-bound

MessagingSession

handoff). This is a coordinator — it sequences the child leaf skills against a canonical set of steps and performs no writes of its own. Each leaf owns one primitive; the coordinator resolves per-org IDs, passes them between leaves, and enforces a shared reuse-vs-create and safety contract. It blocks with a click-path only for prerequisites an operator must action (a missing feature license, or a target sObject that is not enabled).

python3

is listed only because the bundled contract tests (

scripts/tests/test_omni_contracts.py

) use it; running the coordinator itself needs only

jq

and

sf

将组织调整为可用的Omni-Channel配置：检测已存在的内容，仅创建或部署缺失的部分，直至搭建出包含坐席、队列、在线状态和权限的路由环境。为

Case

和

VoiceCall

提供完整的创建并绑定路由（队列 +

QueueRoutingConfig

+ 出站路由流）；

Incident

和

MessagingSession

仅由该协调器验证/复用——它会报告这些对象的状态并复用现有配置，但不会为它们创建缺失的队列/QRC/流（如需创建并绑定

MessagingSession

转接，请使用

service-agentforce-human-escalation-configure

）。这是一个协调器——它会按照标准步骤序列调用子技能，自身不执行任何写入操作。每个子技能负责一项基础操作；协调器会解析各组织的ID，在子技能间传递这些ID，并强制执行通用的复用/创建规则和安全约定。仅当存在操作员必须处理的前置条件时（如缺失功能许可证，或目标sObject未启用），它才会给出点击路径并阻止流程继续。

列出

python3

仅因为捆绑的契约测试（

scripts/tests/test_omni_contracts.py

）需要它；运行协调器本身只需要

jq

和

sf

。

Inputs

Confirm these once, up front, before any write:

Agent count (default
```
3
```
, range
```
1..10
```
) and supervisor count (default
```
1
```
, range
```
1..5
```
).
Real login email (used for password-reset flows).
```
routing_targets
```
(default
```
["Case"]
```
) — any subset of
```
Case | Incident | MessagingSession | VoiceCall
```
. Only
```
Case
```
and
```
VoiceCall
```
get full create-queue + QRC + routing-flow;
```
Incident
```
and
```
MessagingSession
```
are verified/adopted (report-only).
Service-channel strategy — reuse standard (
```
Cases
```
,
```
sfdc_livemessage
```
, default) or create a custom channel.
Agent/supervisor profile — the driver provisions users on the
```
Service Cloud User
```
profile by default (Omni needs a Service Cloud license). Some orgs ship that license under a differently named profile (e.g.
```
Service Cloud
```
); override via
```
OMNI_AGENT_PROFILE
```
/
```
OMNI_SUPERVISOR_PROFILE
```
without editing the script. The user-create leaves block if the named profile is absent.
Runtime proof (optional) —
```
OMNI_RUNTIME_PROOF=1
```
makes the routing-flow leaf fire the trigger (fail-soft);
```
OMNI_RUNTIME_PROOF_REQUIRED=1
```
makes proof blocking. QueueBased proof requires
```
PendingServiceRouting
```
or
```
AgentWork
```
. SkillsBased proof requires a
```
PendingServiceRouting
```
with at least one
```
SkillRequirement
```
, which is the acceptance signal that
```
WorkSkillRouting
```
actually ran. The throwaway record is always cleaned up.
Queue selection (optional) — set
```
OMNI_CASE_QUEUE_DEVELOPER_NAME
```
,
```
OMNI_VOICE_QUEUE_DEVELOPER_NAME
```
,
```
OMNI_INCIDENT_QUEUE_DEVELOPER_NAME
```
, or
```
OMNI_MESSAGING_QUEUE_DEVELOPER_NAME
```
when the target must use a specific existing or canonical queue. Without an override, each leaf uses its target-derived default.
Routing-config selection (optional) — set
```
OMNI_CASE_ROUTING_CONFIG_DEVELOPER_NAME
```
or
```
OMNI_VOICE_ROUTING_CONFIG_DEVELOPER_NAME
```
to select an existing QRC explicitly. When only a queue override is supplied, the coordinator first adopts that queue's linked
```
QueueRoutingConfig.DeveloperName
```
; it creates the canonical QRC only when the queue has no linked config.
Queue routing controls (optional) —
```
OMNI_QRC_PUSH_TIMEOUT
```
sets the agent acceptance timeout and
```
OMNI_QRC_CAPACITY_PERCENTAGE
```
selects percentage capacity (for example,
```
100
```
for a VoiceCall that consumes the agent's full capacity). The coordinator passes both values to every QRC target.
Routing mode —
```
OMNI_ROUTING_TYPE=QueueBased|SkillsBased
```
is optional. When all four
```
OMNI_WSR_ENTITY
```
/
```
OMNI_WSR_FIELD
```
/
```
OMNI_WSR_SKILL
```
/
```
OMNI_WSR_VALUE
```
inputs are supplied, the coordinator infers
```
SkillsBased
```
; otherwise it defaults to
```
QueueBased
```
. SkillsBased uses
```
OMNI_SKILL_OPTION=RunSBRRules
```
(the default), binds the provisioned agents to
```
OMNI_SBR_SKILL
```
(defaults to
```
OMNI_WSR_SKILL
```
), authors the WorkSkillRouting rule, and only then activates the flow. An incomplete mapping or mismatched SBR/WSR skill is rejected before any write.
```
OMNI_WSR_LABEL
```
optionally names the rule.
Rep-experience stages (optional, default off) —
```
OMNI_REP_EXPERIENCE=1
```
adds presence user config (decline + decline reason + ACW) and the Omni sidebar.
```
OMNI_CONSOLE_APP=<app DeveloperName>
```
targets a specific console app; empty auto-detects one.
Supervisor surface (always, after the config) — once
```
OmniSupervisorConfig
```
exists, the coordinator populates its standard action + tab surface (
```
OmniSupervisorConfigAction
```
/
```
OmniSupervisorConfigTab
```
) via the Data API. Just before the classic config deploy it also runs a read-only Command Center analysis that reports whether the org is on the classic surface or Command Center V2.
Supervisor-config selection (optional) — set
```
OMNI_SUPERVISOR_CONFIG_DEVELOPER_NAME
```
to the exact classic
```
OmniSupervisorConfig.DeveloperName
```
that both the config and surface stages must reconcile. It defaults to
```
Omni_Supervisor
```
; use the override whenever the org has multiple configs so the coordinator never guesses.
```
OMNI_SUPERVISOR_CONFIG_MASTER_LABEL
```
optionally supplies the label when creating a new selected config.

Run it in plan or run mode:

bash

bash scripts/integration-driver.sh --plan <org-alias> [agent_count] [routing_targets_csv] [supervisor_count]
bash scripts/integration-driver.sh --run  <org-alias> [agent_count] [routing_targets_csv] [supervisor_count]

--plan

is a full read-only preview: each leaf runs its own detector and reports

reused

action_needed

, or

blocked

; a leaf whose prerequisite is not yet in place is reported as pending work rather than probed, so a plan never shows a misleading red for a step that is simply earlier in the sequence. A clean plan (all

reused

, exit 0) means the org is already configured; any yellow (exit 2) means work remains.

在执行任何写入操作前，请预先确认以下内容：

坐席数量（默认
```
3
```
，范围
```
1..10
```
）和管理员数量（默认
```
1
```
，范围
```
1..5
```
）。
真实登录邮箱（用于密码重置流程）。
```
routing_targets
```
（默认
```
["Case"]
```
）——
```
Case | Incident | MessagingSession | VoiceCall
```
的任意子集。仅
```
Case
```
和
```
VoiceCall
```
会获得完整的创建队列 + QRC + 路由流；
```
Incident
```
和
```
MessagingSession
```
仅会被验证/复用（仅报告状态）。
服务渠道策略——复用标准渠道（
```
Cases
```
、
```
sfdc_livemessage
```
，默认）或创建自定义渠道。
坐席/管理员配置文件——驱动程序默认使用
```
Service Cloud User
```
配置文件创建用户（Omni需要Service Cloud许可证）。部分组织的该许可证可能对应不同名称的配置文件（如
```
Service Cloud
```
）；无需编辑脚本，可通过
```
OMNI_AGENT_PROFILE
```
/
```
OMNI_SUPERVISOR_PROFILE
```
覆盖默认值。如果指定的配置文件不存在，创建用户的子技能会阻止流程继续。
运行时验证（可选）——设置
```
OMNI_RUNTIME_PROOF=1
```
会让路由流子技能触发验证（软失败）；设置
```
OMNI_RUNTIME_PROOF_REQUIRED=1
```
会让验证成为阻塞条件。基于队列的验证需要
```
PendingServiceRouting
```
或
```
AgentWork
```
；基于技能的验证需要带有至少一个
```
SkillRequirement
```
的
```
PendingServiceRouting
```
，这是
```
WorkSkillRouting
```
实际运行的确认信号。临时记录始终会被清理。
队列选择（可选）——当目标必须使用特定现有或标准队列时，设置
```
OMNI_CASE_QUEUE_DEVELOPER_NAME
```
、
```
OMNI_VOICE_QUEUE_DEVELOPER_NAME
```
、
```
OMNI_INCIDENT_QUEUE_DEVELOPER_NAME
```
或
```
OMNI_MESSAGING_QUEUE_DEVELOPER_NAME
```
。如果没有覆盖设置，每个子技能会使用基于目标对象的默认队列。
路由配置选择（可选）——设置
```
OMNI_CASE_ROUTING_CONFIG_DEVELOPER_NAME
```
或
```
OMNI_VOICE_ROUTING_CONFIG_DEVELOPER_NAME
```
以显式选择现有QRC。当仅提供队列覆盖时，协调器首先会复用该队列关联的
```
QueueRoutingConfig.DeveloperName
```
；仅当队列没有关联配置时，才会创建标准QRC。
队列路由控制（可选）——
```
OMNI_QRC_PUSH_TIMEOUT
```
设置坐席接受超时时间，
```
OMNI_QRC_CAPACITY_PERCENTAGE
```
选择容量百分比（例如，
```
100
```
表示VoiceCall占用坐席全部容量）。协调器会将这两个值传递给所有QRC目标。
路由模式——
```
OMNI_ROUTING_TYPE=QueueBased|SkillsBased
```
为可选设置。当提供了全部四个
```
OMNI_WSR_ENTITY
```
/
```
OMNI_WSR_FIELD
```
/
```
OMNI_WSR_SKILL
```
/
```
OMNI_WSR_VALUE
```
输入时，协调器会推断使用
```
SkillsBased
```
；否则默认使用
```
QueueBased
```
。SkillsBased模式使用
```
OMNI_SKILL_OPTION=RunSBRRules
```
（默认值），将创建的坐席绑定到
```
OMNI_SBR_SKILL
```
（默认值为
```
OMNI_WSR_SKILL
```
），编写WorkSkillRouting规则，然后才激活流。如果映射不完整或SBR/WSR技能不匹配，会在执行任何写入操作前被拒绝。
```
OMNI_WSR_LABEL
```
可选择性地为规则命名。
坐席体验阶段（可选，默认关闭）——设置
```
OMNI_REP_EXPERIENCE=1
```
会添加在线状态用户配置（拒绝 + 拒绝原因 + ACW）和Omni侧边栏。
```
OMNI_CONSOLE_APP=<app DeveloperName>
```
指定目标控制台应用；留空则自动检测一个。
管理员界面（始终在配置后执行）——一旦
```
OmniSupervisorConfig
```
存在，协调器会通过Data API填充其标准操作 + 标签界面（
```
OmniSupervisorConfigAction
```
/
```
OmniSupervisorConfigTab
```
）。在部署经典版配置之前，它还会运行只读的Command Center分析，报告组织当前使用的是经典版界面还是Command Center V2。
管理员配置选择（可选）——设置
```
OMNI_SUPERVISOR_CONFIG_DEVELOPER_NAME
```
为经典版
```
OmniSupervisorConfig.DeveloperName
```
的精确值，配置和界面阶段都必须与此值一致。默认值为
```
Omni_Supervisor
```
；当组织有多个配置时，请使用覆盖设置，避免协调器猜测。
```
OMNI_SUPERVISOR_CONFIG_MASTER_LABEL
```
可在创建新的选定配置时选择性地提供标签。

在计划模式或运行模式下运行：

bash

bash scripts/integration-driver.sh --plan <org-alias> [agent_count] [routing_targets_csv] [supervisor_count]
bash scripts/integration-driver.sh --run  <org-alias> [agent_count] [routing_targets_csv] [supervisor_count]

--plan

是完整的只读预览：每个子技能运行自己的检测器，报告

reused

、

action_needed

或

blocked

；如果某个子技能的前置条件尚未满足，会被报告为待处理工作，而非直接探测，因此计划模式永远不会对序列中较早的步骤显示误导性的红色结果。干净的计划（全部为

reused

，退出码0）表示组织已完成配置；任何黄色结果（退出码2）表示仍有工作需要完成。

Preconditions and safety

Authenticated org via
```
sf
```
CLI using the My Domain URL (not
```
.lightning.force.com
```
).
Service Cloud license with headroom for the agent count.
```
Incident
```
targets require the Incident Management feature enabled;
```
MessagingSession
```
requires Enhanced Messaging;
```
VoiceCall
```
requires Service Cloud Voice. The readiness check hard-fails with a click-path when a requested target sObject is absent.

Production guardrail:

safe_to_write

true

iff any of

IsSandbox = true

TrialExpirationDate != null

, or

OrganizationType IN ('Developer Edition', 'Base Edition')

. The run hard-refuses when it is false. CDOs return

IsSandbox=false

with a non-null

TrialExpirationDate

and must be permitted, so

IsSandbox

alone is never the guard.

Readiness check (silent, mandatory, before any leaf runs):

```
sf org display
```
→ confirm the org alias is authenticated; refuse (exit 1) if not.

Organization

(

IsSandbox

TrialExpirationDate

OrganizationType

) → compute

safe_to_write

; refuse (exit 1) if false.

Preflight entity availability → for each non-
Case
routing target, confirm the sObject exists via
```
EntityDefinition
```
; a missing target hard-fails with a feature-enablement click-path (exit 2).
```
Case
```
is assumed present and skipped.

Omni-Channel base-settings enablement is not a separate upfront probe — it is detected by the base-settings leaf (step 1), and downstream Omni-dependent leaves are deferred as pending in

--plan

until it is on. The driver does not pre-check

UserLicense

headroom or

ServicePresenceStatus

QueueRoutingConfig

availability in this readiness pass.

通过
```
sf
```
CLI使用My Domain URL（而非
```
.lightning.force.com
```
）认证组织。
拥有Service Cloud许可证，且剩余许可数量足够容纳所需坐席数量。
```
Incident
```
目标需要启用Incident Management功能；
```
MessagingSession
```
需要启用Enhanced Messaging；
```
VoiceCall
```
需要启用Service Cloud Voice。当请求的目标sObject不存在时，就绪检查会直接失败并给出功能启用的点击路径。
生产环境防护： 仅当
```
IsSandbox = true
```
、
```
TrialExpirationDate != null
```
或
```
OrganizationType IN ('Developer Edition', 'Base Edition')
```
中的任意一项成立时，
```
safe_to_write
```
才为
```
true
```
。如果为
```
false
```
，运行模式会直接拒绝执行。CDO返回
```
IsSandbox=false
```
且
```
TrialExpirationDate
```
非空，必须允许执行，因此不能仅以
```
IsSandbox
```
作为防护条件。

就绪检查（静默执行，强制性，在所有子技能运行前执行）：

```
sf org display
```
→ 确认组织别名已认证；如果未认证，拒绝执行（退出码1）。

Organization

（

IsSandbox

、

TrialExpirationDate

、

OrganizationType

）→ 计算

safe_to_write

；如果为

false

，拒绝执行（退出码1）。

预检查实体可用性 → 对于每个**非
```
Case
```
**的路由目标，通过
```
EntityDefinition
```
确认sObject存在；如果目标缺失，会直接失败并给出功能启用的点击路径（退出码2）。
```
Case
```
默认存在，跳过检查。

Omni-Channel基础设置的启用状态不会单独提前探测——它由基础设置子技能（步骤1）检测，在

--plan

模式下，依赖Omni的下游子技能会被延迟，标记为待处理，直到基础设置启用。驱动程序不会在此次就绪检查中预先检查

UserLicense

剩余数量或

ServicePresenceStatus

QueueRoutingConfig

的可用性。

Skills this coordinates

The coordinator delegates every write to a leaf skill. sObject-specific leaves (3, 5, 6, 6c, 7) loop once per routing target; the rest run once. For SkillsBased routing, steps 6a and 6b complete before any trigger flow is activated. Step 10a (

command-center-analyze

) is a read-only advisory and always runs. Step 11a (

supervisor-surface-deploy

) always runs after the supervisor config succeeds. Leaves 12–13 are the opt-in rep-experience stages (

OMNI_REP_EXPERIENCE=1


Settings:OmniChannel
service-omni-agent-users-create
ServiceChannel
QueueRoutingConfig
--create-if-missing
service-omni-queue-members-assign
Skill
service-omni-work-skill-routing-configure
Flow
Available_<sObject>
Omni_Agent
service-omni-supervisor-users-create
ContactCenterSupervisor
service-omni-command-center-analyze
OmniSupervisorConfig
OmniSupervisorConfigAction
PresenceUserConfig
CustomApplication.isOmniPinnedViewEnabled=true
platform-metadata-deploy

#	Child skill	Role
1	`service-omni-base-settings-configure`	Deploy `Settings:OmniChannel` (5 toggles)
2	`service-omni-agent-users-create`	Provision the requested agent users
3	`service-omni-service-channel-configure`	Reuse the standard `ServiceChannel` for the target sObject, or deploy the canonical XML
4	`service-omni-queue-routing-config-deploy`	Upsert the target's `QueueRoutingConfig` (e.g. `Case_Routing_Config` , `Voice_Routing_Config` )
5	`service-omni-queue-deploy`	Discover or create ( `--create-if-missing` ) a `Queue` bound to the target sObject; align it to the QRC
6	`service-omni-queue-members-assign`	Assign users to the discovered queue
6a	`service-omni-skills-based-routing-configure`	(SkillsBased only) Ensure the `Skill` and active agents' `SkillUser` bindings exist
6b	`service-omni-work-skill-routing-configure`	(SkillsBased only) Author the required field-value → Skill rule before flow activation
6c	`service-omni-routing-flow-deploy`	Deploy the record-triggered QueueBased or SkillsBased `Flow` for `Case` / `VoiceCall` ; SkillsBased passes `skillOption=RunSBRRules`
7	`service-omni-presence-status-deploy`	Deploy `Available_<sObject>` bound to the matching channel and ensure a universal `Busy` status
8	`service-omni-permission-set-assign`	Assign the `Omni_Agent` PermissionSet to agent users; self-heals the bundled metadata when absent (run mode only)
9	`service-omni-supervisor-users-create`	Provision supervisor users
10	`service-omni-supervisor-permset-assign`	Assign the standard `ContactCenterSupervisor` PermissionSet to supervisor users
10a	`service-omni-command-center-analyze`	Read-only advisory — report whether the org is on the classic supervisor surface or Command Center V2; never writes, never hard-blocks
11	`service-omni-supervisor-config-deploy`	Deploy `OmniSupervisorConfig` binding supervisor users to the queues discovered in step 5
11a	`service-omni-supervisor-surface-deploy`	Populate the supervisor action + tab surface ( `OmniSupervisorConfigAction` / `OmniSupervisorConfigTab` ) on the config from step 11
12	`service-omni-presence-user-config-deploy`	(opt-in) Deploy `PresenceUserConfig` + `PresenceDeclineReason` (decline + ACW) and assign the provisioned agents
13	`service-omni-sidebar-configure`	(opt-in) Set `CustomApplication.isOmniPinnedViewEnabled=true` to pin the Omni utility region on a console app
—	`platform-metadata-deploy`	Underlying Metadata API deploys used by the deploy leaves

协调器将所有写入操作委托给子技能。特定sObject的子技能（3、5、6、6c、7）会针对每个路由目标运行一次；其余子技能仅运行一次。对于SkillsBased路由，步骤6a和6b必须在触发流激活前完成。步骤10a（

command-center-analyze

）是只读的建议性步骤，始终会运行。步骤11a（

supervisor-surface-deploy

）始终会在管理员配置成功后运行。子技能12–13是可选的坐席体验阶段（

OMNI_REP_EXPERIENCE=1

）。


Settings:OmniChannel
service-omni-agent-users-create
ServiceChannel
QueueRoutingConfig
--create-if-missing
service-omni-queue-members-assign
Skill
service-omni-work-skill-routing-configure
Case
Available_<sObject>
Omni_Agent
service-omni-supervisor-users-create
ContactCenterSupervisor
service-omni-command-center-analyze
OmniSupervisorConfig
OmniSupervisorConfigAction
PresenceUserConfig
CustomApplication.isOmniPinnedViewEnabled=true
platform-metadata-deploy

#	Child skill	Role
1	`service-omni-base-settings-configure`	部署 `Settings:OmniChannel` （5个开关）
2	`service-omni-agent-users-create`	创建所需的坐席用户
3	`service-omni-service-channel-configure`	复用目标sObject的标准 `ServiceChannel` ，或部署标准XML
4	`service-omni-queue-routing-config-deploy`	插入或更新目标对象的 `QueueRoutingConfig` （如 `Case_Routing_Config` 、 `Voice_Routing_Config` ）
5	`service-omni-queue-deploy`	发现或创建（ `--create-if-missing` ）绑定到目标sObject的 `Queue` ；将其与QRC对齐
6	`service-omni-queue-members-assign`	将用户分配到发现的队列
6a	`service-omni-skills-based-routing-configure`	(仅SkillsBased模式) 确保 `Skill` 和活跃坐席的 `SkillUser` 绑定关系存在
6b	`service-omni-work-skill-routing-configure`	(仅SkillsBased模式) 在流激活前编写所需的字段值→Skill规则
6c	`service-omni-routing-flow-deploy`	为 `Case` / `VoiceCall` 部署记录触发式的QueueBased或SkillsBased `Flow` ；SkillsBased模式会传递 `skillOption=RunSBRRules`
7	`service-omni-presence-status-deploy`	部署绑定到匹配渠道的 `Available_<sObject>` ，并确保存在通用的 `Busy` 状态
8	`service-omni-permission-set-assign`	为坐席用户分配 `Omni_Agent` 权限集；当权限集缺失时会自动修复捆绑的元数据（仅运行模式）
9	`service-omni-supervisor-users-create`	创建管理员用户
10	`service-omni-supervisor-permset-assign`	为管理员用户分配标准的 `ContactCenterSupervisor` 权限集
10a	`service-omni-command-center-analyze`	只读建议——报告组织当前使用的是经典版管理员界面还是Command Center V2；从不执行写入操作，也不会直接阻止流程
11	`service-omni-supervisor-config-deploy`	部署 `OmniSupervisorConfig` ，将管理员用户绑定到步骤5中发现的队列
11a	`service-omni-supervisor-surface-deploy`	在步骤11的配置上填充管理员操作 + 标签界面（ `OmniSupervisorConfigAction` / `OmniSupervisorConfigTab` ）
12	`service-omni-presence-user-config-deploy`	(可选) 部署 `PresenceUserConfig` + `PresenceDeclineReason` （拒绝 + ACW）并分配给创建的坐席
13	`service-omni-sidebar-configure`	(可选) 设置 `CustomApplication.isOmniPinnedViewEnabled=true` ，在控制台应用上固定Omni工具区域
—	`platform-metadata-deploy`	部署子技能使用的底层Metadata API部署工具

Behavior

Reuse-vs-create contract (enforced for every entity). Query by

DeveloperName

(or the natural key); reuse a standard record when present (

Cases

sfdc_livemessage

); create from the leaf's bundled definition when nothing exists; reconcile idempotently when a same-named custom record exists — never duplicate, rename, or mutate the identity of a standard or managed record.

Ordering and gating. Leaves run in dependency order. Base settings are a hard prerequisite for every write below. For SkillsBased routing, agent

SkillUser

bindings (6a) and the

WorkSkillRouting

rule (6b) must succeed before the routing-flow leaf (6c) can activate the trigger. The flow also requires the queue (5) and its members (6), and it round-trips

FlowDefinitionView.ActiveVersionId

to prove the flow is Active. A required runtime proof does not pass merely because a PSR exists: SkillsBased requires at least one

SkillRequirement

on that PSR.

Supervisor path. Supervisor users (9) use the same Anonymous Apex

System.setPassword

model as agent users. Because a password literal can be captured in an

ApexLog

when a debug TraceFlag is active, both user-create leaves fail closed before the first

System.setPassword

: they prove via a SOQL-filtered Tooling API query (

ExpirationDate > now

) that no active TraceFlag exists for the running user, and if that cannot be positively proven they set no password at all (users left ACTIVE and

reset_required

, with a

security_warning

). They never delete logs, so unrelated audit logs are untouched. The supervisor permset leaf (10) assigns the standard

ContactCenterSupervisor

— never the custom

Omni_Supervisor

, whose license-gated permissions fail assignment — and a contract test asserts this wiring. After the supervisor permset, a read-only Command Center analysis (10a) reports the org's supervisor surface (classic vs Command Center V2); it never writes and never hard-blocks (ambiguous detection is yellow, a clean read green). Once the config lands (11), the surface leaf (11a) inserts the standard action + tab companions (

OmniSupervisorConfigAction

OmniSupervisorConfigTab

) against the config's Id — plain Data API rows, so no metadata-file redeploy — and is idempotent (only missing types are inserted). It runs only after the config succeeds; a skipped or failed config skips the surface with a dependency note.

Optional rep-experience stages. With

OMNI_REP_EXPERIENCE=1

, presence user config (12) deploys a validator-safe

PresenceUserConfig

with its decline reason and assigns every resolved agent username, including reused users. Sidebar (13) pins the Omni utility region on

OMNI_CONSOLE_APP

, or auto-detects a single console app. SkillsBased routing is not a cosmetic rep-experience stage: when requested, its SkillUser and WorkSkillRouting prerequisites run before flow activation.

Login-behavior gap. The login-behavior radio (Setup → Omni-Channel Settings → "Define login behavior when an agent opens a new window/tab") has no public API on v66. After base settings deploy, the coordinator surfaces the exact click-path; it does not attempt to flip it via

enableOmniAutoLoginPrompt

, which deploys but does not drive the radio. See

references/gap-catalog.md

Credentials. Generated passwords are moved into a single restricted

CREDENTIALS.json

(mode 0600) and redacted from every other artifact. The write is atomic and fail-closed: on any redaction or verification failure the plaintext artifact is removed and the run aborts, so no plaintext password is left in the artifacts directory. The operator reads

CREDENTIALS.json

once, distributes securely, then deletes it.

复用/创建约定（对所有实体强制执行）。 通过

DeveloperName

（或自然键）查询；如果存在标准记录（如

Cases

、

sfdc_livemessage

）则复用；如果不存在则从子技能的捆绑定义创建；如果存在同名自定义记录则进行幂等协调——永远不会复制、重命名或修改标准或托管记录的标识。

排序与门控。 子技能按依赖顺序运行。基础设置是后续所有写入操作的硬性前置条件。对于SkillsBased路由，坐席的

SkillUser

绑定关系（6a）和

WorkSkillRouting

规则（6b）必须成功，路由流子技能（6c）才能激活触发器。流还需要队列（5）及其成员（6），并且会通过

FlowDefinitionView.ActiveVersionId

确认流已激活。所需的运行时验证不会仅因PSR存在而通过：SkillsBased模式要求该PSR上至少有一个

SkillRequirement

。

管理员路径。 管理员用户（9）使用与坐席用户相同的匿名Apex

System.setPassword

模型。由于当调试TraceFlag激活时，密码字面量可能会被捕获到

ApexLog

中，两个创建用户的子技能会在首次调用

System.setPassword

前严格检查：它们通过SOQL过滤的Tooling API查询（

ExpirationDate > now

）确认运行用户没有激活的TraceFlag；如果无法确认，则不会设置密码（用户保持ACTIVE状态且

reset_required

，并给出

security_warning

）。它们永远不会删除日志，因此不会影响无关的审计日志。管理员权限集子技能（10）分配标准的

ContactCenterSupervisor

——永远不会分配自定义的

Omni_Supervisor

，因为其许可证限制的权限分配会失败——契约测试会验证此配置。在分配管理员权限集后，只读的Command Center分析（10a）会报告组织的管理员界面类型（经典版 vs Command Center V2）；它从不执行写入操作，也不会直接阻止流程（检测结果不明确时显示黄色，读取正常时显示绿色）。一旦配置完成（11），界面子技能（11a）会针对配置的Id插入标准操作 + 标签配套项（

OmniSupervisorConfigAction

OmniSupervisorConfigTab

）——这是普通的Data API行，无需重新部署元数据文件——并且是幂等的（仅插入缺失的类型）。它仅在配置成功后运行；如果配置被跳过或失败，会因依赖关系而跳过界面配置，并给出说明。

可选坐席体验阶段。 设置

OMNI_REP_EXPERIENCE=1

后，在线状态用户配置（12）会部署符合验证要求的

PresenceUserConfig

及其拒绝原因，并分配给所有解析出的坐席用户名，包括复用的用户。侧边栏（13）会在

OMNI_CONSOLE_APP

上固定Omni工具区域，或自动检测单个控制台应用。SkillsBased路由不属于外观类的坐席体验阶段：当被请求时，其SkillUser和WorkSkillRouting前置条件会在流激活前运行。

登录行为缺口。 登录行为单选框（设置 → Omni-Channel设置 → "定义坐席打开新窗口/标签时的登录行为"）在v66版本中没有公开API。在基础设置部署后，协调器会显示精确的点击路径；它不会尝试通过

enableOmniAutoLoginPrompt

修改该设置，因为该参数可以部署但无法控制单选框。详情请见

references/gap-catalog.md

。

凭据。 生成的密码会被移至单个受限的

CREDENTIALS.json

文件（权限模式0600），并从所有其他工件中脱敏。写入操作是原子性的且严格失败关闭：如果脱敏或验证失败，会删除明文工件并终止运行，因此工件目录中不会留下明文密码。操作员只需读取一次

CREDENTIALS.json

，安全分发后即可删除该文件。

Output contract

The one deliverable is a single report file. As the final action you MUST use the

Write

tool to save the complete report to

omni-coordinate-report.md

in the current working directory — never deliver it only in chat. In

--run

mode it states what is (created resource, reused standard record, resolved decision) — no hedging. In

--plan

mode it states each leaf's honest disposition (

reused

action_needed

/ pending) plus the coordinator's plan JSON (

dry_run: true

). Each leaf also writes its full JSON outcome (including every created record Id and deploy Id) to a per-skill artifact under the run's artifacts directory — that is the audit trail; user-facing output uses human-readable names, not record Ids. See

examples/output-templates.md

for the report shape.

Run artifacts (run mode). Alongside the per-skill artifacts, a

--run

writes three files into the run's artifacts directory (paths echoed in the report JSON as

run_log

deploy_ids_file

teardown_script

run.log

(sanitized, human-readable step sequence and result),

deploy_ids.json

(a provenance manifest — each entry's

provenance

created

updated

reused

, with resource ids, a

before

snapshot, and a pointer to the authoritative per-skill artifact), and

teardown.sh

(an auto-generated, dry-run reverse-dependency-order plan). The teardown script prints what a teardown would

REMOVE

(run-created),

RESTORE

(updated, with prior values), or

KEEP

(adopted/reused — never deleted) and makes no changes; destructive execution stays manual by design (see Limitations).

Report content rules:

Report concrete outcomes, never intentions.
Surface the login-behavior click-path whenever setup ran, even if the operator declined to turn the radio.
Surface any hard fail from step 5 (no queue bound) as a manual action with a click-path.

唯一的交付物是单个报告文件。作为最终操作，您必须使用

Write

工具将完整报告保存到当前工作目录的

omni-coordinate-report.md

中——切勿仅在聊天中交付。在

--run

模式下，报告说明实际完成的操作（创建的资源、复用的标准记录、已解决的决策）——不含模糊表述。在

--plan

模式下，报告说明每个子技能的真实状态（

reused

action_needed

/ 待处理）以及协调器的计划JSON（

dry_run: true

）。每个子技能还会将其完整的JSON结果（包括所有创建的记录Id和部署Id）写入到运行工件目录下的对应子技能工件中——这是审计追踪；面向用户的输出使用人类可读的名称，而非记录Id。报告格式请见

examples/output-templates.md

。

运行工件（运行模式）。 除了子技能工件外，

--run

模式还会在运行工件目录中写入三个文件（路径会在报告JSON中以

run_log

、

deploy_ids_file

、

teardown_script

的形式显示）：

run.log

（脱敏的、人类可读的步骤序列和结果）、

deploy_ids.json

（来源清单——每个条目的

provenance

为

created

updated

reused

，包含资源id、

before

快照，以及指向权威子技能工件的指针），以及

teardown.sh

（自动生成的、仅计划模式的反向依赖顺序计划）。清理脚本会显示清理操作将

REMOVE

（运行时创建的）、

RESTORE

（已更新的，包含之前的值）或

KEEP

（已复用/采用的——永远不会删除）的内容，但不会执行任何更改；破坏性执行默认保持手动（请参见限制）。

报告内容规则：

报告具体结果，而非意图。
无论操作员是否修改单选框，只要执行了设置，就显示登录行为的点击路径。
将步骤5的任何直接失败（无绑定队列）显示为带有点击路径的手动操作。

Limitations

Routing-flow deploy covers
```
Case
```
and
```
VoiceCall
```
only.
Classic
```
OmniSupervisorConfig
```
(including its action + tab surface) only. Command Center V2 (Enhanced Omni-Channel) is reported by the read-only analysis step but not enabled — the org preference is not writable via the Metadata API. The surface leaf populates only the reference-free standard action/tab types; custom-action, FlexiPage, AWS-dashboard, and AI-agent surfaces need an external reference and must be set up in Setup.
The rep-experience stages (presence user config, decline reasons, sidebar) run only with
```
OMNI_REP_EXPERIENCE=1
```
. SkillsBased routing is selected explicitly or inferred from a complete
```
OMNI_WSR_*
```
mapping and runs independently of that flag.
Teardown is plan-only:
```
--run
```
emits
```
deploy_ids.json
```
(a provenance manifest) and a dry-run
```
teardown.sh
```
that prints the reverse-order removal/restore plan, but does not execute destructive changes. Automated reversal is deliberately deferred until every leaf emits a normalized provenance block and the reversal is validated live — metadata-deployed components need destructiveChanges deploys and adopted records must never be deleted. Reversal today is a manual operator task guided by the plan and the per-skill artifacts.

路由流部署仅覆盖
```
Case
```
和
```
VoiceCall
```
。
仅支持经典版
```
OmniSupervisorConfig
```
（包括其操作 + 标签界面）。Command Center V2（增强版Omni-Channel）会由只读分析步骤报告，但无法启用——组织偏好无法通过Metadata API写入。界面子技能仅填充无引用的标准操作/标签类型；自定义操作、FlexiPage、AWS仪表板和AI坐席界面需要外部引用，必须在设置中配置。
坐席体验阶段（在线状态用户配置、拒绝原因、侧边栏）仅在
```
OMNI_REP_EXPERIENCE=1
```
时运行。SkillsBased路由需显式选择，或由完整的
```
OMNI_WSR_*
```
映射推断，与该标志独立运行。
清理仅支持计划模式：
```
--run
```
模式会生成
```
deploy_ids.json
```
（来源清单）和仅计划模式的
```
teardown.sh
```
，显示反向顺序的删除/恢复计划，但不会执行破坏性更改。自动回滚被故意延迟，直到每个子技能都生成标准化的来源块，且回滚操作经过实时验证——元数据部署的组件需要destructiveChanges部署，已采用的记录永远不能被删除。目前回滚是操作员的手动任务，需参考计划和子技能工件。

Use-case coverage (current)

Use case	Status	What is / isn't headless
Case routing	Ready	Full create-and-bind thread (queue + QRC + members + routing flow), idempotent; runtime `PendingServiceRouting` proof optional.
VoiceCall / AFCC routing	Conditional	QRC + queue + members + routing flow are deployable, but require a provisioned Amazon/AFCC contact center and a live Voice runtime to prove end-to-end. Contact-center provisioning is the caller's responsibility.
Open CTI → AFCC migration	Partial	The coordinator creates the Omni routing resources; it does not provision or migrate the contact center itself.
Incident routing	Partial	Service channel + presence are supported; the coordinator verifies/adopts Incident routing but does not create a missing queue/QRC/flow for it.
Generic MessagingSession routing	Partial	Service channel + presence supported; full create-and-bind is delegated to `service-agentforce-human-escalation-configure` , not run generically here.
Classic Omni Supervisor	Ready	Users, permissions, config, queues/users, and the action/tab surface companions are all implemented.
Command Center V2	Detection only	The read-only analysis step reports classic vs V2; the org preference `CommandCenterForServiceV2` is not writable via the Metadata API (tracked: W-23827287) and must be enabled in Setup.
Supervisor monitoring OrgValues	Not implemented	`OmniSuperConvMonitor` , `OmniSuperAgentSneakpeek` , `OmniSuperClientSneakpeek` , `OmniSuperWhisper` , `OmniSuperAdminSkillQueue` are OrgValues with no proven supported external write API.
Omni Inbox	Not implemented	The sidebar leaf pins the Omni sidebar ( `isOmniPinnedViewEnabled` ); it does not create or configure Omni Inbox, a console app, or utility items.

用例	状态	哪些支持无头/哪些不支持
Case路由	已就绪	完整的创建并绑定流程（队列 + QRC + 成员 + 路由流），支持幂等；可选运行时 `PendingServiceRouting` 验证。
VoiceCall / AFCC路由	有条件支持	QRC + 队列 + 成员 + 路由流可部署，但需要已配置的Amazon/AFCC联络中心和可用的Voice运行时来完成端到端验证。联络中心配置由调用方负责。
Open CTI → AFCC迁移	部分支持	协调器创建Omni路由资源；但不负责配置或迁移联络中心本身。
Incident路由	部分支持	支持服务渠道 + 在线状态；协调器验证/复用Incident路由，但不会为其创建缺失的队列/QRC/流。
通用MessagingSession路由	部分支持	支持服务渠道 + 在线状态；完整的创建并绑定委托给 `service-agentforce-human-escalation-configure` ，不在此通用运行。
经典版Omni Supervisor	已就绪	用户、权限、配置、队列/用户关联，以及操作/标签界面配套项均已实现。
Command Center V2	仅支持检测	只读分析步骤报告经典版 vs V2；组织偏好 `CommandCenterForServiceV2` 无法通过Metadata API写入（追踪编号：W-23827287），必须在设置中启用。
管理员监控OrgValues	未实现	`OmniSuperConvMonitor` 、 `OmniSuperAgentSneakpeek` 、 `OmniSuperClientSneakpeek` 、 `OmniSuperWhisper` 、 `OmniSuperAdminSkillQueue` 是OrgValues，没有已证实的支持外部写入的API。
Omni收件箱	未实现	侧边栏子技能固定Omni侧边栏（ `isOmniPinnedViewEnabled` ）；但不创建或配置Omni收件箱、控制台应用或工具项。

References

File	When to read
`references/gap-catalog.md`	The headless gaps (login-behavior radio, Agentforce routing target, Field Service skills routing) and how the coordinator handles each
`examples/output-templates.md`	Before emitting the report — canonical Setup Summary, Skill Outcomes, and Manual Actions blocks

文件	阅读时机
`references/gap-catalog.md`	了解无头配置的缺口（登录行为单选框、Agentforce路由目标、现场服务技能路由）以及协调器的处理方式
`examples/output-templates.md`	生成报告前阅读——标准的设置摘要、技能结果和手动操作块格式