service-omni-supervisor-config-deploy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

service-omni-supervisor-config-deploy

Deploy the classic Omni-Channel Supervisor Configuration (

OmniSupervisorConfig

) to a Salesforce org in a single Metadata API deploy.

OmniSupervisorConfig

is a full Metadata API type whose XSD embeds every companion as a repeatable child element, so the whole configuration — parent plus companions — lands atomically from one

.omniSupervisorConfig-meta.xml

file, and Salesforce rolls the companions back together on a partial failure. By default the deploy binds supervisors explicitly by user and lists the queues they monitor; profile scope is optional (see Behavior).

通过单次Metadata API部署，将经典版Omni-Channel Supervisor配置（

OmniSupervisorConfig

）部署至Salesforce组织。

OmniSupervisorConfig

是完整的Metadata API类型，其XSD将所有关联配置作为可重复子元素嵌入，因此整个配置——父配置及关联项——可通过单个

.omniSupervisorConfig-meta.xml

文件实现原子化部署，若出现部分失败，Salesforce会将所有关联配置一并回滚。默认情况下，部署会通过用户明确绑定管理员并列出他们监控的队列；基于配置文件的范围为可选设置（详见行为说明）。

Inputs

输入参数

bash scripts/deploy-and-report.sh <org-alias> [supervisor_count] [additional_queues_csv] [profiles_csv] [skill_visibility] [config_developer_name]

org-alias

(required) — must resolve via

sf org display --target-org <alias>

```
supervisor_count
```
(optional, default
```
1
```
, range
```
1..5
```
) — how many active
```
supervisor{N}.<suffix>@example.com
```
users to detect and bind.
```
additional_queues_csv
```
(optional) — queue DeveloperNames to bind. When the coordinator supplies this list it is authoritative; when omitted, the canonical
```
CaseQueue
```
,
```
messagingqueue
```
defaults are used. Every requested queue must already exist on the org.
```
profiles_csv
```
(optional) — opt into profile-based fallback scope; supply metadata profile fullNames (e.g.
```
Standard,ServiceCloud
```
). Omit it to bind supervisors by user only.
```
skill_visibility
```
(optional, or
```
OMNI_SUPERVISOR_SKILL_VISIBILITY
```
) —
```
AllSkills
```
or
```
AnySkill
```
. Omitted values preserve an existing config's selection; a new config defaults to
```
AllSkills
```
.
```
config_developer_name
```
(optional, or
```
OMNI_SUPERVISOR_CONFIG_DEVELOPER_NAME
```
; default
```
Omni_Supervisor
```
) — the exact classic
```
OmniSupervisorConfig.DeveloperName
```
to create or reconcile. Supply it when an org has multiple supervisor configurations; the skill never guesses between candidates.
```
OMNI_SUPERVISOR_CONFIG_MASTER_LABEL
```
optionally sets the label for a new config. Existing labels are preserved by default.

bash scripts/deploy-and-report.sh <org-alias> [supervisor_count] [additional_queues_csv] [profiles_csv] [skill_visibility] [config_developer_name]

org-alias

（必填）——必须可通过

sf org display --target-org <alias>

解析。

```
supervisor_count
```
（可选，默认值
```
1
```
，范围
```
1..5
```
）——检测并绑定的
```
supervisor{N}.<suffix>@example.com
```
格式活跃管理员用户数量。
```
additional_queues_csv
```
（可选）——需绑定的队列开发者名称（DeveloperName）。若调用方提供此列表，则以该列表为准；若省略，则使用默认的
```
CaseQueue
```
、
```
messagingqueue
```
。所有请求的队列必须已存在于目标组织中。
```
profiles_csv
```
（可选）——启用基于配置文件的回退范围；需提供元数据配置文件的全名（例如
```
Standard,ServiceCloud
```
）。若省略此参数，则仅通过用户绑定管理员。
```
skill_visibility
```
（可选，或使用环境变量
```
OMNI_SUPERVISOR_SKILL_VISIBILITY
```
）——取值为
```
AllSkills
```
或
```
AnySkill
```
。若省略此值，则保留现有配置的选择；新配置默认使用
```
AllSkills
```
。
```
config_developer_name
```
（可选，或使用环境变量
```
OMNI_SUPERVISOR_CONFIG_DEVELOPER_NAME
```
；默认值
```
Omni_Supervisor
```
）——要创建或协调的经典版
```
OmniSupervisorConfig.DeveloperName
```
的精确值。当组织存在多个管理员配置时需提供此参数；本工具不会自动猜测候选配置。环境变量
```
OMNI_SUPERVISOR_CONFIG_MASTER_LABEL
```
可用于设置新配置的标签。默认情况下会保留现有标签。

Preconditions and safety

前置条件与安全机制

Target org authenticated via
```
sf
```
CLI, Service Cloud license present,
```
sf
```
CLI ≥ 2.139.6.
Active supervisor users exist; their supervisor access is granted separately by
```
service-omni-supervisor-permset-assign
```
.
Omni-Channel base settings are enabled (
```
service-omni-base-settings-configure
```
) and the monitored queues exist (
```
service-omni-queue-deploy
```
).
Production guardrail: the script computes
```
safe_to_write
```
as
```
IsSandbox
```
OR
```
TrialExpirationDate != null
```
OR
```
OrganizationType
```
in {Developer Edition, Base Edition}, and blocks with no override when it is false. Any unmet precondition returns
```
status: blocked
```
with a
```
blocking_issue
```
and a click-path.

目标组织已通过
```
sf
```
CLI完成认证，具备Service Cloud许可证，且
```
sf
```
CLI版本≥2.139.6。
已存在活跃的管理员用户；管理员权限需通过
```
service-omni-supervisor-permset-assign
```
单独授予。
Omni-Channel基础设置已启用（可通过
```
service-omni-base-settings-configure
```
配置），且受监控队列已存在（可通过
```
service-omni-queue-deploy
```
部署）。
生产环境防护机制：脚本会计算
```
safe_to_write
```
值，当目标组织为沙箱环境（
```
IsSandbox
```
）、试用版（
```
TrialExpirationDate != null
```
）或组织类型为开发者版/基础版时，该值为
```
true
```
；若值为
```
false
```
，则脚本会阻止部署且无覆盖选项。任何未满足的前置条件都会返回
```
status: blocked
```
，并附带
```
blocking_issue
```
及操作路径。

Run

运行方式

One script does detect, deploy, and verify:

bash

bash scripts/deploy-and-report.sh <org-alias> [supervisor_count] [additional_queues_csv] [profiles_csv] [skill_visibility] [config_developer_name]

It resolves the deploy artifact's tokens from live org state (discovered supervisor users, verified queues, and — only when

profiles_csv

is given — validated profiles), materializes the selected DeveloperName into the metadata filename and package manifest, then re-queries that same selected config to confirm the parent and its companion rows persisted before emitting JSON to stdout. The coordinator (

service-omni-channel-setup-coordinate

) invokes it with the authoritative queue list and selected supervisor config; standalone runs use the canonical defaults.

单个脚本即可完成检测、部署与验证：

bash

bash scripts/deploy-and-report.sh <org-alias> [supervisor_count] [additional_queues_csv] [profiles_csv] [skill_visibility] [config_developer_name]

脚本会从组织的实时状态（已发现的管理员用户、已验证的队列，以及仅当提供

profiles_csv

时的已验证配置文件）解析部署工件的令牌，将选定的DeveloperName写入元数据文件名和包清单，然后重新查询该选定配置以确认父配置及其关联项已持久化，最后向标准输出（stdout）输出JSON。协调工具（

service-omni-channel-setup-coordinate

）会使用权威队列列表和选定的管理员配置调用本脚本；独立运行时则使用默认配置。

Behavior

行为说明

Companions. The deployed config always carries

omniSupervisorConfigUser

(one per supervisor) and

omniSupervisorConfigQueue

(one per monitored queue). It follows the same single-file Metadata deploy shape as

service-omni-service-channel-configure

and

service-omni-presence-status-deploy

Profile scope is a fallback, off by default. Core resolves a supervisor's configuration by

OmniSupervisorConfigUser

first, and only falls back to

OmniSupervisorConfigProfile

— matched against that supervisor's own profile — when the supervisor has no user row (

RealTimeQueueServiceImpl.getSupervisorConfigId

). Because this skill binds every supervisor by user, profile companions are unnecessary and are omitted unless you pass

profiles_csv

. When supplied, values must be metadata fullNames (the

<profile>

element resolves against the fullName —

Standard

ServiceCloud

Admin

— not the SOQL

User.Profile.Name

label); the skill validates each against

sf org list metadata -m Profile

and blocks on any the org does not expose.

Idempotency and surface preservation. Status follows the Metadata deploy component state:

Unchanged

→

reused

Changed

→

updated

Created

→

created

. Any other state is a hard failure rather than a silent

reused

. Before updating an existing parent, the skill snapshots its reference-free

OmniSupervisorConfigAction

and

OmniSupervisorConfigTab

rows, validates that each can be recreated safely, then restores and re-queries them after the deploy. A custom/reference-bearing surface blocks before deployment instead of risking silent loss. When reconciling an existing config or verifying preservation, invoke only this skill; do not invoke

service-omni-supervisor-surface-deploy

, because adding standard rows afterward could mask a preservation failure. The companion surface skill remains responsible only for a separate request to add new standard actions or tabs.

Fail-closed verification. The deploy

status

must be

Succeeded

(not

SucceededPartial

). After the parent config is queryable, the script re-queries the child

OmniSupervisorConfigUser

and

OmniSupervisorConfigQueue

rows and requires at least the intended counts — the parent existing does not prove the companions landed. Every read must return a parseable

.result.records

array; an inconclusive read never counts as zero. Requested queues are validated against

^[A-Za-z0-9_]{1,80}$

before use, and every requested queue must exist or the run blocks (dropping one silently would under-provision the config).

关联配置项：部署的配置始终包含

omniSupervisorConfigUser

（每个管理员对应一个）和

omniSupervisorConfigQueue

（每个受监控队列对应一个）。其单文件Metadata部署格式与

service-omni-service-channel-configure

和

service-omni-presence-status-deploy

一致。

基于配置文件的范围为回退选项，默认关闭：核心系统会优先通过

OmniSupervisorConfigUser

解析管理员的配置，仅当管理员没有对应的用户行时（

RealTimeQueueServiceImpl.getSupervisorConfigId

），才会回退到

OmniSupervisorConfigProfile

——与该管理员自身的配置文件匹配。由于本工具会通过用户绑定所有管理员，因此基于配置文件的关联项并非必需，除非传入

profiles_csv

参数才会包含。若提供该参数，值必须为元数据全名（

<profile>

元素会根据全名解析——如

Standard

、

ServiceCloud

、

Admin

——而非SOQL的

User.Profile.Name

标签）；工具会通过

sf org list metadata -m Profile

验证每个配置文件，若组织未暴露该配置文件则会阻止部署。

幂等性与界面保留：状态遵循Metadata部署组件的状态：

Unchanged

→

reused

（复用），

Changed

→

updated

（更新），

Created

→

created

（创建）。任何其他状态都会视为严重失败，而非静默复用。在更新现有父配置前，工具会对其无引用的

OmniSupervisorConfigAction

和

OmniSupervisorConfigTab

行进行快照，验证是否可以安全重建，然后在部署后恢复并重新查询这些行。若存在自定义/带引用的界面，部署前会阻止操作，避免静默丢失数据。在协调现有配置或验证界面保留时，仅需调用本工具；请勿调用

service-omni-supervisor-surface-deploy

，因为后续添加标准行可能会掩盖界面保留失败的问题。关联界面工具仅负责处理添加新标准操作或标签的单独请求。

失败关闭验证：部署

status

必须为

Succeeded

（成功），而非

SucceededPartial

（部分成功）。父配置可查询后，脚本会重新查询子项

OmniSupervisorConfigUser

和

OmniSupervisorConfigQueue

的行数，要求至少达到预期数量——父配置存在并不代表关联项已部署成功。每次读取必须返回可解析的

.result.records

数组；不确定的读取结果永远不会被视为零。请求的队列会先验证是否符合

^[A-Za-z0-9_]{1,80}$

格式，且每个请求的队列必须存在，否则运行会被阻止（静默丢弃队列会导致配置不足）。

Output contract

输出约定

A single JSON object to stdout.

status

is one of

created

updated

reused

, or

blocked

. The object also carries

config_developer_name

config_id

skill_visibility

surface_preservation

snapshot/restoration counts,

supervisor_users_bound

supervisor_users_count

queues_bound

queues_count

queue_source

(

caller_supplied

canonical_default

), the re-queried

verified_companion_user_count

verified_companion_queue_count

deploy_id

state

manual_actions

, and

blocking_issue

blocking_issue

null

unless

status: blocked

, in which case it names the missing prerequisite with a click-path in

manual_actions

. Re-running an unchanged config returns

reused

and performs no functional change.

Org-side spot-check:

sql

SELECT Id, DeveloperName, MasterLabel FROM OmniSupervisorConfig WHERE DeveloperName='<config_developer_name>'
SELECT COUNT(Id) FROM OmniSupervisorConfigUser  WHERE OmniSupervisorConfigId = :configId
SELECT COUNT(Id) FROM OmniSupervisorConfigQueue WHERE OmniSupervisorConfigId = :configId

向标准输出（stdout）返回单个JSON对象。

status

取值为

created

、

updated

、

reused

或

blocked

。该对象还包含

config_developer_name

、

config_id

、

skill_visibility

、

surface_preservation

（界面保留）的快照/恢复计数、

supervisor_users_bound

supervisor_users_count

、

queues_bound

queues_count

、

queue_source

（

caller_supplied

或

canonical_default

）、重新查询得到的

verified_companion_user_count

verified_companion_queue_count

、

deploy_id

、

state

、

manual_actions

和

blocking_issue

。

blocking_issue

默认为

null

，仅当

status: blocked

时会指定缺失的前置条件，并在

manual_actions

中提供操作路径。重新运行未更改的配置会返回

reused

，且不会执行任何功能性更改。

组织端抽查SQL：

sql

SELECT Id, DeveloperName, MasterLabel FROM OmniSupervisorConfig WHERE DeveloperName='<config_developer_name>'
SELECT COUNT(Id) FROM OmniSupervisorConfigUser  WHERE OmniSupervisorConfigId = :configId
SELECT COUNT(Id) FROM OmniSupervisorConfigQueue WHERE OmniSupervisorConfigId = :configId

Limitations

局限性

Populates user and queue companions (plus optional profile scope). Existing reference-free Action and Tab rows are preserved across an update; new standard rows are added separately by
```
service-omni-supervisor-surface-deploy
```
. Custom-action, FlexiPage, AWS-dashboard, and AI-agent rows require external references and therefore block an update rather than being reconstructed incompletely.
Binds supervisor users discovered by the
```
supervisor{N}.<suffix>@example.com
```
pattern; it does not create them.
Does not change AgentWork sharing because that org-wide access control is separate from
```
OmniSupervisorConfig
```
. Use
```
service-omni-agent-work-sharing-configure
```
for supported metadata detection and the explicitly confirmed
```
Private
```
to
```
Read
```
operation.
Does not activate the Command Center V2 runtime (a separate settings flip).

仅填充用户和队列关联项（以及可选的配置文件范围）。更新配置时会保留现有无引用的Action和Tab行；新标准行需通过
```
service-omni-supervisor-surface-deploy
```
单独添加。自定义操作、FlexiPage、AWS仪表板和AI-agent行需要外部引用，因此会阻止更新，避免不完整重建。
仅绑定通过
```
supervisor{N}.<suffix>@example.com
```
模式发现的管理员用户；不创建用户。
不会更改AgentWork共享设置，因为该组织级访问控制与
```
OmniSupervisorConfig
```
是分离的。如需支持元数据检测以及明确确认的从
```
Private
```
到
```
Read
```
的操作，请使用
```
service-omni-agent-work-sharing-configure
```
。
不会激活Command Center V2运行时（需单独设置开关）。

References

参考资料

File When to read

File	When to read
`references/api-notes.md`	On a deploy failure — field-by-field `OmniSupervisorConfig` schema and companion sObject semantics
`assets/force-app/main/default/omniSupervisorConfigs/Omni_Supervisor.omniSupervisorConfig-meta.xml`	The token-templated deploy artifact ( `__MASTER_LABEL__` , `__SUPERVISOR_USERS_XML__` , `__PROFILE_SCOPE_XML__` , `__QUEUE_LIST_XML__` , `__SKILL_VISIBILITY__` ); it is materialized under the selected DeveloperName at runtime
`assets/package.xml` , `assets/sfdx-project.json`	Manifest and project scaffold materialized into the temp deploy dir

references/api-notes.md

On a deploy failure — field-by-field

OmniSupervisorConfig

schema and companion sObject semantics

assets/force-app/main/default/omniSupervisorConfigs/Omni_Supervisor.omniSupervisorConfig-meta.xml

The token-templated deploy artifact (

__MASTER_LABEL__

__SUPERVISOR_USERS_XML__

__PROFILE_SCOPE_XML__

__QUEUE_LIST_XML__

__SKILL_VISIBILITY__

); it is materialized under the selected DeveloperName at runtime

assets/package.xml

assets/sfdx-project.json

Manifest and project scaffold materialized into the temp deploy dir

文件阅读场景

文件	阅读场景
`references/api-notes.md`	部署失败时——查看 `OmniSupervisorConfig` 的逐字段架构及关联sObject语义
`assets/force-app/main/default/omniSupervisorConfigs/Omni_Supervisor.omniSupervisorConfig-meta.xml`	令牌模板化的部署工件（包含 `__MASTER_LABEL__` 、 `__SUPERVISOR_USERS_XML__` 、 `__PROFILE_SCOPE_XML__` 、 `__QUEUE_LIST_XML__` 、 `__SKILL_VISIBILITY__` ）；运行时会根据选定的DeveloperName实例化该文件
`assets/package.xml` , `assets/sfdx-project.json`	清单和项目脚手架，会被实例化到临时部署目录

references/api-notes.md

部署失败时——查看

OmniSupervisorConfig

的逐字段架构及关联sObject语义

assets/force-app/main/default/omniSupervisorConfigs/Omni_Supervisor.omniSupervisorConfig-meta.xml

令牌模板化的部署工件（包含

__MASTER_LABEL__

、

__SUPERVISOR_USERS_XML__

、

__PROFILE_SCOPE_XML__

、

__QUEUE_LIST_XML__

、

__SKILL_VISIBILITY__

）；运行时会根据选定的DeveloperName实例化该文件

assets/package.xml

assets/sfdx-project.json

清单和项目脚手架，会被实例化到临时部署目录