service-omni-supervisor-config-deploy

service-omni-supervisor-config-deploy

通过一次 Metadata API 部署，将经典 Omni-Channel Supervisor Configuration（OmniSupervisorConfig）部署到 Salesforce 组织。OmniSupervisorConfig 是完整的 Metadata API 类型，其 XSD 将每个配套项都嵌入为可重复的子元素，因此整个配置（父项及其配套项）都会通过一个 .omniSupervisorConfig-meta.xml 文件原子性地写入；如果部分失败，Salesforce 会一并回滚这些配套项。默认情况下，部署会通过用户明确绑定主管，并列出他们监控的队列；也可选用配置文件范围（请参阅“行为”）。

输入

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 可为新配置设置标签。默认情况下保留现有标签。

前置条件与安全

• 目标组织已通过 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 OR TrialExpirationDate != null OR OrganizationType 属于 {Developer Edition, Base Edition}；如果结果为 false，则会阻止操作，且不提供覆盖方式。任何未满足的前置条件都会返回 status: blocked，并包含 blocking_issue 和点击路径。

运行

一个脚本即可完成检测、部署和验证：

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）会使用权威队列列表和所选主管配置来调用此脚本；独立运行时使用规范默认值。

行为

配套记录。 部署的配置始终包含 omniSupervisorConfigUser（每位主管一条）和 omniSupervisorConfigQueue（每个受监控队列一条）。它采用与 service-omni-service-channel-configure 和 service-omni-presence-status-deploy 相同的单文件 Metadata 部署形式。

配置文件范围仅作后备，默认关闭。 Core 会先通过 OmniSupervisorConfigUser 解析主管的配置；只有当主管没有用户记录时，才会回退到 OmniSupervisorConfigProfile，并与该主管自己的配置文件匹配（RealTimeQueueServiceImpl.getSupervisorConfigId）。由于此技能会按用户绑定每位主管，因此无需配置文件配套记录，除非你传入 profiles_csv。提供该参数时，值必须是 Metadata fullNames（<profile> 元素按 fullName（Standard、ServiceCloud、Admin）解析，而非 SOQL User.Profile.Name 标签）；此技能会使用 sf org list metadata -m Profile 验证每个值，如果组织未公开其中任何一项，就会阻止执行。

幂等性与界面保留。 状态遵循 Metadata 部署组件状态：Unchanged → reused，Changed → updated，Created → created。任何其他状态都会导致硬性失败，而不是静默返回 reused。更新现有父记录之前，此技能会快照其不含引用的 OmniSupervisorConfigAction 和 OmniSupervisorConfigTab 行，验证每行都能安全重建，然后在部署后恢复并重新查询这些行。若界面包含自定义项或带引用的项，则会在部署前阻止执行，而不是冒着静默丢失的风险。协调现有配置或验证保留情况时，只调用此技能；不要调用 service-omni-supervisor-surface-deploy，因为之后添加标准行可能会掩盖保留失败。配套界面技能仅负责处理单独提出的添加新标准操作或标签页的请求。

失败即关闭的验证。 部署 status 必须为 Succeeded（不能是 SucceededPartial）。父配置可查询后，脚本会重新查询子项 OmniSupervisorConfigUser 和 OmniSupervisorConfigQueue，并要求数量至少达到预期值——父记录存在并不能证明配套记录已写入。每次读取都必须返回可解析的 .result.records 数组；无法确定的读取结果绝不会按零处理。使用前会根据 ^[A-Za-z0-9_]{1,80}$ 验证请求的队列名称，且每个请求的队列都必须存在，否则本次运行会被阻止（静默丢弃队列会导致配置不足）。

输出约定

向标准输出写入单个 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。除非 status: blocked，否则 blocking_issue 为 null；如果状态为 blocked，则该字段会指出缺失的前置条件，并在 manual_actions 中提供点击路径。对未发生变化的配置重新运行时会返回 reused，且不会产生任何功能变化。

组织端抽查：

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

限制

• 填充用户和队列关联项（以及可选的配置文件范围）。更新时会保留现有的无引用 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/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	生成到临时部署目录中的清单和项目框架