mcpField
S
service-omni-queue-routing-config-deploy

service-omni-queue-routing-config-deploy

github.com/forcedotcom其他1.1k90 次安装1 天前更新
代码仓库

关于 service-omni-queue-routing-config-deploy

这是一个 Salesforce 技能，通过 Data API 创建或更新 Omni-Channel 的 `QueueRoutingConfig`。它会保留未指定的设置，并在再次查询组织后验证结果，可安全重复运行。

主要功能

  1. 01创建或更新路由配置
  2. 02支持 MostAvailable 和 LeastActive
  3. 03设置容量、优先级和推送超时
  4. 04配置溢出接收用户
  5. 05重新查询并验证写入值
  6. 06更新时保留未指定设置

适用场景

  1. 01设置 Omni-Channel 队列的路由方式
  2. 02更新容量设置并保留其他值
  3. 03将溢出工作转给活跃用户
  4. 04检查 API 写入后的配置

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/forcedotcom/sf-skills --skill service-omni-queue-routing-config-deploy

安装后在 Claude Code 中输入/service-omni-queue-routing-config-deploy确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
api-notes.md
scripts/
upsert-and-report.sh
scripts/tests/
_bootstrap.py
test_queue_routing_config_contracts.py

详细介绍

service-omni-queue-routing-config-deploy

通过 Data API 创建或更新 QueueRoutingConfig。此记录用于告知 Omni-Channel 如何将工作分配给队列中的 Agent：路由模型（MostAvailable 用于类似轮询的分配，LeastActive 用于负载均衡）、每项工作占用的容量（CapacityWeight 或 CapacityPercentage）、推送超时时间以及路由优先级。它是 Omni 路由 Queue 的前置条件——service-omni-queue-deploy 会将队列绑定到此技能返回的配置 Id。技能通过 DeveloperName 检测记录，因此会 POST 新记录，或 PATCH 现有记录以使其保持一致，并且可以安全地重复运行。

输入

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):
[email protected] 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（必填）。
  • 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（Username 或 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 会针对每个目标设置此变量。

前置条件和安全性

  • 目标组织已通过 sf CLI（My Domain URL）完成身份验证，具有 Service Cloud 许可证，且 sf CLI 版本 ≥ 2.139.6。
  • 已启用 Omni-Channel 基本设置（service-omni-base-settings-configure）——否则无法写入 QueueRoutingConfig（INVALID_TYPE）。
  • 适用三重 safe_to_write 生产环境防护措施。

运行

upsert-and-report.sh 会执行检测 → upsert → 验证：

  1. 查询 QueueRoutingConfig WHERE DeveloperName = '<target-derived-or-explicit>'，并捕获现有 Id 和字段值。
  2. 将其与请求值或规范值进行比较。
  3. 如果记录不存在，则 POST 新记录；如果所有字段均已匹配，则不执行任何操作（reused）；如果有字段不匹配，则 PATCH。
  4. 重新查询以确认最终状态；如果重新查询结果显示不匹配，则阻止操作。

行为

基于目标命名。 未指定名称时，DeveloperName 会根据路由目标生成（Case_Routing_Config、Voice_Routing_Config 等），因此重复运行和协调器会指向同一条记录，而不是创建重复记录。

优先保留，避免不必要的变更。 对于现有记录，未提供的路由模型、标签、路由优先级、容量模式／值、溢出指派对象、推送超时和基于属性的标志都会保留。默认值（MostAvailable、基于目标生成的标签、权重 5、优先级 1、非基于属性）仅适用于全新记录。容量只能使用一种模式；显式地从权重切换为百分比或从百分比切回权重时，会清除旧的对应字段，避免记录中存在相互冲突的容量设置。

回退／溢出路由。 在 QueueBased 模型中，“回退”指队列的溢出指派对象——当没有队列成员可用时接收工作项的 User（而不是让工作项无限期地留在队列中）。Agent 是否可用由 Omni 异步决定，无法在路由流中观察，因此此设置应属于 QueueRoutingConfig，而不是流程。提供 overflow-assignee 时，该技能会将其解析为活跃的 User（若用户未知或未激活，则阻止操作，因为溢出到未激活用户会导致工作被悄然搁置），写入 OverflowAssigneeId，并验证该值能否往返读取。

回读报告。 所有报告的字段值都会在写入后从 org 重新查询（values_source: "requeried"），而不是照抄输入值——201／204 仅表示写入已被接受。该技能绝不会删除 QueueRoutingConfig（队列、Agent 和工作技能可能引用其 Id）——始终通过 PATCH 使记录符合目标设置。

输出约定

返回一个 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、生产 org、写入后不匹配，或 overflow-assignee 未能解析为唯一的活跃 User）。

before.existed 记录开始时是否存在匹配的记录（若存在，还会记录其先前的 capacity_weight／routing_model）；对于所有非 blocked 状态，都会填入 id；仅当状态为 blocked 时，blocking_issue 才不为 null。

限制

  • 基于属性的路由（IsAttributeBased=true）不在范围内——它还需要额外的属性架构。
  • v66 仅支持 MostAvailable 和 LeastActive。
  • v66 已弃用按渠道加权容量（参见 service-omni-service-channel-configure）；每个 Agent 的容量总量在其他位置配置。

参考资料

文件阅读时机
references/api-notes.md遇到意外错误或需要自定义字段时——了解 QueueRoutingConfig 架构、RoutingModel 语义，以及 CapacityWeight 与 Agent 容量的交互方式
scripts/tests/test_queue_routing_config_contracts.py验证变更时——从此技能目录运行 python3 scripts/tests/test_queue_routing_config_contracts.py

评论

支持 Markdown