service-omni-queue-deploy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

service-omni-queue-deploy

Verify that a

Group

(Type='Queue') exists with a

QueueSobject

binding to the requested routable sObject, reusing whatever is already there. With

--create-if-missing

, create the queue via the Metadata API (Group + QueueSobject) when none is bound, and optionally align its

QueueRoutingConfigId

to a caller-specified QRC. The skill discovers the queue by its

QueueSobject.SobjectType

binding, not by name, because real orgs name queues inconsistently (

CaseQueue

messagingqueue

Omni_Demo_Cases_Queue

) — the functional link between a queue and the routing it supports is the binding, not the

DeveloperName

. It is invoked by

service-omni-channel-setup-coordinate

; queue membership is a separate leaf (

service-omni-queue-members-assign

) and the QRC it aligns to comes from

service-omni-queue-routing-config-deploy

验证是否存在与请求的可路由sObject绑定了QueueSobject的

Group

（类型为'Queue'），复用已存在的队列。若使用

--create-if-missing

参数，当没有绑定队列时，将通过Metadata API（Group + QueueSobject）创建队列，并可选择将其

QueueRoutingConfigId

与调用方指定的QRC对齐。该工具通过

QueueSobject.SobjectType

绑定来发现队列，而非通过名称，因为实际组织中的队列命名不一致（如

CaseQueue

、

messagingqueue

、

Omni_Demo_Cases_Queue

）——队列与其支持的路由之间的功能关联是绑定关系，而非

DeveloperName

。它由

service-omni-channel-setup-coordinate

调用；队列成员管理是独立的子功能（

service-omni-queue-members-assign

），其对齐的QRC来自

service-omni-queue-routing-config-deploy

。

Inputs

输入参数

bash

bash scripts/verify-and-align.sh <org-alias> [Case|Incident|MessagingSession|VoiceCall] [routing_config_dn] [queue_developer_name] [--create-if-missing]

bash

bash scripts/verify-and-align.sh <org-alias> [Case|Incident|MessagingSession|VoiceCall] [routing_config_dn] [queue_developer_name] [--create-if-missing]

create + bind a Voice queue on a fresh org:

在全新组织中创建并绑定Voice队列：

bash scripts/verify-and-align.sh myorg VoiceCall Voice_Routing_Config "" --create-if-missing


- `org-alias` (required).
- `sobject_type` (optional, default `Case`).
- `routing_config_dn` (optional) — when passed, forces alignment to that QRC; when omitted for Case it defaults to `Case_Routing_Config`; when omitted for other sObjects the skill reports the existing binding without forcing.
- `queue_developer_name` (optional 4th positional) — the explicit queue to operate on, or the name to create with `--create-if-missing`.
- `--create-if-missing` (flag, or `QUEUE_CREATE_IF_MISSING=1`) — create the queue via the Metadata API when none is bound; label defaults to a spaced form of the DeveloperName (override via `QUEUE_LABEL`).

bash scripts/verify-and-align.sh myorg VoiceCall Voice_Routing_Config "" --create-if-missing


- `org-alias`（必填）。
- `sobject_type`（可选，默认值为`Case`）。
- `routing_config_dn`（可选）——传入时，强制对齐至该QRC；针对Case省略时，默认值为`Case_Routing_Config`；针对其他sObject省略时，工具仅报告现有绑定关系，不强制执行对齐。
- `queue_developer_name`（可选，第4个位置参数）——要操作的指定队列名称，或使用`--create-if-missing`时创建队列的名称。
- `--create-if-missing`（标志位，或设置`QUEUE_CREATE_IF_MISSING=1`）——当没有绑定队列时，通过Metadata API创建队列；标签默认使用DeveloperName的空格分隔形式（可通过`QUEUE_LABEL`覆盖）。

Preconditions and safety

前置条件与安全机制

Target org authenticated via
```
sf
```
CLI (My Domain URL), Service Cloud license,
```
sf
```
CLI ≥ 2.139.6.
The target sObject is enabled on the org — verified via
```
EntityDefinition
```
before any write; missing sObjects block with a feature-enablement click-path (Incident Management for Incident, Enhanced Messaging for MessagingSession).
When
```
routing_config_dn
```
is supplied, that QRC must already exist (resolved by DeveloperName); otherwise the run blocks with a pointer to
```
service-omni-queue-routing-config-deploy
```
.
The three-way
```
safe_to_write
```
production guard applies.

目标组织已通过
```
sf
```
CLI（My Domain URL）认证，拥有Service Cloud许可证，且
```
sf
```
CLI版本≥2.139.6。
目标sObject已在组织中启用——在执行任何写入操作前，通过
```
EntityDefinition
```
验证；若sObject缺失，将阻止操作并提供功能启用的点击路径（如Incident对应Incident Management，MessagingSession对应Enhanced Messaging）。
当提供
```
routing_config_dn
```
时，该QRC必须已存在（通过DeveloperName解析）；否则将阻止运行，并指向
```
service-omni-queue-routing-config-deploy
```
工具。
启用三方
```
safe_to_write
```
生产环境保护机制。

Run

运行流程

verify-and-align.sh

runs the full sequence and emits the report:

Prereq — confirm the sObject via
```
EntityDefinition
```
.
Discover —
```
QueueSobject WHERE SobjectType = '<sobject_type>'
```
. A hit is reused. No hit: create via the Metadata API when
```
--create-if-missing
```
, else block with a Setup click-path.
Inspect — read the queue's
```
QueueRoutingConfigId
```
and its full
```
QueueSobject
```
list.
Align (optional) — when
```
routing_config_dn
```
is supplied, resolve its Id and PATCH
```
Group.QueueRoutingConfigId
```
if drifted.
Re-query — confirm convergence and emit JSON.

verify-and-align.sh

执行完整流程并生成报告：

前置检查——通过
```
EntityDefinition
```
确认sObject是否存在。
发现队列——查询
```
QueueSobject WHERE SobjectType = '<sobject_type>'
```
。若找到则复用；未找到时，若设置了
```
--create-if-missing
```
则通过Metadata API创建，否则阻止操作并提供Setup点击路径。
检查队列——读取队列的
```
QueueRoutingConfigId
```
及其完整的
```
QueueSobject
```
列表。
对齐配置（可选）——当提供
```
routing_config_dn
```
时，解析其Id，若配置已偏离则执行
```
Group.QueueRoutingConfigId
```
的PATCH操作。
重新查询——确认状态收敛并输出JSON结果。

Behavior

行为特性

Discovery over naming. Any queue whose

QueueSobject

routes the target sObject is the queue for that sObject, regardless of its name. A name-based check would miss a queue like

messagingqueue

and either block or create a duplicate.

Creation is idempotent. Metadata deploy upserts by fullName, so

--create-if-missing

adopts/updates an existing same-named queue rather than making a second one. Creation ships the minimal safe set (

doesSendEmailToMembers=false

plus the sObject binding) and never deletes existing

QueueSobject

rows — other sObjects may be intentionally routed through the same queue.

Forced vs discovered QRC. For Case, the coordinator wants deterministic alignment to

Case_Routing_Config

, so the skill forces it. For other sObjects with no coordinator-owned QRC, the skill reports whatever the queue is already bound to (

source: discovered

) rather than forcing a name that may not exist. QRC Ids are resolved by

DeveloperName

at runtime — never hardcoded.

Ambiguity. If multiple distinct queues bind the same sObject, the skill does not guess — it blocks and asks the operator to disambiguate, unless a canonical name matches or an explicit

queue_developer_name

pins the exact queue.

PATCH hygiene.

sf api request rest

prints a beta warning on stderr; the skill captures stderr separately so it cannot corrupt JSON parsing, and it preserves the queue Id on PATCH (never delete + recreate) because downstream references point to it.

基于发现而非命名。任何通过

QueueSobject

路由目标sObject的队列，即为该sObject对应的队列，无论其名称如何。基于名称的检查会遗漏类似

messagingqueue

的队列，导致操作受阻或创建重复队列。

创建操作具有幂等性。Metadata部署通过fullName进行upsert，因此

--create-if-missing

会采用/更新同名的现有队列，而非创建第二个队列。创建时仅包含最小安全配置集（

doesSendEmailToMembers=false

加上sObject绑定），且绝不会删除现有的

QueueSobject

行——其他sObject可能有意通过同一队列路由。

强制QRC与发现QRC。针对Case，协调器要求确定性对齐至

Case_Routing_Config

，因此工具会强制执行对齐。针对其他没有协调器托管QRC的sObject，工具仅报告队列已绑定的配置（

source: discovered

），而非强制使用可能不存在的名称。QRC Id在运行时通过

DeveloperName

解析——绝不硬编码。

歧义处理。若多个不同队列绑定了同一sObject，工具不会猜测——会阻止操作并要求操作人员消除歧义，除非存在匹配的规范名称或指定了

queue_developer_name

来锁定确切队列。

PATCH操作规范。

sf api request rest

会在stderr输出beta版本警告；工具会单独捕获stderr，避免破坏JSON解析，且在PATCH操作时保留队列Id（绝不删除后重建），因为下游引用依赖该Id。

Output contract

输出约定

A single JSON object with

status

∈

created

reused

updated

blocked

, plus

sobject_type

developer_name

queue_created

id

queue_routing_config_id

queue_routing_config_developer_name

queue_routing_config_source

(

forced

discovered

queue_sobjects

, a

before

snapshot,

manual_actions

, and

blocking_issue

```
created
```
— no queue was bound and
```
--create-if-missing
```
created one (binding its QRC when supplied).
```
reused
```
— a bound queue existed and, if a QRC was passed, already matched (no PATCH).
```
updated
```
— a bound queue existed but the caller-supplied QRC was drifted; PATCH ran.
```
blocked
```
— sObject absent, no bound queue and no
```
--create-if-missing
```
, supplied QRC missing, or the re-query showed state did not converge.

queue_created

true

only when this run deployed a new queue;

blocking_issue

names the specific precondition that failed and

manual_actions

carries the click-path.

返回单个JSON对象，其中

status

取值为

created

reused

updated

blocked

，还包含

sobject_type

、

developer_name

、

queue_created

、

id

、

queue_routing_config_id

、

queue_routing_config_developer_name

、

queue_routing_config_source

（

forced

discovered

）、

queue_sobjects

、

before

快照、

manual_actions

和

blocking_issue

。

```
created
```
——无绑定队列，且
```
--create-if-missing
```
创建了新队列（若提供了QRC则绑定）。
```
reused
```
——存在绑定队列，且若传入了QRC则已匹配（未执行PATCH）。
```
updated
```
——存在绑定队列，但调用方提供的QRC已偏离；已执行PATCH操作。
```
blocked
```
——sObject缺失、无绑定队列且未设置
```
--create-if-missing
```
、提供的QRC缺失，或重新查询显示状态未收敛。

仅当本次运行部署了新队列时，

queue_created

为

true

；

blocking_issue

会指明失败的具体前置条件，

manual_actions

包含对应的操作点击路径。

Limitations

局限性

Only
```
Case
```
,
```
Incident
```
,
```
MessagingSession
```
,
```
VoiceCall
```
— extend by adding a dispatcher branch.
Never deletes a queue or its
```
QueueSobject
```
rows, and never modifies queue members.
Creation ships a minimal queue shape; exotic fields (
```
doesIncludeBosses
```
, email routing address) are not set.

仅支持
```
Case
```
、
```
Incident
```
、
```
MessagingSession
```
、
```
VoiceCall
```
——可通过添加调度分支扩展支持范围。
绝不会删除队列或其
```
QueueSobject
```
行，也绝不会修改队列成员。
创建时仅生成最小队列结构；不会设置特殊字段（如
```
doesIncludeBosses
```
、邮件路由地址）。

References

参考文档

File	When to read
`references/api-notes.md`	On a block for a missing queue (manual click-path) or unexpected Data API errors — Queue/QueueSobject schema, the Metadata API creation shape, and the stderr-separation and queue-naming-variance notes

文件	阅读场景
`references/api-notes.md`	当因队列缺失（手动操作路径）或意外Data API错误导致操作受阻时阅读——包含Queue/QueueSobject架构、Metadata API创建结构，以及stderr分离和队列命名差异的说明