service-itsm-teams-itdesk-configure

设置 Salesforce IT Desk（Microsoft Teams）

在 Teams ITSM Go 页面（service-cloud-itsm-teams-integration 的功能页面）上完成 “Set Up Salesforce IT Desk” 检查清单组——这是 Teams ITSM 集成中供履行人员／Agent 使用的一侧，让 IT Agent 可以在 Teams 中协同处理并解决工单。每项操作都会通过 headless-360 执行。

范围

• 范围内：启用 OrgHasITSMFulfillerTeams 偏好设置；向用户提供 IT Desk 应用的确切 Teams Marketplace 链接和帮助文档，以便安装；为已确认的用户分配 TeamsForITSrvcsUser/MicrosoftGraphAccess 权限集，并配置组织范围的 API-Enabled 登录权限集（仅需创建一次，登录时必需）；将“Set Teams as Collaboration Tool for Swarming”委派给 service-itsm-swarming-configure。
• 范围外：基本 Teams Salesforce Go 页面开关（ITSMTeamsEnabled）、Azure/Entra 应用注册、Named Credential 填充，以及 Teams 扩展／首选站点注册——请使用 service-itsm-teams-configure（此技能的前置条件）。IT Service／员工一侧的检查清单——请使用 service-itsm-teams-itservice-configure。启用 service-cloud-swarming Go 功能本身——请委派给 service-itsm-swarming-configure。

**前置条件：**先运行 service-itsm-teams-configure（也可同时运行）——此技能假定 service-cloud-itsm-teams-integration Go 功能已启用。

**一次只执行一个步骤。**这些步骤会执行真实的、会改变状态的 API 调用。每次只运行一项操作，显示其结果，确认成功后再继续——不要将多个设置调用合并到一个并行区块中。

---

工作流

步骤 1 — 启用 Salesforce IT Desk

这是一个直接的组织偏好设置开关（与 ITSMTeamsEnabled 不同，它支持直接 PATCH）——请自行通过 API 启用，不要让用户点击 Setup 开关：

mcp__headless-360__dispatch(
  method: "PATCH",
  url:    "/services/data/v67.0/setup/org/preferences/OrgHasITSMFulfillerTeams",
  body:   { "desiredState": true }
)

预期结果为 200 {"isPreferenceEnabled": true}。告知用户该功能已启用——不要让他们自行切换开关。

步骤 2 — 在 Teams 上安装 Salesforce IT Desk 应用（由用户负责）

此技能无法调用任何 Salesforce 或 Microsoft API 将 Teams 应用安装到租户的应用目录中——这始终需要用户以具备足够租户权限的账号登录 Microsoft Teams 管理中心／AppSource，手动点击“Add”。向用户提供确切的 Marketplace 链接和帮助文档；不要尝试自动执行此步骤。

• Marketplace（已通过 Go 页面的“Go to Microsoft Marketplace”按钮实时验证）：

  https://marketplace.microsoft.com/en-us/product/teams-app/WA200009869?tab=Overview
  

• 帮助文档：https://help.salesforce.com/s/articleView?id=service.it_srvce_msteams_cnfig_fulfilerhub_app.htm&type=5

请同时提供这两项内容，让用户在安装链接之外也能参考自助资料。还要告知用户，履行人员登录 Teams 时使用的 Azure/Microsoft 账号邮箱必须与该 Salesforce 用户的邮箱／Username 一致——SSO 会将 Microsoft UPN 解析为 Salesforce Username，因此两者不匹配会导致登录静默失败。

然后停止并等待用户确认应用已安装（他们回复 “installed”）。此操作只能由人工完成；不要在未完成此操作的情况下继续步骤 3 的用户访问权限分配，也不要伪造确认——请等待用户实际回复。

步骤 3 — 管理用户访问权限

“管理用户访问权限”（Go 页面上的“Manage”按钮）会分配两组权限 — 已通过“Manage Microsoft Teams for Employee Service User Access”对话框实时验证：

• TeamsForITSrvcsUser（标签 “Microsoft Teams for IT Services”，由 PSL TeamsForITSrvcsPsl 提供支持）
• MicrosoftGraphAccess（标签 “MicrosoftGraphAccess”）— 在同一对话框中一并分配。

还需要第三组“登录”权限集 — 每个组织只需配置一次。 对话框中的两组权限集提供 IT 服务台的界面，但不能让处理人员登录：两者的 PermissionsApiEnabled = false，因此嵌入式应用的 Connect 调用会返回 403，登录失败并显示“server not reachable”。处理人员需要一组包含 API Enabled 系统权限的权限集。某些组织中已有名为 Teams_Employee_ApiAccess 的权限集（这是一个自定义权限集 — 不要假设新客户组织中已有该权限集）；否则请创建它。这是一个组织范围共享的资源 — 同一权限集也涵盖 IT Service 登录，因此只需创建一次，然后在需要的地方分配即可。请参阅下方的登录前置条件，了解先查找或创建、再分配的操作步骤。请将此操作作为本步骤的一部分完成；不要等到登录出问题后再处理。

不要直接给所有活跃用户分配权限。 询问用户应该让哪些特定用户获得访问权限。如果他们想先查看用户列表，而不是直接指定用户，请分页显示 — 每页最多显示 10 个用户，然后先询问“还想查看更多吗？”，再显示下一页，因为组织中可能有数百或数千名用户：

mcp__headless-360__dispatch_readonly(
  method: "GET",
  url:    "/services/data/v67.0/query",
  queryParams: { "q": "SELECT Id, Name, Username, Email FROM User WHERE IsActive = true ORDER BY Name LIMIT 10 OFFSET <page * 10>" }
)

已验证的注意事项： 在临时/测试组织中（某些实际组织中也可能如此），此查询的前几页通常大多是非员工系统/集成账号 — 例如 Automated Process、Bot User、Insights Integration、*.ext 集成用户、ESW_* / *Site Guest User 访客用户，以及 DigitalAgent.* Agent 用户。向用户展示某一页时，请标明这些可能不是员工账号（不要悄悄从列表中筛掉它们 — 用户仍可能想给其中某个账号分配权限，但请指出哪些行看起来是系统账号，这样用户就不必自己猜测）。如果用户表示某批列出的账号“不是员工用户，跳过”，请转到下一页，而不要给其中任何账号分配权限。

用户确认具体用户后，查询两个对话框权限集的 Id（它们在组织内是固定的，但不要将其硬编码 — 每次都要重新查询；第三组“登录”权限集请参阅下方的登录前置条件）：

mcp__headless-360__dispatch_readonly(
  method: "GET",
  url:    "/services/data/v67.0/query",
  queryParams: { "q": "SELECT Id, Name FROM PermissionSet WHERE Name IN ('TeamsForITSrvcsUser','MicrosoftGraphAccess')" }
)

然后通过 PermissionSetAssignment 将两组权限集都分配给每个已确认的用户（每个用户/权限集组合对应一条记录 — 可根据需要分多次调用，这里没有公开批量分配端点）：

mcp__headless-360__dispatch(
  method: "POST",
  url:    "/services/data/v67.0/sobjects/PermissionSetAssignment",
  body:   { "AssigneeId": "<user id>", "PermissionSetId": "<permission set id>" }
)

可通过重新查询该 AssigneeId 对应的 PermissionSetAssignment 进行验证，或者直接信任分配调用返回的 201，并读取以下查询结果进行确认：SELECT ... FROM PermissionSetAssignment WHERE AssigneeId = '<user id>' AND PermissionSetId = '<permset id>'。

登录前提条件 — 配置登录权限集（已验证）

仅配置 TeamsForITSrvcsUser + MicrosoftGraphAccess 后，IT Desk 界面 已完成配置，但履约人员在 Teams 中打开 IT Desk 应用时，会在登录页面遇到 “服务器不可访问”。经验证，阻碍因素是 API 已启用：两个对话框权限集的 PermissionsApiEnabled = false（已在线验证），因此嵌入式应用的 Connect 调用会返回 403。为履约人员分配一个 PermissionsApiEnabled = true 的权限集即可解决登录问题。此权限集是组织范围内创建一次并与 IT Service 共享的 — 先查找或创建，再进行分配：

1. 如果已存在则重用（已启用 API 的权限集 — 通常为 Teams_Employee_ApiAccess）： SELECT Id, Name, PermissionsApiEnabled FROM PermissionSet WHERE Name = 'Teams_Employee_ApiAccess'。 如果找到且 PermissionsApiEnabled = true，则记录其 Id 并跳到第 3 步。
2. 否则创建一次（已验证 PermissionsApiEnabled 可创建）：

   mcp__headless-360__dispatch(
     method: "POST",
     url:    "/services/data/v67.0/sobjects/PermissionSet",
     body:   { "Name": "Teams_Employee_ApiAccess", "Label": "Teams Employee API Access", "PermissionsApiEnabled": true }
   )
   

   记录返回的 Id。由于该权限集在整个组织范围内共享，如果后续运行（或 IT Service 技能）已创建它，请勿重复创建 — 第 1 步的查询会进行检查。
3. 将其分配给每位已确认的履约人员，并与两个对话框权限集一同分配：

   mcp__headless-360__dispatch(
     method: "POST",
     url:    "/services/data/v67.0/sobjects/PermissionSetAssignment",
     body:   { "AssigneeId": "<user id>", "PermissionSetId": "<login permset Id>" }
   )
   

分配后，请用户完全关闭并重新打开 Teams 应用（OAuth 授权会缓存在客户端）。另外，请确认 CORS Allowed Origins 中包含 https://teams.cloud.microsoft 和 https://cdn.scs.static.lightning.force.com（SELECT UrlPattern FROM CorsWhitelistEntry）。

为 Teams 登录提供支持的 ServiceCloudMSTeamsEca 外部客户端应用会在 Go 页面切换开关后自动安装，无需配置 — Teams_Employee_ApiAccess 授予 API 已启用权限，与 ECA 无关。请勿添加 SetupEntityAccess 行或更改 ECA 的 OAuth 策略。

如果分配已启用 API 的权限集后，在新会话中登录仍失败，则剩余的嫌疑项是配置文件中的 “Allow OAuth for employees” 复选框（仅限 Setup UI — 无 API 写入路径）。 完整的通过／失败诊断流程请参阅 service-itsm-teams-itservice-configure 的 登录前提条件。

步骤 4 — 将 Teams 设为协同处理的协作工具（委派）

必须先启用 service-cloud-swarming Go 功能，才能完成此第 4 项检查清单。 请勿在此处直接启用该功能 — 请调用专用的 service-itsm-swarming-configure 技能，而不是重复实现功能启用逻辑：

Invoke the service-itsm-swarming-configure skill.

该技能会启用 service-cloud-swarming 并且通过 PATCH /services/data/v67.0/setup/org/values/SWARM_COLLABORATION_TOOL 将 SWARM_COLLABORATION_TOOL 写入 "Teams" — 此检查清单项现已实现端到端全自动化，无需手动点击“Go to Feature Page”。

---

注意事项

问题	详情
需要先启用 Teams Salesforce Go 页面功能	OrgHasITSMFulfillerTeams 不会直接控制或依赖 ITSMTeamsEnabled，但只有启用 service-cloud-itsm-teams-integration 后才会显示 Go 页面清单——请先运行 service-itsm-teams-configure。
OrgHasITSMFulfillerTeams 不会解除 ITSMTeamsEnabled 的限制	这是两个独立的设置位——启用此首选项本身不会解除 Teams Salesforce Go 页面切换首选项的限制，反之亦然。
“将 Teams 设为群组协作工具”需要先启用 service-cloud-swarming	请委派给 service-itsm-swarming-configure，而不是在此处直接启用该功能。该技能既会启用此功能，也会将 SWARM_COLLABORATION_TOOL 写入 "Teams"——整个清单项都可通过 API 完成，而不只是启用基础功能。
权限集 / PSL	启用功能后，本次会话中自动配置了 TeamsForITSrvcsUser、MicrosoftGraphAccess（权限集）和 PSL TeamsForITSrvcsPsl，并立即确认其状态为 Active（10 个许可证）——获得 TeamsITSrvcsAddOn+IncidentManagementAddOn 许可证后，无需手动创建 PSL / 权限集。
Manage-User-Access 权限集不包含登录权限——请分配 API-Enabled 权限集	已验证：分配 TeamsForITSrvcsUser + MicrosoftGraphAccess 后，IT Desk Agent 仍无法登录 Teams，并出现 “server not reachable”——这两个对话框权限集的 PermissionsApiEnabled = false，因此嵌入式应用的 Connect 调用会返回 403。解决方法是使用 API-Enabled 权限集（PermissionsApiEnabled = true），通常为 Teams_Employee_ApiAccess——这是一个供 IT Service 共用的自定义组织范围权限集，因此只需创建一次，然后分配即可。测试组织可能已配置该权限集；全新的客户组织则不会有，因此请先查找，不存在时再创建。（ServiceCloudMSTeamsEca ECA 会由 Go 页面切换开关自动安装，无需配置——它不控制登录，且与 Teams_Employee_ApiAccess 无关。）请参阅 步骤 3 → 登录前置条件。
需要版本前缀	headless-360 dispatch/dispatch_readonly 不会解析 API 版本——始终传入完整的 /services/data/vXX.0/... 前缀。

---

相关技能

技能	何时改用 / 同时使用
service-itsm-teams-configure	启用基础 Teams Salesforce Go 页面切换开关、注册 Azure/Entra 应用、填充 Named Credential，以及注册 Teams 扩展——这是使用此技能的前置条件
service-itsm-teams-itservice-configure	清单中 IT Service / 员工部分（启用 IT Service、安装 IT Service 应用、管理用户访问权限、选择 Digital Experience 站点）
service-itsm-swarming-configure	为“将 Teams 设为群组协作工具”启用 service-cloud-swarming Go 功能——此技能会委派给它，而不重复实现该逻辑
service-itsm-channels-coordinate	Teams、Slack、Swarming、Notifications、Portal 的顶层菜单