service-omni-skills-based-routing-configure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

service-omni-skills-based-routing-configure

配置Omni基于技能的路由（service-omni-skills-based-routing-configure）

Make agents routable by Omni skills-based routing (SBR). A routable agent needs the Skill and a SkillUser junction assigning that skill to the agent's user.

SkillUser

is the classic Omni-Channel model written by Setup > Skills > Assign Users and evaluated when work has skill requirements. This skill ensures both, idempotently, for one skill across a set of active agent users.

ServiceResource

and

ServiceResourceSkill

are the Field Service skill model. On a plain Service Cloud org,

ServiceResource.IsActive

is not writable or queryable, so a newly created resource remains inactive and the junction is rejected. This skill therefore uses the supported, license-appropriate

SkillUser

path.

通过Omni基于技能的路由（SBR）实现座席可路由。可路由的座席需要拥有Skill，以及将该技能分配给座席用户的SkillUser关联对象。

SkillUser

是经典的Omni-Channel模型，可通过Setup > Skills > Assign Users进行配置，当工作项有技能要求时会被调用。本技能可幂等性地为一组活跃座席用户配置所需的技能及关联关系。

ServiceResource

和

ServiceResourceSkill

是Field Service的技能模型。在纯Service Cloud组织中，

ServiceResource.IsActive

字段不可写且不可查询，因此新创建的资源会保持非活跃状态，关联关系会被拒绝。因此本技能采用受支持且符合许可要求的

SkillUser

路径。

Inputs

输入参数

bash

bash scripts/configure-and-report.sh <org-alias> <skill_developer_name> [agent_members_csv] [skill_master_label]

```
org-alias
```
(required).
```
skill_developer_name
```
(required). The Omni
```
Skill
```
DeveloperName to ensure and bind (e.g.
```
Omni_Demo_Voice
```
).
```
agent_members_csv
```
(optional). Comma-separated agents to make skill-routable — each token a Username (
```
…@…
```
) or a 15/18-char User Id (
```
005…
```
). May also be supplied via
```
AGENT_MEMBERS_CSV
```
. When omitted, the skill blocks (it will not guess which agents to skill).
```
skill_master_label
```
(optional). MasterLabel used only when the skill must be created; defaults to a title-cased form of the DeveloperName.

bash

bash scripts/configure-and-report.sh <org-alias> <skill_developer_name> [agent_members_csv] [skill_master_label]

```
org-alias
```
（必填）。
```
skill_developer_name
```
（必填）。要确保存在并绑定的Omni
```
Skill
```
的DeveloperName（例如：
```
Omni_Demo_Voice
```
）。
```
agent_members_csv
```
（可选）。逗号分隔的需设置为技能可路由的座席——每个元素为用户名（
```
…@…
```
）或15/18位用户ID（
```
005…
```
）。也可通过环境变量
```
AGENT_MEMBERS_CSV
```
提供。若省略该参数，本技能将停止执行（不会自动猜测要配置的座席）。
```
skill_master_label
```
（可选）。仅当需要创建技能时使用的MasterLabel；默认值为DeveloperName的标题化形式。

Preconditions and safety

前置条件与安全要求

Target org authenticated via
```
sf
```
CLI, Service Cloud license,
```
sf
```
CLI ≥ 2.139.6.
Omni-Channel base settings enabled with skills-based routing turned on (
```
service-omni-base-settings-configure
```
).
The named agents exist and are active (
```
service-omni-agent-users-create
```
).
The three-way
```
safe_to_write
```
production guard applies.

目标组织已通过
```
sf
```
CLI完成认证，拥有Service Cloud许可，且
```
sf
```
CLI版本≥2.139.6。
Omni-Channel基础设置已启用，且基于技能的路由已开启（可通过
```
service-omni-base-settings-configure
```
技能配置）。
指定的座席已存在且处于活跃状态（可通过
```
service-omni-agent-users-create
```
技能创建）。
启用了三方
```
safe_to_write
```
生产环境保护机制。

Run

运行方式

configure-and-report.sh

proceeds in two idempotent phases, each detect-before-write:

Skill — query
```
Skill
```
by DeveloperName. Present → reused; absent → deploy a
```
Skill
```
component via the Metadata API and re-query for its Id.
SkillUser — query existing
```
SkillUser
```
records for the Skill and resolved users, then create only missing (
```
SkillId
```
,
```
UserId
```
) bindings via REST DML. A concurrent
```
DUPLICATE_VALUE
```
is reconciled as reused.

configure-and-report.sh

分为两个幂等阶段执行，每个阶段均先检测再写入：

Skill——通过DeveloperName查询
```
Skill
```
。若已存在则复用；若不存在则通过Metadata API部署一个
```
Skill
```
组件，并重查询其ID。
SkillUser——查询该技能与已解析用户的现有
```
SkillUser
```
记录，然后仅通过REST DML创建缺失的（
```
SkillId
```
,
```
UserId
```
）绑定关系。若出现并发
```
DUPLICATE_VALUE
```
错误，将自动处理为复用已有绑定。

Behavior

行为特性

Idempotent + non-destructive. Existing skills and bindings are reused; the skill never deletes or reassigns anything it did not create, so re-runs converge without duplication. Only active users are resolved — an inactive user cannot be routed work, so it is reported rather than silently skilled.

Partial safety. If some bindings succeed and others fail, the status is

partial

with per-agent errors in

blocking_issue

; the successful bindings are left in place (each junction is an independent write).

幂等性 + 非破坏性。已有的技能和绑定关系会被复用；本技能绝不会删除或重新分配其未创建的内容，因此重复执行不会产生重复内容，最终会收敛到一致状态。仅会解析活跃用户——非活跃用户无法接收路由工作项，因此会被报告而非静默配置技能。

部分安全性。若部分绑定成功而其他绑定失败，状态会设为

partial

，并在

blocking_issue

中包含每个座席的错误信息；成功的绑定关系会保留（每个关联对象都是独立的写入操作）。

Output contract

输出约定

A single JSON object:

status

∈

configured

reused

partial

blocked

skill

(

{developer_name, id, state}

agents

(array of

{username, user_id, skill_binding_id, skill_binding_state}

created_counts

reused_counts

manual_actions

blocking_issue

```
reused
```
— skill and all bindings already existed.
```
configured
```
— at least one component created and all requested bindings now exist.
```
partial
```
/
```
blocked
```
— see
```
blocking_issue
```
;
```
manual_actions
```
names the prerequisite skill when the cause is a missing precondition.

返回单个JSON对象：

status

∈

configured

reused

partial

blocked

，

skill

（

{developer_name, id, state}

），

agents

（

{username, user_id, skill_binding_id, skill_binding_state}

数组），

created_counts

，

reused_counts

，

manual_actions

，

blocking_issue

。

```
reused
```
——技能及所有绑定关系已存在。
```
configured
```
——至少创建了一个组件，且所有请求的绑定关系现已存在。
```
partial
```
/
```
blocked
```
——详见
```
blocking_issue
```
；若原因是缺少前置条件，
```
manual_actions
```
会指明所需的前置技能。

Limitations

局限性

One skill per invocation; run again per skill an agent set needs.
Does not author
```
WorkSkillRouting
```
rules or field-based skill criteria — that is a separate skill.
Does not create agent users, queues, or presence configuration.
```
SkillUser.SkillLevel
```
is left at the platform default; forking the DML body is required to set explicit proficiency.

每次调用仅能配置一个技能；若座席组需要多个技能，需重复执行。
不支持编写
```
WorkSkillRouting
```
规则或基于字段的技能条件——这属于单独的技能范畴。
不支持创建座席用户、队列或在线状态配置。
```
SkillUser.SkillLevel
```
会保留平台默认值；若需设置明确的熟练度，需修改DML主体内容。

References

参考资料

File	When to read
`references/api-notes.md`	Skill metadata vs Skill sObject, the SkillUser agent-binding model, and SBR base-setting prerequisites
`scripts/tests/test_sbr_contracts.py`	When validating changes — run `python3 scripts/tests/test_sbr_contracts.py` from this skill directory

文件	阅读场景
`references/api-notes.md`	了解Skill元数据与Skill sObject的区别、SkillUser座席绑定模型，以及SBR基础设置的前置条件
`scripts/tests/test_sbr_contracts.py`	验证变更时——从本技能目录运行 `python3 scripts/tests/test_sbr_contracts.py`