service-omni-work-skill-routing-configure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

service-omni-work-skill-routing-configure

Author an Omni WorkSkillRouting rule so work is routed to agents by a field value on the work record, not just by skills the agent happens to hold. Where

service-omni-skills-based-routing-configure

makes an agent routable (Skill + ServiceResource + ServiceResourceSkill), this skill decides which skill a work item requires based on one of its fields — for example "when

Case.Origin

Phone

, require the

Voice

skill". The rule is one

WorkSkillRouting

record (a header plus one

workSkillRoutingAttributes

mapping) deployed via the Metadata API. It runs after the referenced Skill exists and belongs to the same routing family coordinated by

service-omni-channel-setup-coordinate

编写Omni WorkSkillRouting规则，使工作项根据工作记录上的字段值路由至Agent，而非仅依据Agent已拥有的技能。

service-omni-skills-based-routing-configure

用于让Agent具备可路由性（Skill + ServiceResource + ServiceResourceSkill），而本技能则根据工作项的某个字段确定其所需的技能——例如“当

Case.Origin

Phone

时，要求具备

Voice

技能”。该规则为一条

WorkSkillRouting

记录（包含一个头部信息和一个

workSkillRoutingAttributes

映射），通过Metadata API部署。运行本技能前，需确保引用的Skill已存在，且与

service-omni-channel-setup-coordinate

协调的同一路由家族关联。

Inputs

输入参数

bash

bash scripts/configure-and-report.sh <org-alias> <related_entity> <field> <skill> <value> [rule_master_label]

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

related_entity

(required). The sObject the rule applies to (e.g.

Case

MessagingSession

LiveChatTranscript

Lead

VoiceCall

```
field
```
(required). The field the attribute evaluates (e.g.
```
Case.Origin
```
or
```
Origin
```
). Bare standard fields are qualified with the related entity before deploy, so
```
Origin
```
becomes
```
Case.Origin
```
instead of being misread as a custom-field metadata name.
```
skill
```
(required). The Omni
```
Skill
```
DeveloperName required when the field matches (e.g.
```
Voice
```
).
```
value
```
(required). The field value that maps to the skill (e.g.
```
Phone
```
). Plain values only; XML-reserved characters are not supported.
```
rule_master_label
```
(optional). MasterLabel for the rule; defaults to
```
<related_entity> Skill Routing
```
.

Env overrides:

RULE_DEVELOPER_NAME

(fullName of the rule, default the related-entity name — one rule per entity),

IS_ACTIVE

(default

true

SKILL_LEVEL

(0–10),

SKILL_PRIORITY

(0–10, additional-skill drop order),

IS_ADDITIONAL_SKILL

(

true

false

bash

bash scripts/configure-and-report.sh <org-alias> <related_entity> <field> <skill> <value> [rule_master_label]

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

related_entity

（必填）。规则适用的sObject（例如

Case

、

MessagingSession

、

LiveChatTranscript

、

Lead

、

VoiceCall

）。

```
field
```
（必填）。属性评估的字段（例如
```
Case.Origin
```
或
```
Origin
```
）。部署前，纯标准字段会自动关联实体，因此
```
Origin
```
会转换为
```
Case.Origin
```
，避免被误读为自定义字段元数据名称。
```
skill
```
（必填）。字段匹配时所需的Omni
```
Skill
```
DeveloperName（例如
```
Voice
```
）。
```
value
```
（必填）。映射至技能的字段值（例如
```
Phone
```
）。仅支持纯文本值；不支持XML保留字符。
```
rule_master_label
```
（可选）。规则的MasterLabel；默认值为
```
<related_entity> Skill Routing
```
。

环境变量覆盖：

RULE_DEVELOPER_NAME

（规则的fullName，默认值为关联实体名称——每个实体对应一条规则）、

IS_ACTIVE

（默认值

true

）、

SKILL_LEVEL

（0–10）、

SKILL_PRIORITY

（0–10，附加技能的排序优先级）、

IS_ADDITIONAL_SKILL

（

true

false

）。

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 referenced

Skill

already exists (

service-omni-skills-based-routing-configure

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
```
配置）。

引用的

Skill

已存在（通过

service-omni-skills-based-routing-configure

创建）。

启用三方
```
safe_to_write
```
生产环境保护机制。

Run

运行流程

safe_to_write — query
```
Organization
```
; refuse to write to a real production org.
Skill prereq — query
```
Skill
```
by DeveloperName; if absent, block and point at
```
service-omni-skills-based-routing-configure
```
.
Merge — read the existing
```
WorkSkillRouting.Metadata
```
through the Tooling API, preserve unrelated attributes, and replace or append only the requested
```
(field, value)
```
mapping. An inconclusive read blocks the write;
```
WSR_REPLACE=1
```
is the explicit destructive-replacement escape hatch.
Deploy — materialize the merged
```
WorkSkillRouting
```
record (elements in XSD/alphabetical order) and deploy it via the Metadata API (async + poll to a terminal state).

Classify — read

files[].state

(

Created

Changed

Unchanged

) to report

created

updated

reused

安全写入校验 —— 查询
```
Organization
```
；拒绝写入真实生产环境。
Skill前置校验 —— 通过DeveloperName查询
```
Skill
```
；若不存在，则阻止操作并引导使用
```
service-omni-skills-based-routing-configure
```
。
合并处理 —— 通过Tooling API读取现有
```
WorkSkillRouting.Metadata
```
，保留无关属性，仅替换或追加请求的
```
(field, value)
```
映射。若读取结果不明确，则阻止写入；
```
WSR_REPLACE=1
```
为显式破坏性替换的应急开关。
部署操作 —— 生成合并后的
```
WorkSkillRouting
```
记录（元素按XSD/字母顺序排列），并通过Metadata API部署（异步执行+轮询至终端状态）。

状态分类 —— 读取

files[].state

（

Created

Changed

Unchanged

）以报告

created

updated

reused

状态。

Behavior

行为特性

Idempotent + merge-safe. WorkSkillRouting permits a single rule per related entity, so the rule's fullName defaults to the entity name. Re-running the same mapping reports

reused

; a new mapping is merged into the existing attribute list; changing the same field/value mapping updates only that entry. The skill never silently replaces an existing rule when its current metadata could not be read.

Graceful degradation. WorkSkillRouting is not provisioned on every org (some trials/CDOs). A deploy failure shaped like

INVALID_TYPE

/ "not available" / "WorkSkillRouting" is reported as

blocked

with a clear limitation message and a pointer to base settings — the skill surfaces the limitation rather than crashing.

幂等性 + 合并安全性。WorkSkillRouting要求每个关联实体对应一条规则，因此规则的fullName默认使用实体名称。重复运行相同映射会报告

reused

；新映射会合并至现有属性列表；修改同一字段/值映射仅更新对应条目。当无法读取当前元数据时，本技能绝不会静默替换现有规则。

优雅降级。并非所有组织都配置了WorkSkillRouting（部分试用版/CDO组织）。若部署失败提示

INVALID_TYPE

/ “不可用” / “WorkSkillRouting”，则会报告为

blocked

状态，并显示清晰的限制信息及基础设置引导链接——本技能会暴露限制而非直接崩溃。

Output contract

输出约定

A single JSON object:

status

∈

created

updated

reused

blocked

(plus

action_needed

in plan mode),

rule

(

{developer_name, master_label, related_entity, is_active, state}

attribute

(

{field, skill, value, skill_level, skill_priority, is_additional_skill}

merge

(

{merged_from_existing, attribute_count, preserved_count}

deploy_id

manual_actions

blocking_issue

返回单个JSON对象：

status

∈

created

updated

reused

blocked

（计划模式下附加

action_needed

）、

rule

（

{developer_name, master_label, related_entity, is_active, state}

）、

attribute

（

{field, skill, value, skill_level, skill_priority, is_additional_skill}

）、

merge

（

{merged_from_existing, attribute_count, preserved_count}

）、

deploy_id

、

manual_actions

、

blocking_issue

。

Limitations

限制说明

One field→skill mapping per invocation and one rule per related entity. Multiple invocations safely accumulate attributes on that rule.
Does not create the Skill, ServiceResources, agent users, queues, or presence configuration.
Field/value correctness is validated by the platform at deploy time; an invalid field or value surfaces as a
```
blocked
```
deploy failure.

每次调用仅支持一个字段→技能映射，且每个关联实体对应一条规则。多次调用可安全地在该规则上累积属性。
不支持创建Skill、ServiceResources、Agent用户、队列或在线状态配置。
字段/值的正确性由平台在部署时验证；无效的字段或值会导致部署失败并报告为
```
blocked
```
状态。

References

参考资料

File	When to read
`references/api-notes.md`	WorkSkillRouting metadata shape, XSD element order, one-rule-per-entity constraint, attribute fields, and graceful-degradation triggers
`scripts/tests/test_work_skill_routing_contracts.py`	When validating changes — run `python3 scripts/tests/test_work_skill_routing_contracts.py` from this skill directory

文件	阅读场景
`references/api-notes.md`	了解WorkSkillRouting元数据结构、XSD元素顺序、单实体单规则约束、属性字段及优雅降级触发条件
`scripts/tests/test_work_skill_routing_contracts.py`	验证变更时——从本技能目录运行 `python3 scripts/tests/test_work_skill_routing_contracts.py`