service-omni-service-channel-configure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

service-omni-service-channel-configure

Ensure exactly one

ServiceChannel

is present for a routable sObject, reusing whatever is already bound (Salesforce standard or a pre-existing custom channel) and deploying the skill's canonical v66 template only when none exists. Salesforce enforces one ServiceChannel per

RelatedEntity

, so the skill detects first and never deploys blindly — deploying a second channel for an sObject that already has one fails with "This Salesforce object is already in use by another Service channel." It handles one sObject per call; callers configuring multiple sObjects invoke it once for each sObject, after

service-omni-base-settings-configure

has enabled Omni-Channel.

sObject	Standard channel (if any)	Canonical asset
`Case`	`Cases`	`Cases.serviceChannel-meta.xml`
`Incident`	none (Incident Management sObject)	`Incidents.serviceChannel-meta.xml` — deployed on first run
`MessagingSession`	`sfdc_livemessage`	`MessagingSessions.serviceChannel-meta.xml` — deployed only if the standard channel is missing
`VoiceCall`	`sfdc_phone`	`VoiceCalls.serviceChannel-meta.xml` — deployed only if the standard channel is missing

确保可路由sObject仅存在一个

ServiceChannel

，重用已绑定的任何渠道（Salesforce标准渠道或预先存在的自定义渠道），仅在不存在渠道时部署该技能的v66规范模板。Salesforce强制每个

RelatedEntity

对应一个ServiceChannel，因此该技能会先进行检测，绝不会盲目部署——如果为已存在渠道的sObject部署第二个渠道，会失败并提示“此Salesforce对象已被另一个服务渠道使用。”每次调用仅处理一个sObject；配置多个sObject的调用方需为每个sObject调用一次该技能，且需在

service-omni-base-settings-configure

启用Omni-Channel之后调用。

sObject	标准渠道（如有）	规范资产
`Case`	`Cases`	`Cases.serviceChannel-meta.xml`
`Incident`	无（事件管理sObject）	`Incidents.serviceChannel-meta.xml` — 首次运行时部署
`MessagingSession`	`sfdc_livemessage`	`MessagingSessions.serviceChannel-meta.xml` — 仅在标准渠道缺失时部署
`VoiceCall`	`sfdc_phone`	`VoiceCalls.serviceChannel-meta.xml` — 仅在标准渠道缺失时部署

Inputs

bash

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

```
org-alias
```
(required).

sobject_type

(optional, default

Case

) — one of

Case | Incident | MessagingSession | VoiceCall

bash

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

```
org-alias
```
（必填）。

sobject_type

（可选，默认值

Case

）——可选值为

Case | Incident | MessagingSession | VoiceCall

。

Preconditions and safety

前置条件与安全要求

Target org authenticated via
```
sf
```
CLI (My Domain URL), Service Cloud license,
```
sf
```
CLI ≥ 2.139.6.
Omni-Channel base settings enabled (
```
service-omni-base-settings-configure
```
) —
```
ServiceChannel
```
is only queryable/writable when
```
enableOmniChannel=true
```
; a
```
INVALID_TYPE
```
on deploy means base settings are off.
```
Incident
```
requires the Incident Management feature enabled;
```
MessagingSession
```
requires Enhanced Messaging. The skill verifies
```
EntityDefinition
```
first and blocks with a click-path when the target sObject is absent.

目标组织已通过
```
sf
```
CLI（我的域名URL）完成身份验证，拥有Service Cloud许可证，
```
sf
```
CLI版本≥2.139.6。
Omni-Channel基础设置已启用（
```
service-omni-base-settings-configure
```
）——仅当
```
enableOmniChannel=true
```
时，
```
ServiceChannel
```
才可查询/写入；部署时出现
```
INVALID_TYPE
```
错误意味着基础设置未开启。
```
Incident
```
要求启用事件管理功能；
```
MessagingSession
```
要求启用增强消息功能。该技能会先验证
```
EntityDefinition
```
，若目标sObject不存在则通过点击路径阻止操作。

Run

运行方式

deploy-and-report.sh

performs the prereq check, discovery, and (only when needed) deploy, then emits the report:

Prereq — confirm the target sObject is queryable via
```
EntityDefinition
```
; block with a click-path otherwise.
Discover — query the Tooling API for a
```
ServiceChannel
```
with
```
RelatedEntity = <sobject_type>
```
.
```
ServiceChannel
```
is a Tooling entity on v66; the standard Data API returns
```
INVALID_TYPE
```
. A hit means reuse.

Deploy (only when nothing was found) —

sf project deploy start

of the canonical XML (

Cases

Incidents

MessagingSessions

VoiceCalls

); a

Changed

state is

created

Unchanged

reused

deploy-and-report.sh

会执行前置检查、发现操作，仅在需要时进行部署，然后生成报告：

前置检查——通过
```
EntityDefinition
```
确认目标sObject可查询；否则通过点击路径阻止操作。
发现——通过Tooling API查询
```
RelatedEntity = <sobject_type>
```
的
```
ServiceChannel
```
。v66版本中
```
ServiceChannel
```
是Tooling实体；标准Data API会返回
```
INVALID_TYPE
```
。若查询到结果则重用该渠道。
部署（仅在未找到渠道时执行）——使用
```
sf project deploy start
```
部署规范XML文件（
```
Cases
```
|
```
Incidents
```
|
```
MessagingSessions
```
|
```
VoiceCalls
```
）；状态为
```
Changed
```
表示“已创建”，
```
Unchanged
```
表示“已重用”。

Behavior

行为逻辑

Detect-then-reuse-or-deploy. Because Salesforce rejects a second channel per

RelatedEntity

, deploy-first is unsafe: an operator who renamed the standard

Cases

channel would hit the "already in use" error instead of gracefully reusing. Tooling discovery is fast and returns both the reuse decision and the discovered

DeveloperName

in one call. The trade-off is that the skill cannot tell "our canonical shape matches" from "some custom channel is bound" — an operator with a non-canonical channel gets

reused

and their channel is left untouched (v1 never overwrites operator state).

Capacity model. The canonical assets use

TAB_BASED

for every variant.

STATUS_BASED

requires companion fields whose full schema is undocumented, so it is out of scope; per-agent capacity tuning belongs to

PresenceUserConfig.Capacity

, not this skill.

Concurrency. If a deploy fails with "already in use," another process created the channel between discovery and deploy; the skill soft-fails and a re-run reuses it.

先检测，再重用或部署。由于Salesforce不允许每个

RelatedEntity

对应多个渠道，先部署的方式不安全：如果操作人员重命名了标准

Cases

渠道，会触发“已被使用”错误，而非优雅地重用该渠道。Tooling发现操作速度快，一次调用即可返回重用决策和已发现的

DeveloperName

。权衡之处在于，该技能无法区分“渠道符合规范形态”和“绑定了某个自定义渠道”——拥有非规范渠道的操作人员会得到“已重用”状态，其渠道会保持原样（v1版本绝不会覆盖操作人员的配置）。

容量模型。规范资产的所有变体均使用

TAB_BASED

。

STATUS_BASED

需要配套字段，但其完整架构未公开，因此不在本技能的范围内；针对每个Agent的容量调整属于

PresenceUserConfig.Capacity

的范畴，与本技能无关。

并发处理。如果部署失败并提示“已被使用”，说明在发现操作和部署操作之间，另一个进程创建了该渠道；此时技能会软失败，重新运行即可重用该渠道。

Output contract

输出约定

A single JSON object per invocation with

status

∈

created

reused

blocked

, plus

sobject_type

channel_developer_name

channel_id

channel_origin

target_capacity_model

target_related_entity_type

before_state

deploy_id

manual_actions

, and

blocking_issue

```
reused
```
— an existing channel was found (discovery hit, or a deploy returned
```
Unchanged
```
).
```
created
```
— no channel existed; the canonical XML deployed with
```
Changed
```
.
```
blocked
```
— the sObject is not on the org, base settings are off (
```
INVALID_TYPE
```
), or a race left the channel already in use.
```
channel_origin
```
is one of
```
salesforce_standard
```
(an
```
sfdc_*
```
name or
```
Cases
```
),
```
canonical_asset
```
(a shipped asset name),
```
canonical_template
```
(freshly deployed this run), or
```
custom
```
(a pre-existing org-specific channel).
```
channel_id
```
is populated whenever a channel exists (
```
null
```
on
```
blocked
```
);
```
deploy_id
```
is populated only on the deploy branch;
```
blocking_issue
```
is non-null only when
```
status: blocked
```
.

每次调用返回一个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不在组织中、基础设置未开启（
```
INVALID_TYPE
```
错误），或因竞态条件导致渠道已被使用。
```
channel_origin
```
的取值为
```
salesforce_standard
```
（名称为
```
sfdc_*
```
或
```
Cases
```
）、
```
canonical_asset
```
（已发布的资产名称）、
```
canonical_template
```
（本次运行新部署的模板）或
```
custom
```
（预先存在的组织特定渠道）。
```
channel_id
```
会在渠道存在时填充（
```
blocked
```
状态下为
```
null
```
）；
```
deploy_id
```
仅在部署分支中填充；
```
blocking_issue
```
仅在
```
status: blocked
```
时非空。

Limitations

局限性

One sObject per invocation.

Only

Case

Incident

MessagingSession

VoiceCall

are supported — extend by adding an

assets/force-app/main/default/serviceChannels/<Name>.serviceChannel-meta.xml

file and a dispatcher branch.

Always reuses an existing channel; it does not reset a mis-configured channel to canonical shape.

每次调用仅处理一个sObject。

仅支持

Case

、

Incident

、

MessagingSession

、

VoiceCall

——如需扩展，需添加

assets/force-app/main/default/serviceChannels/<Name>.serviceChannel-meta.xml

文件和调度分支。

始终重用现有渠道；不会将配置错误的渠道重置为规范形态。

References

参考资料

File	When to read
`references/api-notes.md`	On unexpected discovery results, deploy failures, or sObject-specific schema questions

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