service-itsm-swarming-configure

为员工服务（ITSM）启用 Swarming

启用 Salesforce Go 功能 “Swarming”（service-cloud-swarming）——此功能可帮助服务代表及时邀请合适的协作者和主题专家，共同解决事件。每项操作都通过 headless-360 调度。

每次只执行一个步骤。 这些步骤会发起真实且会更改状态的 API 调用。每次只运行一项操作，展示其结果并确认成功，然后再继续——不要将多个设置调用合并到一个并行代码块中。

范围

• 范围内：通过功能启用 Connect API 启用 service-cloud-swarming Go 功能；之后验证功能状态；通过 org-values Connect API 将“Select a Collaboration Tool”选项列表（“Set Teams as Collaboration Tool for Swarming”检查清单项对应的 API 层目标）设为 Teams。
• 范围外：Microsoft Teams ITSM Salesforce Go 页面的基础开关（ITSMTeamsEnabled）和 Azure/Entra 应用注册——请使用 service-itsm-teams-configure（根据 Go 页面说明，Swarming 的前置条件是已设置好 Teams）。通知渠道偏好设置（Notifications / TeamsNotifications）——这与此功能无关。门户/站点创建——请使用 experience-portal-create。

---

此技能要解决的问题

“Set Teams as Collaboration Tool for Swarming”是 Teams ITSM Go 页面（service-cloud-itsm-teams-integration 的功能页面）中“Set Up Salesforce IT Desk”检查清单的一项，但它受一个单独的 Go 功能 service-cloud-swarming 限制，必须先启用该功能。此技能专门用于启用 Swarming，因此 service-itsm-teams-configure 可以委托给它，而无需重复实现功能启用逻辑。

---

工作流

步骤 1 — 检查当前功能状态

mcp__headless-360__dispatch(
  method: "POST",
  url:    "/services/data/v67.0/connect/setup/discovery/features/status",
  body:   { "featureApiNames": ["service-cloud-swarming"] }
)

响应格式：

{
  "items": [
    {
      "apiName": "service-cloud-swarming",
      "status": "ENABLED",          // or "NOT_ENABLED" / "DISABLED"
      "blockedByApexLock": false,
      "dependencyStatuses": [],
      "enableBlockedReasons": [],
      "disableBlockedReasons": []
    }
  ]
}

**注意：**此端点仅支持 POST，尽管它用于读取状态——使用 queryParams 进行 GET 请求会返回 405 METHOD_NOT_ALLOWED "Allowed are POST"。

如果 status 已是 "ENABLED"，请跳至步骤 3（验证）——不要重复启用。 如果 enableBlockedReasons 不为空，请在尝试步骤 2 前将这些原因告知用户。

步骤 2 — 启用功能

mcp__headless-360__dispatch(
  method: "POST",
  url:    "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-swarming/enable",
  body:   {}
)

已在线验证：会正常返回 201 {"success":true}（与 Teams 功能启用不同，此调用在测试中没有出现“返回 500 但仍然成功”的问题——但仍应在之后重新检查状态，因为 Go 功能启用调用通常可能不稳定）。

步骤 3 — 验证

mcp__headless-360__dispatch(
  method: "POST",
  url:    "/services/data/v67.0/connect/setup/discovery/features/status",
  body:   { "featureApiNames": ["service-cloud-swarming"] }
)

预期结果：status: "ENABLED"。

步骤 4 — 检查当前协作工具值

mcp__headless-360__dispatch_readonly(
  method: "GET",
  url:    "/services/data/v67.0/setup/org/values/SWARM_COLLABORATION_TOOL"
)

响应格式——四个值字段中恰好只有一个有值：

{ "booleanValue": false, "dateValue": null, "numberValue": null, "stringValue": "None" }

stringValue 保存当前选项列表选择值："None"、"Slack" 或 "Teams"。这是 setup-connect-api 中 get-org-value/update-org-value/verify-org-value-update 步骤所述的同一类 Java 枚举限制型 org-value 端点——valueName 必须是字面形式的 Java 枚举常量名称（SWARM_COLLABORATION_TOOL，SCREAMING_SNAKE_CASE），不能猜成 SwarmCollaborationTool 这样的 camelCase 名称。

如果当前值已是 "Teams"，请跳至步骤 6（报告）——不要再次发起写入。

步骤 5 — 将协作工具设为 Teams

mcp__headless-360__dispatch(
  method: "PATCH",
  url:    "/services/data/v67.0/setup/org/values/SWARM_COLLABORATION_TOOL",
  body:   { "orgValue": "Teams" }
)

已在线验证：会返回 200 { "stringValue": "Teams", ... }。这是 Swarming Go 功能页面“Select a Collaboration Tool”下拉菜单背后的 API 层写入操作——Teams ITSM Go 页面中的“Set Teams as Collaboration Tool for Swarming”检查清单项也会通过其“Go to Feature Page”按钮深度链接到同一设置。有效的 orgValue 字符串为 "None"、"Slack"、"Teams"。

之后重新执行步骤 4 的 GET 请求，确认 stringValue == "Teams"。

步骤 6 — 向用户报告

报告 service-cloud-swarming 功能状态和 SWARM_COLLABORATION_TOOL 的值，并确认“将 Teams 设为 Swarming 的协作工具”现已完全自动化——启用该功能是前置条件，而 org 值的 PATCH 才是真正写入清单项的操作。

---

禁用（如有需要）

mcp__headless-360__dispatch(
  method: "POST",
  url:    "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-swarming/disable",
  body:   {}
)

之后重新运行步骤 1 以确认。

如需同时重置协作工具选择（可选——禁用功能不会自动重置该选项）：

mcp__headless-360__dispatch(
  method: "PATCH",
  url:    "/services/data/v67.0/setup/org/values/SWARM_COLLABORATION_TOOL",
  body:   { "orgValue": "None" }
)

---

注意事项

问题	详情
“将 Teams 设为 Swarming 的协作工具”通过 SWARM_COLLABORATION_TOOL 写入，而不是调用 Teams 端点	此清单项位于 Swarming Go 功能页面本身（/lightning/setup/page/feature/service-cloud-swarming/home，“选择协作工具”下拉菜单）——Teams ITSM Go 页面的清单项只是通过“转到功能页面”链接到该页面。写入 API 是 PATCH /services/data/v67.0/setup/org/values/SWARM_COLLABORATION_TOOL，请求正文为 {"orgValue": "Teams"}——这是 setup-connect-api 的 get-org-value/update-org-value 步骤的一部分。已通过实时验证：GET 在 PATCH 前返回 {"stringValue":"None"}，PATCH 后返回 {"stringValue":"Teams"}。
valueName 必须是准确的 Java 枚举常量，不能使用驼峰命名	/setup/org/values/{valueName} 端点会直接调用 OrgValues.valueOf(valueName)（Enum.valueOf），因此需要使用 ui.services.utils.OrgValueUtil.OrgValues 中声明的字面值 SCREAMING_SNAKE_CASE 常量名，例如 SWARM_COLLABORATION_TOOL。SwarmCollaborationTool 或 SwarmingCollaborationTool 等驼峰命名猜测会返回 400 ILLEGAL_QUERY_PARAMETER_VALUE "No enum constant ui.services.utils.OrgValueUtil.OrgValues.<guess>"——此特定错误说明端点和机制正确，但大小写或名称有误。只读的 get-service-itsm-teams-collaboration-app-settings 端点（GET /connect/it-service/collaboration-app-settings/{targetApplication}）与此设置无关——它是只读的（POST/PATCH/PUT 会返回 405），并且无论功能状态如何，都会返回空的 settings: []。
features/status 仅支持 POST	对 /connect/setup/discovery/features/status 使用 queryParams 发送 GET 请求会返回 405 METHOD_NOT_ALLOWED "Allowed are POST"——务必使用包含 featureApiNames 的 JSON 请求正文发送 POST 请求。
swarming-connect-api SOR 无关	headless-360 的 swarming-connect-api SOR 涉及 Swarming 对话中的 Slack 消息（发布/修改/删除 Slack 消息、添加表情回应、上传文件、搜索频道/用户）——它不会配置 Swarming 使用哪种协作工具（Teams、Slack 还是 Chatter）。不要将其与此技能的范围混淆。
Swarming 需要先配置 Teams	Go 页面将“将 Teams 设为 Swarming 的协作工具”列为 Teams ITSM 设置中的一个步骤——请先启用或同时启用 service-cloud-itsm-teams-integration（通过 service-itsm-teams-configure）。
必须指定版本前缀	headless-360 的 dispatch/dispatch_readonly 不会解析 API 版本——务必传入完整的 /services/data/vXX.0/... 前缀。

---

相关技能

技能	何时替代使用／配合使用
service-itsm-teams-configure	启用 Microsoft Teams ITSM 基础集成并进行 Azure/Entra 设置——这是 Swarming 的前置条件；该技能会将“将 Teams 设为 Swarming 的协作工具”清单项委托给此技能处理
通知渠道偏好设置	启用 Notifications/TeamsNotifications 偏好设置，与此功能是不同事项（目前尚无专门的子技能）
service-itsm-channels-coordinate	涵盖 Teams、Slack、Swarming、通知和门户的顶层菜单