service-omni-queue-routing-config-deploy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

service-omni-queue-routing-config-deploy

Create or update a

QueueRoutingConfig

via the Data API. This record tells Omni-Channel how to distribute work to agents on a queue: the routing model (

MostAvailable

for round-robin-style,

LeastActive

for load-balancing), how much capacity each work item consumes (

CapacityWeight

CapacityPercentage

), the push timeout, and the routing priority. It is a prerequisite for an Omni-routed

Queue

—

service-omni-queue-deploy

binds the queue to the config Id this skill returns. Detection is by

DeveloperName

, so the skill POSTs a new record or PATCHes an existing one to align, and is safe to re-run.

通过Data API创建或更新

QueueRoutingConfig

。该记录用于告知Omni-Channel如何将工作分配给队列中的Agent：路由模型（

MostAvailable

为轮询式，

LeastActive

为负载均衡式）、每个工作项消耗的容量（

CapacityWeight

或

CapacityPercentage

）、推送超时时间以及路由优先级。它是配置Omni路由

Queue

的前置条件——

service-omni-queue-deploy

会将队列与本工具返回的配置ID绑定。通过

DeveloperName

进行检测，因此本工具会POST新记录或PATCH现有记录以保持一致，且可安全重复运行。

Inputs

bash

bash scripts/upsert-and-report.sh <org-alias> [routing-model] [developer-name] [master-label] [capacity-weight] [routing-priority] [overflow-assignee] [push-timeout]

bash

bash scripts/upsert-and-report.sh <org-alias> [routing-model] [developer-name] [master-label] [capacity-weight] [routing-priority] [overflow-assignee] [push-timeout]

Case_Routing_Config, preserve model / create MostAvailable:

bash scripts/upsert-and-report.sh myorg

align the Case QRC to LeastActive:

bash scripts/upsert-and-report.sh myorg LeastActive

Voice_Routing_Config (coordinator path):

QRC_ROUTING_TARGET=VoiceCall bash scripts/upsert-and-report.sh myorg

set a fallback/overflow assignee (route overflow work to a supervisor):

QRC_OVERFLOW_ASSIGNEE=supervisor@example.com bash scripts/upsert-and-report.sh myorg

Voice uses 100% capacity and a 30-second push timeout:

QRC_ROUTING_TARGET=VoiceCall QRC_CAPACITY_PERCENTAGE=100 QRC_PUSH_TIMEOUT=30 bash scripts/upsert-and-report.sh myorg MostAvailable


- `org-alias` (required).
- `routing-model` (optional, or `ROUTING_MODEL_INPUT`) — `MostAvailable` | `LeastActive`. Omitted: an existing record's model is preserved; a new record is created `MostAvailable`. Provided: written on create, aligned on an existing record.
- `developer-name` / `master-label` / `capacity-weight` (1..100) / `routing-priority` (≥1) — positional after routing-model, or via `QRC_DEVELOPER_NAME` / `QRC_MASTER_LABEL` / `QRC_CAPACITY_WEIGHT` / `QRC_ROUTING_PRIORITY`. Label, weight `5`, and priority `1` are defaults only when creating a new record; omitted values preserve an existing record.
- `QRC_CAPACITY_PERCENTAGE` (optional, 0..100) — use percentage capacity instead of weight. It is mutually exclusive with an explicitly supplied capacity weight; switching modes clears the old sibling field.
- `overflow-assignee` (optional 7th positional, or `QRC_OVERFLOW_ASSIGNEE`) — the fallback User (Username or `005` Id) that receives work when every queue member is unavailable (`OverflowAssigneeId`). Resolved to an **active** User Id before the write; omitted leaves an existing record's overflow untouched and a new record with none.
- `push-timeout` (optional 8th positional, or `QRC_PUSH_TIMEOUT`, 0..3600 seconds) — how long Omni waits for an agent to accept pushed work. Omitted preserves an existing value.
- `QRC_ROUTING_TARGET` (env) — `Case | VoiceCall | Incident | MessagingSession`; selects the canonical naming defaults. `service-omni-channel-setup-coordinate` sets this per target.

QRC_ROUTING_TARGET=VoiceCall QRC_CAPACITY_PERCENTAGE=100 QRC_PUSH_TIMEOUT=30 bash scripts/upsert-and-report.sh myorg MostAvailable


- `org-alias`（必填）。
- `routing-model`（可选，或`ROUTING_MODEL_INPUT`）——`MostAvailable` | `LeastActive`。若省略：保留现有记录的模型；创建新记录时使用`MostAvailable`。若提供：创建时写入该值，现有记录则对齐该值。
- `developer-name` / `master-label` / `capacity-weight`（1..100） / `routing-priority`（≥1）——位于routing-model之后的位置参数，或通过`QRC_DEVELOPER_NAME` / `QRC_MASTER_LABEL` / `QRC_CAPACITY_WEIGHT` / `QRC_ROUTING_PRIORITY`传入。仅在创建新记录时使用默认值（标签为目标派生值、权重5、优先级1）；省略的参数会保留现有记录的值。
- `QRC_CAPACITY_PERCENTAGE`（可选，0..100）——使用百分比容量而非权重。与显式提供的容量权重互斥；切换模式时会清除旧模式对应的字段。
- `overflow-assignee`（可选第7位位置参数，或`QRC_OVERFLOW_ASSIGNEE`）——当所有队列成员不可用时接收工作的备用User（用户名或`005`格式ID）（对应`OverflowAssigneeId`）。写入前会解析为**活跃**User ID；省略时会保留现有记录的溢出配置，新记录则不设置该值。
- `push-timeout`（可选第8位位置参数，或`QRC_PUSH_TIMEOUT`，0..3600秒）——Omni等待Agent接受推送工作的时长。省略时保留现有值。
- `QRC_ROUTING_TARGET`（环境变量）——`Case | VoiceCall | Incident | MessagingSession`；选择标准命名默认值。`service-omni-channel-setup-coordinate`会根据目标对象设置该变量。

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
```
QueueRoutingConfig
```
is not writable (
```
INVALID_TYPE
```
).
The three-way
```
safe_to_write
```
production guard applies.

已通过
```
sf
```
CLI（My Domain URL）认证目标org，拥有Service Cloud许可证，且
```
sf
```
CLI版本≥2.139.6。
已启用Omni-Channel基础设置（
```
service-omni-base-settings-configure
```
）——否则
```
QueueRoutingConfig
```
不可写入（错误码
```
INVALID_TYPE
```
）。
启用三方
```
safe_to_write
```
生产环境防护机制。

Run

upsert-and-report.sh

performs detect → upsert → verify:

Query

QueueRoutingConfig WHERE DeveloperName = '<target-derived-or-explicit>'

, capturing the existing Id and field values.

Compare against the requested/canonical values.
POST a new record when none exists; no-op (
```
reused
```
) when all fields already match; PATCH when a field differs.
Re-query to confirm the final state; block if the re-query shows a mismatch.

upsert-and-report.sh

执行检测→upsert→验证流程：

查询

QueueRoutingConfig WHERE DeveloperName = '<目标派生或显式指定名称>'

，捕获现有记录的ID和字段值。

将查询结果与请求的/标准值进行对比。
若不存在记录则POST新记录；若所有字段已匹配则无操作（状态
```
reused
```
）；若字段存在差异则执行PATCH。
重新查询以确认最终状态；若重新查询结果存在不匹配则终止操作。

Behavior

Target-derived naming. With no explicit name, the DeveloperName follows the routing target (

Case_Routing_Config

Voice_Routing_Config

, etc.), so re-runs and the coordinator converge on the same record rather than creating parallel duplicates.

Preserve over churn. On an existing record, omitted routing model, label, routing priority, capacity mode/value, overflow assignee, push timeout, and attribute-based flag are preserved. Defaults (

MostAvailable

, target-derived label, weight

, priority

, non-attribute-based) apply only to a brand-new record. Capacity uses exactly one mode; explicitly changing from weight to percentage, or back, clears the old sibling field so the record cannot contain conflicting capacity settings.

Fallback / overflow routing. In the

QueueBased

model, "fallback" is the queue's overflow assignee — the User who receives work when no queue member is available (rather than the item sitting queued indefinitely). Agent availability is an async Omni decision, not observable in a routing flow, so this belongs on the

QueueRoutingConfig

, not the flow. When

overflow-assignee

is provided the skill resolves it to an active User (blocking on an unknown or inactive user, since overflow to an inactive user would silently strand work), writes

OverflowAssigneeId

, and verifies it round-trips.

Read-back reporting. All reported field values are re-queried from the org after the write (

values_source: "requeried"

), not echoed from inputs — a 201/204 only means the write was accepted. The skill never deletes a

QueueRoutingConfig

(queues, agents, and work skills may reference the Id) — it always PATCHes to align.

目标派生命名规则：若未指定显式名称，DeveloperName将遵循路由目标对象（如

Case_Routing_Config

、

Voice_Routing_Config

等），因此重复运行或通过协调工具操作时会指向同一记录，而非创建重复记录。 保留现有配置：对于现有记录，未指定的路由模型、标签、路由优先级、容量模式/值、溢出经办人、推送超时时间以及基于属性的标志将保持不变。默认值（

MostAvailable

、目标派生标签、权重5、优先级1、非基于属性）仅适用于全新记录。容量仅使用一种模式；若显式从权重切换为百分比（或反之），将清除旧模式对应的字段，确保记录不会包含冲突的容量设置。 Fallback/溢出路由：在

QueueBased

模型中，“fallback”指队列的溢出经办人——当队列中所有成员均不可用时，接收工作的User（而非让工作项无限期排队）。Agent可用性是Omni的异步决策，无法在路由流中观测，因此该配置属于

QueueRoutingConfig

，而非路由流。当提供

overflow-assignee

时，本工具会将其解析为活跃User（若用户不存在或非活跃则终止操作，因为向非活跃用户溢出会导致工作项无声滞留），写入

OverflowAssigneeId

并验证往返一致性。 回读报告：所有报告的字段值均为写入后从org重新查询的结果（

values_source: "requeried"

），而非回显输入值——201/204状态码仅表示写入已被接受。本工具绝不会删除

QueueRoutingConfig

（队列、Agent和工作技能可能引用其ID）——始终通过PATCH操作对齐配置。

Output contract

A single JSON object with

status

∈

created

reused

updated

blocked

, plus

routing_target

developer_name

id

master_label

routing_model

routing_priority

capacity_mode

capacity_weight

capacity_percentage

is_attribute_based

push_timeout

overflow_assignee_id

overflow_assignee_requested

values_source

, a

before

snapshot,

manual_actions

, and

blocking_issue

```
created
```
— no record existed; POST succeeded.
```
reused
```
— a record existed with all fields matching; no-op.
```
updated
```
— a record existed but a field differed; PATCH succeeded.
```
blocked
```
— precondition failed (Omni not enabled, production org, a post-write mismatch, or an
```
overflow-assignee
```
that did not resolve to exactly one active User).

before.existed

records whether a matching record was present at start (with its prior

capacity_weight

routing_model

when so);

id

is populated for every non-blocked status;

blocking_issue

is non-null only for

blocked

返回单个JSON对象，其中

status

取值为

created

reused

updated

blocked

，此外还包含

routing_target

、

developer_name

、

id

、

master_label

、

routing_model

、

routing_priority

、

capacity_mode

、

capacity_weight

、

capacity_percentage

、

is_attribute_based

、

push_timeout

、

overflow_assignee_id

、

overflow_assignee_requested

、

values_source

、

before

快照、

manual_actions

和

blocking_issue

字段。

```
created
```
：不存在记录；POST操作成功。
```
reused
```
：存在记录且所有字段匹配；无操作。
```
updated
```
：存在记录但部分字段存在差异；PATCH操作成功。
```
blocked
```
：前置条件不满足（未启用Omni、生产环境、写入后存在不匹配，或
```
overflow-assignee
```
未解析为唯一活跃User）。

before.existed

记录初始时是否存在匹配记录（若存在则包含其之前的

capacity_weight

routing_model

）；

id

会在所有非

blocked

状态下填充；仅当状态为

blocked

时

blocking_issue

非空。

Limitations

Attribute-based routing (
```
IsAttributeBased=true
```
) is out of scope — it requires an additional attribute schema.
Only
```
MostAvailable
```
and
```
LeastActive
```
are supported on v66.
Per-channel capacity weighting is deprecated on v66 (see
```
service-omni-service-channel-configure
```
); per-agent capacity totals are configured elsewhere.

基于属性的路由（
```
IsAttributeBased=true
```
）不在本工具范围内——这需要额外的属性schema。
在v66版本中仅支持
```
MostAvailable
```
和
```
LeastActive
```
路由模型。
在v66版本中，按渠道的容量权重已被弃用（详见
```
service-omni-service-channel-configure
```
）；按Agent的总容量需在其他位置配置。

References

File	When to read
`references/api-notes.md`	On unexpected errors or when customizing fields — QueueRoutingConfig schema, RoutingModel semantics, and how CapacityWeight interacts with agent capacity
`scripts/tests/test_queue_routing_config_contracts.py`	When validating changes — run `python3 scripts/tests/test_queue_routing_config_contracts.py` from this skill directory

文件	阅读场景
`references/api-notes.md`	遇到意外错误或自定义字段时——包含QueueRoutingConfig schema、RoutingModel语义以及CapacityWeight与Agent容量的交互方式
`scripts/tests/test_queue_routing_config_contracts.py`	验证变更时——从本工具目录运行 `python3 scripts/tests/test_queue_routing_config_contracts.py`