service-omni-presence-status-deploy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

service-omni-presence-status-deploy

Deploy the sObject-specific

Available_<X>

ServicePresenceStatus bound to that sObject's ServiceChannel, and ensure a universal

Busy

status exists, in one atomic Metadata API deploy. Every Omni agent needs an "available for work" status carrying a channel (so incoming work routes) and an "off-work" status (so they can step away). A presence status binds to exactly one ServiceChannel by DeveloperName, so each routing target needs its own Available status. It pairs with

service-omni-permission-set-assign

, which grants agents access to the statuses this skill deploys, and is invoked once per routing target by

service-omni-channel-setup-coordinate

Target sObject	Available status	Bound channel
`Case`	`Available_Case`	`Cases`
`Incident`	`Available_Incident`	`Incidents`
`MessagingSession`	`Available_Messaging`	`sfdc_livemessage`
`VoiceCall`	`Available_Voice`	`sfdc_phone`

Busy is UI-defined, not metadata-defined. The Omni "Busy vs Online" option is not expressible via the Metadata API — a

ServicePresenceStatus

carries only

<label>

and

<channels>

, and a status with no channels is treated as busy. The conventional busy DeveloperName is simply

Busy

, and most orgs already have one, so this skill reuses an existing

Busy

and deploys the bundled asset only when none exists. A busy status is not required to receive work — the Available status carrying the channel is what routes it.

通过一次原子化Metadata API部署，创建与目标sObject对应的ServiceChannel绑定的

Available_<X>

ServicePresenceStatus，并确保全局

Busy

状态存在。每位Omni Agent都需要一个关联渠道的“工作可用”状态（用于接收路由过来的工作）和一个“离岗”状态（用于暂时离开工作）。在线状态通过DeveloperName与唯一的ServiceChannel绑定，因此每个路由目标都需要专属的Available状态。该技能与

service-omni-permission-set-assign

配合使用——后者为Agent授予访问当前技能所部署状态的权限，且由

service-omni-channel-setup-coordinate

针对每个路由目标调用一次。

Target sObject	Available status	Bound channel
`Case`	`Available_Case`	`Cases`
`Incident`	`Available_Incident`	`Incidents`
`MessagingSession`	`Available_Messaging`	`sfdc_livemessage`
`VoiceCall`	`Available_Voice`	`sfdc_phone`

Busy状态由UI定义，而非元数据定义。Omni的“忙碌 vs 在线”选项无法通过Metadata API实现——

ServicePresenceStatus

仅包含

<label>

和

<channels>

字段，无渠道关联的状态会被视为忙碌状态。常规的忙碌状态DeveloperName为

Busy

，大多数组织已存在该状态，因此本技能会复用现有

Busy

状态，仅在不存在时才部署捆绑的资源。接收工作无需忙碌状态——关联渠道的Available状态才是实现工作路由的关键。

Inputs

bash

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

```
org-alias
```
(required).
```
sobject_type
```
(optional, default
```
Case
```
).

bash

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

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

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
```
) — otherwise the deploy fails with
```
INVALID_TYPE
```
.
The target sObject's ServiceChannel exists (
```
service-omni-service-channel-configure
```
) — otherwise the deploy fails with
```
Value '<channel>' is not valid
```
.
```
Incident
```
requires the Incident Management feature enabled;
```
MessagingSession
```
requires Enhanced Messaging.
The three-way
```
safe_to_write
```
production guard applies.

目标组织已通过
```
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
```
要求启用事件管理功能；
```
MessagingSession
```
要求启用增强型消息功能
已启用三重
```
safe_to_write
```
生产环境保护机制

Run

deploy-and-report.sh

deploys the

Available_<X>

status (and

Busy

only when the org has none) in one Metadata API call, then maps the per-component

files[].state

to a skill status:

```
reused
```
— every component
```
Unchanged
```
.
```
updated
```
— any component
```
Changed
```
, none
```
Created
```
.
```
created
```
— any component
```
Created
```
.

There is no separate detect step — Salesforce's

files[].state

is authoritative. The deploy uses explicit

--metadata

flags (never

--source-dir

) so unrelated assets cannot piggyback.

deploy-and-report.sh

通过一次Metadata API调用部署

Available_<X>

状态（仅当组织不存在

Busy

状态时才部署该状态），随后将每个组件的

files[].state

映射为技能状态：

```
reused
```
——所有组件均为
```
Unchanged
```
（未变更）
```
updated
```
——存在组件为
```
Changed
```
（已变更），无组件为
```
Created
```
（已创建）
```
created
```
——存在组件为
```
Created
```
（已创建）

无需单独的检测步骤——Salesforce的

files[].state

为权威依据。部署使用明确的

--metadata

参数（绝不使用

--source-dir

），以避免无关资源被附带部署。

Behavior

Reuse over redeploy. An existing

Busy

is detected and left untouched; only a missing one is deployed. The skill never deletes or overwrites presence statuses it did not deploy — orgs often carry other custom statuses (

Omni_OnBreak

availableForMiaw

Schema. The XML omits

<statusType>

(removed in v66; online/busy is inferred from the presence of

<channels>

), and the skill never SOQL-queries

StatusType

(not queryable on v66 — only Id, DeveloperName, MasterLabel are reliable).

Available_Messaging

binds the standard

sfdc_livemessage

channel that Enhanced Messaging always ships.

优先复用，避免重复部署。系统会检测现有

Busy

状态并保持其不变；仅在不存在时才部署该状态。本技能绝不会删除或覆盖非自身部署的在线状态——组织通常会包含其他自定义状态（如

Omni_OnBreak

、

availableForMiaw

）。

架构说明。XML文件中省略了

<statusType>

字段（该字段在v66版本中已移除；在线/忙碌状态由是否存在

<channels>

字段推断），且本技能从不通过SOQL查询

StatusType

（v66版本中该字段不可查询——仅Id、DeveloperName、MasterLabel字段可靠）。

Available_Messaging

状态与增强型消息功能默认提供的标准

sfdc_livemessage

渠道绑定。

Output contract

A single JSON object with

status

∈

created

reused

updated

blocked

sobject_type

, a

presence_statuses

array (each with

developer_name

label

channels

state

, and — for

Busy

—

reused_existing

deploy_id

manual_actions

, and

blocking_issue

```
blocked
```
— deploy failed (missing prereq, schema mismatch, or org error);
```
manual_actions
```
names the prerequisite skill to run and
```
blocking_issue
```
is an operator-friendly translation of the Salesforce error.
```
deploy_id
```
is populated on every run (Salesforce issues one even for no-op deploys).

输出为单个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也会生成该ID）

Limitations

Deploys only the
```
Available_<X>
```
+
```
Busy
```
pair — custom statuses require forking the
```
assets/servicePresenceStatuses/*.xml
```
.
Only
```
Case
```
,
```
Incident
```
,
```
MessagingSession
```
,
```
VoiceCall
```
— extend by adding a dispatcher branch and a matching asset.
Does not configure
```
PresenceUserConfig
```
capacity or decline reasons, and never deletes existing statuses.

仅部署
```
Available_<X>
```
+
```
Busy
```
状态对——自定义状态需复刻
```
assets/servicePresenceStatuses/*.xml
```
文件进行配置
仅支持
```
Case
```
、
```
Incident
```
、
```
MessagingSession
```
、
```
VoiceCall
```
——如需扩展，需添加调度分支及匹配的资源
不配置
```
PresenceUserConfig
```
容量或拒绝原因，且绝不会删除现有状态

References

File	When to read
`assets/package.xml`	Load when preparing the explicit Metadata API deployment for the selected Available status and the optional Busy status
`references/api-notes.md`	On unexpected deploy behavior — the v66 XML schema (no `statusType` ), channel-binding rules, and MessagingSession-specific notes

文件	阅读时机
`assets/package.xml`	为选定的Available状态及可选的Busy状态准备显式Metadata API部署时查阅
`references/api-notes.md`	出现意外部署行为时查阅——包含v66版本XML架构（无 `statusType` 字段）、渠道绑定规则及MessagingSession专属说明