service-itsm-teams-configure

为员工服务（ITSM）启用 Microsoft Teams

启用 Salesforce Go 功能 “Microsoft Teams for Employee Service” （service-cloud-itsm-teams-integration）——此功能可让 IT Desk 和 IT Service Agent 在 Microsoft Teams 中跟踪工单、请求目录项目，并获得 Agentforce 协助。所有操作都通过 headless-360 执行。

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

范围

• 范围内：通过功能启用 Connect API 启用 service-cloud-itsm-teams-integration Go 功能；之后验证功能和 ITSMTeamsEnabled 偏好设置状态；说明直接 PATCH 组织偏好设置的方式为何失败，以及此方法为何可行；按需禁用该功能；由于没有 Salesforce API 可以完成 Azure/Entra 应用注册（步骤 4a），因此向用户提供逐步说明；用户在聊天中提供 Client ID/Tenant ID，且通过步骤 4a 中的复制粘贴命令将 Client Secret 写入 Git 忽略的机密文件（切勿在聊天中发送）后，通过 API 将其直接写入 MSTeamsSetupClientCredentialsEC 命名凭据——此 Salesforce 端写入始终由此技能自动完成，绝不交由用户处理；凭据创建后，通过 /connect/service-itsm-teams/graph-api/extensions 将 Experience Cloud 站点注册为 Teams“首选站点”扩展。
• 范围外：通知渠道偏好设置（Notifications、TeamsNotifications）——这与此功能无关。启用 service-cloud-swarming Go 功能本身——交由 service-itsm-swarming-configure 处理。IT Desk/履行人员清单组（Turn on IT Desk、Install IT Desk app、Manage User Access、Set Teams as Collaboration Tool for Swarming）——交由 service-itsm-teams-itdesk-configure 处理。IT Service/员工清单组（Turn on IT Service、Install IT Service app、Manage User Access、Select a Digital Experience Site）——交由 service-itsm-teams-itservice-configure 处理。创建门户/站点——使用 experience-portal-create。Azure 端的实际操作（浏览 Azure 门户、生成客户端密钥、授予 Microsoft 管理员同意）必须由用户在 Microsoft 管理中心完成——没有 Salesforce API 可以访问 Azure/Entra——但此技能仍会提供这些步骤的准确说明（见“注意事项”和步骤 4a），而不是将其视为他人的问题。

---

此技能解决的问题

ITSMTeamsEnabled 是 Salesforce Go 页面上用于控制 Microsoft Teams ITSM 集成的开关偏好设置。其 UDD 定义（ServiceItsmTeams.settings.xml）声明了 orgAccess="always"，但没有 editAccess 属性——而可正常使用的偏好设置（例如 Notifications/TeamsNotifications）会明确设置 editAccess="always"。因此，直接使用 Setup 偏好设置 Connect API 路由会被阻止：

GET  /services/data/vXX.0/setup/org/preferences/ITSMTeamsEnabled
PATCH /services/data/vXX.0/setup/org/preferences/ITSMTeamsEnabled  body: {"desiredState": true}

两者都会返回 401：

{"error_code":"API_ERROR","status_code":401,"body":"[{\"errorCode\":\"INSUFFICIENT_ACCESS\",\"message\":\"Cannot read data!\"}]"}

（PATCH 会返回 "Cannot update preference value!"。）这是一个真实的代码级访问限制（setup-connect-impl 中的 StandardMetadataChecker 会转发 Aura NoAccessException——“bit(s) do not have READ/WRITE access”——且仅针对这一偏好设置），不是版本前缀或路由错误。不要尝试使用不同的 API 版本或请求体重试此路由。

经验证可行的路径不同：启用 Go 功能，而不是直接启用偏好设置。 Salesforce Go 功能启用 Connect API 使用不同的访问检查；启用功能时，会将 ITSMTeamsEnabled（以及相关功能状态）作为副作用一并开启。

---

工作流

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

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

响应格式：

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

如果 status 已是 "ENABLED"，则跳到步骤 3（验证），不要重新启用。 如果 enableBlockedReasons 非空，请在尝试步骤 2 之前将这些原因告知用户（通常是缺少许可证/附加组件）。

步骤 2 — 启用功能

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

已知问题（已验证）： 即使功能最终成功变为 ENABLED，此调用也可能返回 500 INTERNAL_ERROR。不要将此处的 500 视为彻底失败——务必重新运行步骤 1（features/status）和步骤 3（读取 ITSMTeamsEnabled），然后再根据实际状态向用户报告。如果重试一次后状态仍显示 NOT_ENABLED，再报告失败并附上原始错误。

步骤 3 — 验证 ITSMTeamsEnabled 已切换

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

预期结果为 200 {"isPreferenceEnabled": true}。这确认了底层偏好设置现已启用；否则，无法通过直接 PATCH 访问此设置。启用功能时，此设置会作为副作用一并启用。

步骤 4 — 报告阶段性状态（设置尚未完成）

报告功能状态以及 ITSMTeamsEnabled 读取结果是否为 true，但要将其表述为进展，而非已完成。 启用 Go 功能只是第一部分；只有注册 Microsoft Entra 应用、将其凭据写入 Named Credential 和 Auth Provider，并授予管理员同意（步骤 4a）后，集成才会正常运行。不要将 Teams 标记为“已完成”，也不要将其作为已完成事项交还协调员。明确说明：“Salesforce 功能已启用；Teams 集成尚未完成——接下来需要注册 Microsoft Entra 应用。” 然后继续步骤 4a。有关“完成”的要求，请参阅下文的完成标准。

步骤 4a — 按照 Go 页面自身的顺序操作：创建 Entra 应用 → 配置 Named Credentials → 授予同意

Salesforce Go 功能页面（Setup → Salesforce Go → 此功能， .../lightning/setup/page/feature/service-cloud-itsm-teams-integration/home?topic=SalesforceGo）会显示一份包含**“完成必需步骤” → “将 Salesforce 与 Teams 集成”**的清单，准确列出三项，顺序如下——已通过该页面的实时截图验证。请遵循此顺序；不要在 Entra 应用尚未创建时提前配置 Named Credentials，也不要将“授予 Azure 管理员同意”视为可选项：

1. 创建 Microsoft Entra ID 应用（“设置 Microsoft Entra ID 应用”按钮 — 打开 portal.azure.com）。此子步骤没有 Salesforce API；请向用户提供以下准确的点击路径，并等待他们提供生成的值：
   • portal.azure.com → Microsoft Entra ID → 应用注册 → 新注册。 为应用命名一个便于识别的名称（例如 Salesforce ITSM Teams Integration）；除非用户的组织跨越多个租户，否则选择单租户即可。创建时将重定向 URI 留空 — 以下委派 Graph 权限需要重定向 URI，但要稍后将其添加为 Auth Provider 回调（步骤 5；参见 references/azure-credential-population.md）。
   • 在应用的概述页面中，记下应用程序（客户端）ID和目录（租户）ID。
   • 证书和机密 → 新建客户端机密 → 立即复制机密值（离开页面后将无法恢复）。
   • API 权限 → 添加权限 → Microsoft Graph → 委派权限 → 添加以下全部 17 项，然后点击授予管理员同意，使每一行都显示已授予。这些是委派权限（不是应用程序权限）— 已验证可用的权限集： Channel.Create、Channel.ReadBasic.All、ChannelMember.Read.All、 ChannelMember.ReadWrite.All、ChannelMessage.Edit、ChannelMessage.Read.All、 ChannelMessage.ReadWrite、ChannelMessage.Send、Team.Create、Team.ReadBasic.All、 Group.Read.All、Group.ReadWrite.All、openid、profile、email、offline_access、 User.Read。其中一些权限需要管理员同意（需要管理员同意 = 是），因此必须点击授予管理员同意 — 未获同意的必需权限会导致 Teams 调用失败（参见 AccessDenied 注意事项）。不要添加 TeamworkAppSettings.ReadWrite.All（不在可用权限集中）。不同版本之间的范围可能会变化 — 如果 MS 文档列出了更多权限，请添加并重新授予同意。
   • 不要在聊天中暴露机密：客户端 ID 和 租户 ID 不属于机密，可以在对话中提供；客户端机密属于机密 — 绝不要在聊天中索要。让用户将其写入被 git 忽略的文件：将 <secret-file> 替换为作业/临时路径（例如 $CLAUDE_JOB_DIR/tmp/teams-secret），然后让他们将以下内容原样复制粘贴到 Claude Code 提示词中（引号之间应填写机密值，而非机密 ID）：

     ! umask 077; printf '%s' 'PASTE-CLIENT-SECRET-HERE' > <secret-file> && echo written
     

     保留开头的 ! — 它会在此会话的 Bash 中运行该行，使文件得以保留。它会输出 written；然后在写入时从 <secret-file> 读取机密（步骤 5），绝不要回显或记录该机密。

     **注意：**带 ! 前缀的行会显示在聊天记录中 — 如果机密出现在其中，

     请视其为已泄露，并在设置完成后让用户在 Azure 中轮换该机密。

2. 配置设置命名凭据（Go 页面上的“前往设置”按钮 — 本技能自动执行操作的手动等效方式）。获得客户端 ID / 租户 ID 且机密已存入机密文件后，不要让用户在 Setup 中输入任何内容 — 请按照下方步骤 5 中“在用户提供客户端 ID/机密的情况下填充 MSTeamsSetupClientCredentialsEC”的说明，直接调用 Named Credential API。还必须将同一组值写入 microsoft_auth_provider Auth Provider（这是入站 SSO 端，与出站 Graph Named Credential 不同）— 组织提供的此 Auth Provider 为空。也要自动完成此操作；参见步骤 5 中“填充 microsoft_auth_provider Auth Provider”。这两项都使用相同的客户端 ID / 租户 ID / 客户端机密，必须一并填充 — 只填充 Named Credential 会导致门户 SSO 登录无法使用。
3. 授予 Azure 管理员同意（Go 页面上的“授予同意”按钮）。点击后会打开一个模态窗口，其中包含一次性同意链接，指向一个由 Salesforce 所有的固定 Entra 应用 （client_id=cd6bd63f-41ef-47cc-9465-86e986179a29，租户段为 organizations — 不是用户自己的租户 ID，也不是步骤 1 中创建的应用），该应用请求 Organization.ReadWrite.All 委派范围：

   https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize?client_id=cd6bd63f-41ef-47cc-9465-86e986179a29&response_type=code&redirect_uri=https://salesforce.com&response_mode=query&scope=Organization.ReadWrite.All
   

   此链接是静态的 — 无需按组织或用户单独获取，headless-360 也没有生成或分发该链接的操作（该链接由内部 Aura 控制器呈现，没有公开的 Connect API 对应接口）。粘贴此确切链接，并告知用户以 Microsoft 租户管理员身份登录后点击该链接以授予同意 — 此操作需要以 Microsoft 管理员身份进行身份验证，本技能无法通过 API 执行。 用户在上文执行的所有操作（步骤 1 中点击 Azure，以及步骤 3 中点击同意）都由用户手动负责，因为 Salesforce API 无法访问 Azure/Entra。所有 Salesforce 端的操作——在步骤 2 中将提供的凭据（从 gitignored 密钥文件中读取，而非从聊天中读取）写入 Named Credential——均由此技能负责自动化；这种分工正是此技能的核心目的。

第 4b 步 — 委托给 IT Desk / IT Service 子技能

在处理“Set Up Salesforce IT Desk”/“Set Up Salesforce IT Service”清单组之前，先询问用户需要哪一项——这是此功能的两个独立部分（处理者端与员工端），用户可能只需要其中一项：

• Salesforce IT Desk — 供 IT 代理/处理者在 Teams 中协同处理并解决工单。 调用 service-itsm-teams-itdesk-configure。
• Salesforce IT Service — 供员工在 Teams 中创建和管理自己的工单。 调用 service-itsm-teams-itservice-configure。
• 两者都需要 — 调用这两个子技能。

每个子技能都会端到端处理各自的 3-4 项清单组（启用 <app> → 在 Teams 上安装 <app> 应用 → 管理用户访问权限 → 可选的第 4 项）——请勿在此重复该逻辑。

第 4c 步 — 委托嵌入式 Agentforce Agent（Teams“询问 AI Agent”）

如果用户希望嵌入式 Agentforce Agent 在 Teams 自定义客户端（“Salesforce Employee Assist” → “Ask AI Agent”）中回复——即构建 Teams_AgentForce MIAW 部署、其 Web 通道（User Verification ON + 一个 JWKS_URL Key Set）、指向 IT Service Employee Agent 的路由流，以及门户用户的 Agent Access 权限集——**请调用 service-itsm-teams-employee-agent-configure。**这是一个独立且功能庞大的能力，有自己的对象模型；请勿在此处尝试内联处理。必须先创建员工门户站点（experience-portal-create）。

第 5 步 — 注册首选站点（Teams 扩展），需在 Azure 凭据创建后进行

组织中存在名为 MSTeamsSetupClientCredentialsEC 的外部凭据后（参见第 4a 步和下方的“填充...”），注册应为 Teams 集成提供支持的 Experience Cloud 站点：

mcp__headless-360__dispatch(
  method: "POST",
  url:    "/services/data/v67.0/connect/service-itsm-teams/graph-api/extensions",
  body:   { "siteUrlPathPrefixes": ["<site urlPathPrefix from GET /connect/communities>"] }
)

稍后更新：

mcp__headless-360__dispatch(
  method: "PATCH",
  url:    "/services/data/v67.0/connect/service-itsm-teams/graph-api/extensions/{extensionId}",
  body:   { "siteUrlPathPrefixes": ["<updated prefix list>"] }
)

如果返回 400 UNKNOWN_EXCEPTION "...external credential \"MSTeamsSetupClientCredentialsEC\" might not exist"，说明尚未完成 Azure/Entra 步骤（注意事项）——这并非调用本身的问题。

如果返回的是 AccessDenied（或 400 UNKNOWN_EXCEPTION "...Unable to fetch tenant ID"），即使 EC 显示 authenticationStatus: "Configured" 也是如此，那么原因几乎总是Azure/Entra 授权未完成——可以修复，并非许可证限制（已验证：完成以下操作后，同一调用从 AccessDenied 变为 201 Success）。请按顺序检查：(1) 尚未授予管理员同意——第 4a 步中的多个范围标注为 Admin consent required = Yes，在管理员点击授予管理员同意之前会显示为 AccessDenied；确认每一行都显示为 Granted。(2) 凭据为空——重新预配可能会清空 EC；重试时必须显示为 Configured，因此请重新填充。两项都完成后，重试第 5 步。不要通过将 Delegated 切换为 Application 来“修复”此问题——已验证的可用集成使用 Delegated + 管理员同意；切换为 Application 会偏离已验证的正确配置。

获取 Azure Client ID 和 Tenant ID（通过聊天提供）以及 Client Secret（从第 4a 步写入的 Git 忽略密钥文件中读取——绝不通过聊天索取）后，请自行执行 Salesforce 端的写入操作——不要让用户在 Setup 中输入值。完整且已验证的操作指南（填充 MSTeamsSetupClientCredentialsEC、通过 Metadata API 填充用于入站 SSO 的 microsoft_auth_provider Auth Provider、将门户用户的 Username 与 Microsoft UPN 匹配，以便 MsTeamsItsmSSOHandler 解析用户身份，以及授予门户用户 Teams Connect API 所需的 ApiEnabled 权限）——包含准确的 API 请求体、AuthProvider MDAPI 模板、Web 与 SPA 回调限制及相关注意事项——见：

→ references/azure-credential-population.md

---

完成标准 — 满足以下所有条件前，切勿报告 Teams 设置“已完成”

启用 Go 功能（步骤 1–3）是必要条件，但并不足够。最常见的失败情形是在步骤 3 后就宣布 Teams“已配置／已完成”，但 Microsoft Entra 应用仍未注册——这会导致 Teams 内登录和出站 Graph 集成无法正常工作。请将 Entra 应用注册视为完成设置的阻断性前提条件，绝非可选的后续步骤。只有在验证以下每一项后（而不只是告知用户操作步骤），才能报告已完成：

1. 已启用功能 — service-cloud-itsm-teams-integration 显示 ENABLED，且 ITSMTeamsEnabled 显示 true（步骤 1–3）。
2. 已注册 Microsoft Entra 应用 — 用户已完成步骤 4a 中的 Azure 操作，并在聊天中提供了 Client ID 和 Tenant ID，同时通过步骤 4a 的复制粘贴命令将 Client Secret 写入 git 忽略的密钥文件（绝不可粘贴到聊天中）。在用户完成这些操作之前，请停止并等待——这是硬性门槛；不得越过此步骤，也不得绕过它报告已完成。
3. 已填入凭据（Salesforce 端，由此技能自动完成） — MSTeamsSetupClientCredentialsEC 显示 authenticationStatus: "Configured"，并且 microsoft_auth_provider Auth Provider 已填入相同的值（参见 references/azure-credential-population.md）。只填入其中一处会导致出站 Graph 或入站 SSO 无法正常工作。
4. 已授予管理员同意 — 用户已点击步骤 4a 第 3 项中的静态同意链接，并以 Microsoft 租户管理员身份登录。
5. 已注册首选站点 — 步骤 5 中的 Teams 扩展调用返回成功（或用户已明确推迟员工站点部分）。

如果第 2–4 项中有任何一项待完成，正确状态应为 “因 Microsoft 管理员操作受阻 — Teams 集成未完成”，并明确指出下一步操作。部分完成不算成功；不要淡化这一点，也不要让协调者将此功能标记为 Done。

---

禁用（如有请求）

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

之后重新运行步骤 1/步骤 3 进行确认。禁用 ITSMTeamsEnabled 的底层配置（SSO 处理程序、命名凭据／外部凭据、PKCE OAuth 客户端）可能无法仅通过此调用完全撤销——请向用户确认是否还需要移除这些项目，并将其作为单独的手动 Setup 操作处理。

---

相关的独立启用偏好设置

两个同级组织偏好设置分别控制此功能的“Fulfiller Hub”和“Employee Hub”部分；与 ITSMTeamsEnabled 不同，这两个设置可通过标准 Setup preferences Connect API 直接写入——GET/PATCH /services/data/v67.0/setup/org/preferences/OrgHasITSMFulfillerTeams （“启用 Salesforce IT Desk”）和 .../OrgHasEmployeeServiceTeams（“启用 Salesforce IT Service”）。两者都接受 {"desiredState": true}，并返回 {"isPreferenceEnabled": true}。它们是彼此独立的开关——启用它们不会解除 ITSMTeamsEnabled 的阻止状态；如果用户需要两个 Hub，请同时启用这些设置，而不是用它们替代步骤 2 中的功能启用调用。

---

注意事项

已验证且会影响结果的问题（直接 PATCH 返回 401、Auth Provider 为空、Azure Web 与 SPA 重定向、Username=UPN 处理程序、门户 API-Enabled、静态同意链接、版本前缀要求等）都汇总在 references/gotchas.md 中。报告某个步骤失败或重试启用操作前，请先阅读。

---

相关技能

技能	适用情形
service-itsm-teams-itdesk-configure	“Set Up Salesforce IT Desk”清单组（服务处理人员端）——此技能会委派给它（见步骤 4b）
service-itsm-teams-itservice-configure	“Set Up Salesforce IT Service”清单组（员工端）——此技能会委派给它（见步骤 4b）
service-itsm-teams-employee-agent-configure	让嵌入式 Agentforce Agent 在 Teams“Ask AI Agent”自定义客户端中回复（Teams_AgentForce MIAW 部署）——此技能会委派给它（见步骤 4c）
service-itsm-swarming-configure	启用 service-cloud-swarming Go 功能，以便“Set Teams as Collaboration Tool for Swarming”——由 service-itsm-teams-itdesk-configure 调用，而非由此技能直接调用
通知渠道偏好设置	启用 Notifications/TeamsNotifications 偏好设置与此功能属于不同事项（目前尚无专用的子技能）
experience-portal-create	创建员工服务门户/站点本身
service-itsm-channels-coordinate	Teams、Slack、Swarming、通知和门户的顶层菜单