mcpField
S
service-omni-queue-members-assign

service-omni-queue-members-assign

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

关于 service-omni-queue-members-assign

此 Salesforce skill 通过 Data API 将 Agent 用户加入现有队列。它会识别缺失成员并在写入后复查，可安全重跑且不会移除现有成员。

主要功能

  1. 01添加生成或明确指定的用户
  2. 02检测现有队列成员
  3. 03仅创建缺失的成员关系
  4. 04写入后重新检查成员
  5. 05阻止不安全的生产环境变更

适用场景

  1. 01为 Omni-Channel 队列配置 Agent 用户
  2. 02将指定的活跃用户加入队列
  3. 03重跑成员配置而不重复添加

安装

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

$npx skills add https://github.com/forcedotcom/sf-skills --skill service-omni-queue-members-assign

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

包含的文件

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

references/
api-notes.md
scripts/
verify-and-bind.sh
scripts/tests/
_bootstrap.py
test_queue_members_contracts.py

详细介绍

service-omni-queue-members-assign

通过 GroupMember Data API POST 将 N 个 Agent 用户加入 Salesforce 队列。如果用户不是队列成员，Omni-Channel 路由会认为该队列没有可用用户，因此永远不会分配工作。检测基于 SOQL（采用与 service-omni-queue-routing-config-deploy 相同的先检测后 POST 模式），因此只会创建缺失的成员关系，安全技能可重复运行。Agent 用户来自 service-omni-agent-users-create，队列来自 service-omni-queue-deploy，用户的 Omni 权限来自 service-omni-permission-set-assign。

输入

bash scripts/verify-and-bind.sh <org-alias> [queue-developer-name=CaseQueue] [count=3] [explicit-members-csv]
# demo agents (default):
bash scripts/verify-and-bind.sh myorg CaseQueue 3
# real agents by username/id:
bash scripts/verify-and-bind.sh myorg VoiceQueue "" "[email protected],005XX000001abcd"
  • org-alias（必需）。
  • queue-developer-name（可选，默认值为 CaseQueue）。
  • count（可选，默认值为 3，范围为 1..10）——必须与 Agent 用户数量一致；显式模式下忽略。
  • explicit-members-csv（可选的第 4 个位置参数，或 MEMBER_USERNAMES_CSV / MEMBER_USER_IDS_CSV）——每个条目可以是用户名或 15/18 字符的用户 ID；数量根据列表计算。

前提条件和安全性

  • 目标组织已通过 sf CLI（My Domain URL）进行身份验证，具有 Service Cloud 许可证，且 sf CLI 版本 ≥ 2.139.6。
  • 执行用户具有 PermissionsModifyAllData（System Administrator 默认具有此权限）。
  • Agent 用户（service-omni-agent-users-create）和队列（service-omni-queue-deploy）均已存在；缺少用户集或队列时会阻止执行，并提示使用相应技能（无法通过 Data API 创建队列）。
  • 适用三重 safe_to_write 生产环境防护——向生产队列添加用户会将真实客户工作路由错误，因此会直接阻止，且无法覆盖。

运行

verify-and-bind.sh 会运行整个流程：

  1. 计算 safe_to_write；推导 8 字符的组织后缀。
  2. 按 DeveloperName 和 Type='Queue' 解析队列 Group.Id；若不存在则阻止执行。
  3. 解析成员集——生成模式会查询 User，查找符合 agent{1..N}.<suffix>@example.com 格式的用户（若任何预期用户不存在则阻止执行）；显式模式会解析每个提供的条目，并要求所有用户均为 ACTIVE 状态。
  4. 查询该队列现有的 GroupMember；计算尚未加入的用户。
  5. 为每个缺失用户分别 POST 一个 GroupMember（单独 POST，不使用 allOrNone）。
  6. 重新查询以确认最终成员关系，并输出报告。

行为

两种成员来源，绝不混用。 默认的生成模式可确保从创建用户到分配成员的交接过程可预测；显式模式需选择启用，适用于真实 Agent，并会自动推导数量。在显式模式下，若某个条目无法解析为活跃用户，则会阻止执行——绑定拼写错误或非活跃用户会导致队列成员数量不足，且不会发出提示。

幂等性和如实反馈。 POST 会逐个执行，因此即使一个绑定失败（例如，与另一位管理员的操作发生竞争），也不会回滚其他成功的绑定；技能会在所有 POST 完成后重新查询——201 仅表示写入请求已被接受，之后还需通过 SOQL 确认路由引擎可以看到该记录。before 快照包含已有成员，包括通过其他方式添加的非演示用户，以便协调人员查看完整成员状态。

非破坏性。 仅创建；不会移除或重新分配现有成员。

输出约定

单个 JSON 对象，包含 status（值为 bound | reused | partial | blocked）、已解析的 queue、org_suffix、member_source（generated_pattern | explicit）、requested_count、before 快照、bound_this_run/bound_count、reused_count、after 快照、manual_actions 和 blocking_issue。

  • bound — 至少创建了一个新成员；最终状态符合预期数量。
  • reused — 所有预期用户都已是成员；未执行 POST。
  • partial — 部分 POST 失败；重新查询显示的成员数量少于请求数量（详情见 blocking_issue）。
  • blocked — 前提条件未满足（生产组织、缺少队列、缺少用户或缺少权限）。

除 partial 外，bound_count + reused_count == requested_count；仅当状态为 blocked/partial 时，blocking_issue 才不为 null。

限制

  • 每次运行中，生成模式和显式模式互斥。
  • 仅支持创建；不支持移除或重新分配成员。
  • 不会创建队列或用户，也不会分配权限集或在线状态配置。

参考资料

文件阅读时机
references/api-notes.md在检测/绑定循环之前 — GroupMember 架构、队列与公开组的区别、UserOrGroupId 为何是多态字段，以及常见的 POST 失败
scripts/tests/test_queue_members_contracts.py验证更改时 — 在此技能目录中运行 python3 scripts/tests/test_queue_members_contracts.py

评论

支持 Markdown