service-omni-service-channel-configure

service-omni-service-channel-configure

确保可路由的 sObject 恰好存在一个 ServiceChannel，复用已绑定的通道（无论是 Salesforce 标准通道还是已有的自定义通道），并且仅当不存在时才部署该技能的规范 v66 模板。Salesforce 强制要求每个 RelatedEntity 只能有一个 ServiceChannel，因此该技能会先检测，绝不会盲目部署——如果某个 sObject 已有关联通道，再部署第二个通道会失败，并报错 "This Salesforce object is already in use by another Service channel."。每次调用仅处理一个 sObject；配置多个 sObject 的调用方需对每个 sObject 分别调用一次，并且要先通过 service-omni-base-settings-configure 启用 Omni-Channel。

sObject	标准通道（如有）	规范资源
Case	Cases	Cases.serviceChannel-meta.xml
Incident	无（Incident Management sObject）	Incidents.serviceChannel-meta.xml — 首次运行时部署
MessagingSession	sfdc_livemessage	MessagingSessions.serviceChannel-meta.xml — 仅当标准通道缺失时部署
VoiceCall	sfdc_phone	VoiceCalls.serviceChannel-meta.xml — 仅当标准通道缺失时部署

输入

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

• org-alias（必需）。
• sobject_type（可选，默认值为 Case）— 可选值：Case | Incident | MessagingSession | VoiceCall。

前置条件与安全性

• 目标组织已通过 sf CLI（My Domain URL）完成身份验证，拥有 Service Cloud 许可证，且 sf CLI ≥ 2.139.6。
• 已启用 Omni-Channel 基础设置（service-omni-base-settings-configure）——仅当 enableOmniChannel=true 时，才能查询或写入 ServiceChannel；部署时出现 INVALID_TYPE 表示基础设置未启用。
• Incident 需要启用 Incident Management 功能；MessagingSession 需要启用 Enhanced Messaging。该技能会先验证 EntityDefinition，如果目标 sObject 不存在，则会提供点击路径并阻止操作。

运行

deploy-and-report.sh 会执行前置条件检查、发现以及（仅在需要时）部署，然后输出报告：

1. 前置条件 — 确认可通过 EntityDefinition 查询目标 sObject；否则提供点击路径并阻止操作。
2. 发现 — 通过 Tooling API 查询 RelatedEntity = <sobject_type> 的 ServiceChannel。v66 中的 ServiceChannel 是 Tooling 实体；标准 Data API 会返回 INVALID_TYPE。查询命中表示复用。
3. 部署（仅当未找到任何通道时）— 通过 sf project deploy start 部署规范 XML（Cases | Incidents | MessagingSessions | VoiceCalls）；状态为 Changed 表示已创建，Unchanged 表示已复用。

行为

先检测，再复用或部署。 由于 Salesforce 不允许每个 RelatedEntity 关联第二个通道，先部署并不安全：如果操作员重命名了标准 Cases 通道，就会遇到 "already in use" 错误，而无法顺利复用。Tooling 发现速度快，并可在一次调用中返回复用决策和发现的 DeveloperName。其取舍是，该技能无法区分“与我们的规范结构一致”和“已绑定某个自定义通道”——对于非规范通道，操作员会得到 reused，且通道不会被修改（v1 绝不会覆盖操作员状态）。

容量模型。 所有变体的规范资源均使用 TAB_BASED。STATUS_BASED 需要配套字段，但其完整架构尚未文档化，因此不在此技能的范围内；每个 Agent 的容量调整应通过 PresenceUserConfig.Capacity 进行，而非使用此技能。

并发。 如果部署失败并提示 "already in use"，说明另一个进程在发现和部署之间创建了该通道；该技能会软失败，重新运行即可复用该通道。

输出约定

每次调用返回一个 JSON 对象，其中 status ∈ created | reused | blocked，并包含 sobject_type、channel_developer_name、channel_id、channel_origin、target_capacity_model、target_related_entity_type、before_state、deploy_id、manual_actions 和 blocking_issue。

• reused — 找到了现有渠道（发现命中，或部署返回 Unchanged）。
• created — 不存在渠道；规范 XML 部署结果为 Changed。
• blocked — 该 sObject 不在 org 中、基础设置已关闭（INVALID_TYPE），或竞态导致渠道已在使用。
• channel_origin 的取值为 salesforce_standard（名称以 sfdc_* 开头或为 Cases）、canonical_asset（随附资源名称）、canonical_template（本次运行中新部署）、custom（org 中预先存在的专用渠道）。
• 只要渠道存在，就会填充 channel_id（blocked 时为 null）；仅在部署分支中填充 deploy_id；只有 status: blocked 时 blocking_issue 才非空。

限制

• 每次调用处理一个 sObject。
• 仅支持 Case、Incident、MessagingSession、VoiceCall — 如需扩展，请添加 assets/force-app/main/default/serviceChannels/<Name>.serviceChannel-meta.xml 文件和一个 dispatcher 分支。
• 始终复用现有渠道；不会将配置错误的渠道重置为规范形态。

参考资料

文件	阅读时机
references/api-notes.md	遇到意外发现结果、部署失败或 sObject 特定架构问题时