service-omni-presence-status-deploy

service-omni-presence-status-deploy

通过一次原子 Metadata API 部署，部署绑定到对应 sObject 的 ServiceChannel 的 sObject 专属 Available_<X> ServicePresenceStatus，并确保存在通用 Busy 状态。每个 Omni Agent 都需要一个携带渠道的“可接单”状态（以便路由传入的工作），以及一个“下班”状态（以便暂时离开）。一个 presence status 只能通过 DeveloperName 绑定到一个 ServiceChannel，因此每个路由目标都需要自己的 Available 状态。它与 service-omni-permission-set-assign 配合使用，后者会授予 Agent 访问此技能部署的状态的权限；service-omni-channel-setup-coordinate 会针对每个路由目标调用一次此技能。

目标 sObject	Available 状态	绑定渠道
Case	Available_Case	Cases
Incident	Available_Incident	Incidents
MessagingSession	Available_Messaging	sfdc_livemessage
VoiceCall	Available_Voice	sfdc_phone

Busy 由 UI 定义，而非由元数据定义。 Omni 中的“Busy vs Online”选项无法通过 Metadata API 表达——ServicePresenceStatus 仅包含 <label> 和 <channels>，没有渠道的状态会被视为忙碌。惯用的忙碌状态 DeveloperName 就是 Busy，而大多数组织中已经存在该状态，因此此技能会复用现有的 Busy，仅在不存在时才部署随附资产。接收工作不需要忙碌状态——携带渠道的 Available 状态才负责路由工作。

输入

bash scripts/deploy-and-report.sh <org-alias> [Case|Incident|MessagingSession|VoiceCall]

• org-alias（必填）。
• sobject_type（可选，默认值为 Case）。

前提条件与安全

• 目标组织已通过 sf CLI 进行身份验证（My Domain URL），具有 Service Cloud 许可证，且 sf CLI ≥ 2.139.6。
• 已启用 Omni-Channel 基本设置（service-omni-base-settings-configure），否则部署会失败并返回 INVALID_TYPE。
• 目标 sObject 的 ServiceChannel 已存在（service-omni-service-channel-configure），否则部署会失败并返回 Value '<channel>' is not valid。Incident 需要启用 Incident Management 功能；MessagingSession 需要启用 Enhanced Messaging。
• 适用三重 safe_to_write 生产环境防护。

运行

deploy-and-report.sh 会在一次 Metadata API 调用中部署 Available_<X> 状态（仅当组织中不存在 Busy 时才部署该状态），然后将每个组件的 files[].state 映射为技能状态：

• reused — 所有组件均为 Unchanged。
• updated — 至少一个组件为 Changed，且没有组件为 Created。
• created — 至少一个组件为 Created。

没有单独的检测步骤——Salesforce 的 files[].state 是权威依据。部署使用显式的 --metadata 标志（绝不使用 --source-dir），因此无关资产无法搭载部署。

行为

优先复用，而非重新部署。 检测到现有的 Busy 后会保留不动；仅在缺失时部署。此技能绝不会删除或覆盖其未部署的 presence status——组织通常还会有其他自定义状态（Omni_OnBreak、availableForMiaw）。

架构。 XML 中省略 <statusType>（该字段已在 v66 中移除；online/busy 会根据是否存在 <channels> 推断），且此技能绝不会通过 SOQL 查询 StatusType（它在 v66 上不可查询——只有 Id、DeveloperName、MasterLabel 可靠）。Available_Messaging 绑定到 Enhanced Messaging 始终附带的标准 sfdc_livemessage 渠道。

输出契约

单个 JSON 对象，包含 status（取值为 created | reused | updated | blocked）、sobject_type、presence_statuses 数组（每项包含 developer_name、label、channels、state，且对于 Busy 还包含 reused_existing）、deploy_id、manual_actions 和 blocking_issue。

• blocked — 部署失败（缺少前置条件、架构不匹配或组织错误）；manual_actions 会列出需要运行的前置条件技能，blocking_issue 会将 Salesforce 错误转换为便于操作人员理解的说明。
• 每次运行都会填充 deploy_id（即使是无操作部署，Salesforce 也会生成一个）。

限制

• 仅部署 Available_<X> + Busy 这一对状态——自定义状态需要分叉 assets/servicePresenceStatuses/*.xml。
• 仅支持 Case、Incident、MessagingSession、VoiceCall——添加一个分发分支和匹配的资源即可扩展。
• 不配置 PresenceUserConfig 容量或拒绝原因，也绝不会删除现有状态。

参考资料

文件	阅读时机
assets/package.xml	准备针对所选 Available 状态和可选 Busy 状态的显式 Metadata API 部署时加载
references/api-notes.md	部署行为异常时阅读——v66 XML 架构（不含 statusType）、渠道绑定规则以及 MessagingSession 特有说明