service-itsm-teams-itservice-configure

设置 Salesforce IT Service（Microsoft Teams）

完成 Teams ITSM Go 页（service-cloud-itsm-teams-integration 的功能页面）上的 “设置 Salesforce IT Service” 检查清单组——这是 Teams ITSM 集成的员工端，供员工在 Teams 中创建和管理自己的工单。每项操作都通过 headless-360 执行。

范围

• 包含：启用 OrgHasEmployeeServiceTeams 偏好设置；向用户提供准确的 Teams Marketplace 链接和 IT Service 应用安装帮助文档；为已确认的用户分配 TeamsForEmployeeUser 权限集；通过 SLACK_PREFERRED_SITE 组织值选择要关联 Teams 的 Digital Experience Site。
• 不包含：Teams Salesforce Go 页面的基础开关（ITSMTeamsEnabled）、Azure/Entra 应用注册、Named Credential 填充，以及 Teams 扩展程序/首选站点注册——请使用 service-itsm-teams-configure（此技能的前置条件）。检查清单中 IT Desk/处理人员的部分——请使用 service-itsm-teams-itdesk-configure。

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

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

---

工作流

步骤 1 — 启用 Salesforce IT Service

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

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

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

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

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

• Marketplace（已通过 Go 页面的“前往 Microsoft Marketplace”按钮在线验证）：

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

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

请同时打印这两项。还要告知用户：员工登录时使用的 Microsoft 电子邮件地址必须与该 Salesforce 用户的 Username 一致（SSO 会将 MS UPN 映射到 Username；不一致会导致登录失败且不显示任何提示）。 然后暂停，直到用户回复 “已安装”——这是只能由人工执行的操作；不要继续，也不要伪造确认。

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

“管理用户访问权限”（Go 页面上的“管理”按钮）用于分配权限集 — 已通过“管理 Microsoft Teams for Employee 服务用户访问权限”对话框确认：

• TeamsForEmployeeUser（标签为 “Teams for Employee”，由 PSL TeamsForEmployeePsl 支持）

不要直接为所有活跃用户分配权限。 询问用户具体要为哪些用户授予访问权限。 如果他们想先查看用户列表（而不是直接指定用户），请分页显示 — 每页最多显示 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>" }
)

授予对象 — 提前提醒用户： 目标必须是真实员工 / UEL 用户，且其电子邮件地址必须存在于 Azure/Entra 侧（同一租户中的 Microsoft 账号）。登录使用 SSO（MS UPN → Salesforce Username），因此如果将权限分配给没有匹配 Azure 账号的用户 — 或电子邮件地址与 UPN 不一致 — 登录会静默失败（参见上文 UPN↔Username 说明）。分配前请说明这一点；切勿分配给系统 / 集成账号。

已确认的注意事项（识别不应选择的用户）： 在临时 / 测试组织中，第一页或前几页通常以非员工账号为主 — 例如 Automated Process、Bot User、Insights Integration、*.ext 集成用户、ESW_* / *Site Guest User 访客、DigitalAgent.* Agent — 这些都不是员工 / UEL 用户，也没有 Azure 身份。请标记这类行可能不是员工（不要静默过滤 — 请明确指出）；如果用户说“不是员工用户，跳过”，就转到下一页。

用户确认具体用户后，查询权限集的 Id（该值在每个组织中都稳定，但不要硬编码 — 每次都重新查询）：

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

然后通过 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>' 进行回读。

登录前提条件（用户要在 Teams 中实际登录 IT Service 的必备条件）

分配上述权限集是必要条件，但并非充分条件——UEL 用户在 Teams 中打开 IT Service 应用后，仍可能遇到无提示的登录失败，除非以下三项条件也全部满足。启用用户时，请一并核实（并设置）这些条件：

1. 员工登录配置文件（例如 Unified Employee）中的 “Allow OAuth for employees” — Setup → Profiles → (profile) → Session Settings → 勾选 Allow OAuth for employees。 请在 Setup UI 中设置此项。 它不是 Profile SObject 字段（在 Profile describe 中不会显示 OAuth 字段），也不是 Metadata 元素 Profile.sessionSettings.allowOauthForEmployees ——包含 <sessionSettings><allowOauthForEmployees> 的 Profile metadata 部署会验证失败：Element {…}sessionSettings invalid at this location in type Profile（已于 2026 年 8 月验证）。此项也无法通过无头 360 Connect/REST/Tooling dispatch 读取或写入。请使用 Setup UI 中的复选框。已确认的阻塞原因：关闭此项时，嵌入式应用的 OAuth 握手会失败，登录也不会完成，且不会显示提示——社区登录成功（LoginHistory 中 “Employee Login to Community” = Success），但不会为该用户创建任何 OauthToken，Teams 应用会再次弹出 “Single Sign-On / Login with URL” 选择器（通常还会弹出 /…/setup/secur/RemoteAccessAuthorizationPage “Service Not Available” 窗口）。

2. CORS Allowed Origins 必须包含两个 Teams 来源。通过 dispatch_readonly GET /services/data/v67.0/query 查询 SELECT Id, UrlPattern FROM CorsWhitelistEntry，并使用 dispatch POST /services/data/v67.0/sobjects/CorsWhitelistEntry 请求体 {"UrlPattern": "<origin>"} 创建缺少的条目（这是一个数据 API sobject，不是 Tooling 类型——Tooling POST/query 会返回 NOT_FOUND/INVALID_TYPE）：

   • https://teams.cloud.microsoft
   • https://cdn.scs.static.lightning.force.com ——嵌入式 IT Service 界面加载所用的 Lightning 静态资源 CDN。已确认的阻塞原因：缺少此来源时（即使已添加 teams.cloud.microsoft），浏览器也会阻止资源/OAuth 预检请求，导致登录无提示失败。添加后，请让用户强制刷新页面 / 清除 Teams 应用缓存。

3. 用户的系统权限集中必须启用 “API Enabled” 系统权限（PermissionsApiEnabled = true）——不能只在基础配置文件中启用，否则嵌入式应用的 API 调用会被拒绝，用户无法登录。请使用 IT Desk 采用的全组织通用、仅创建一次的权限集（通常名为 Teams_Employee_ApiAccess）：查询 PermissionSet WHERE Name = 'Teams_Employee_ApiAccess'；如果不存在，则创建一次（POST /sobjects/PermissionSet {"Name":"Teams_Employee_ApiAccess","Label":"Teams Employee API Access","PermissionsApiEnabled":true}）； 然后分配该权限集。不要创建重复项。请参阅 service-itsm-teams-itdesk-configure 中的 Login prerequisite。

如果用户反馈“无法在 Teams 中登录 IT Service”，且步骤 1–4 看起来都已完成，请先逐一检查这三个前提条件——它们是最常见的无提示登录阻塞原因。有关完整的通过/失败诊断流程（包括用于定位门户用户 OAuth 故障的 OAuth 令牌创建检查），请参阅下方的故障排除：Teams 中的 Employee Service 登录与 Agent。

第 4 步 — 选择数字体验站点

此清单项（“数字体验站点名称”下拉菜单，设置前当前显示为“无”） 读取/写入组织值 SLACK_PREFERRED_SITE——与 Swarming 的 SWARM_COLLABORATION_TOOL 使用相同的 OrgValueUtil.OrgValues Java 枚举机制——且不受任何 Teams 许可证或 Azure/Entra 凭据限制，因此无需依赖 Teams 设置的其他部分即可使用。

1. 列出组织中的所有数字体验站点：

   mcp__headless-360__dispatch_readonly(method: "GET", url: "/services/data/v67.0/connect/communities")
   

   如果组织还没有数字体验站点（列表为空），必须先创建一个才能完成此步骤——转交给 experience-portal-create 来配置新站点（员工服务 / IT 支持门户适用于此用例），然后返回此处并提供其 Id。
2. 向用户展示完整列表并请其选择一个。如果用户没有选择，就自行选一个（如果只有一个站点，则选该站点；否则选择合理的默认项，例如最近修改的 Live 站点），并明确告知用户选了哪个站点——不要默默继续。
3. 先检查当前值（如果已设置为所选站点的 Id，则跳过写入）：

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

   stringValue 保存当前选择——所选站点的 Id，或 "None"。
4. 使用站点的 Id 写入所选项（来自步骤 1 的 connect/communities 响应中的 Network 记录 Id，而不是 urlPathPrefix）：

   mcp__headless-360__dispatch(
     method: "PATCH",
     url:    "/services/data/v67.0/setup/org/values/SLACK_PREFERRED_SITE",
     body:   { "orgValue": "<site Id>" }
   )
   

   已在实际环境中验证：使用站点的 Network Id（例如 0DBSB000002EYwj4AG）执行 PATCH 后返回 200 {"stringValue": "<that Id>", ...}，随后执行 GET 确认该值已持久化。
5. 重新执行步骤 3 的 GET 以确认。

第 5 步 — 让嵌入式 Agentforce Agent 在 Teams 中回复

完成步骤 1–4 后会配置 IT Service 门户，但不会让嵌入式 Agentforce Agent 真正在 Teams 自定义客户端（“Salesforce Employee Assist” / “Ask AI Agent”）中回复。这是 IT Service Agent 设置中最后也是最难的一步，由专门的技能介绍：

→ service-itsm-teams-employee-agent-configure

用户希望 Teams 内的 Agent 回复时，请在步骤 4 后调用该技能（或转交给它）。该技能介绍了经验证的架构——一个启用用户验证 + JWKS_URL 密钥集的 Web 渠道、Teams_AgentForce 部署、将请求路由到真实且处于活动状态的 Agent 的 Omni-Flow 路由流，以及为门户用户设置的 Agent Access 权限集——并提供了常见的“Agent 加入后又离开”问题诊断方法（已启用身份验证但没有密钥集，或缺少 Agent Access）。其中针对每位用户分配 Agent Access，是上述“管理用户访问”步骤（步骤 3）的自然后续操作。

已验证的问题 — UI 在 API 写入后仍显示旧的“无”。 Go 页面中的下拉菜单使用 LDS 缓存读取此组织值；直接执行 Connect PATCH 不会使缓存失效。写入确实成功且已持久化（后续 GET 可确认）——如果 Setup 页面仍处于打开状态，请告知用户对标签页执行强制刷新，以查看新的选择。

名称具有误导性 — 这是跨功能共享设置，并非 Teams 专用。 尽管前缀为 SLACK_（这是该组织值最初用于 Slack-ITSM 时留下的旧名称），它为 Teams ITSM Go 页面和对应的 Slack ITSM Go 页面中的“选择数字体验站点”选择器提供数据——从一个界面写入会改变另一个界面显示的内容。如果用户也配置了 Slack ITSM，请提醒用户，此设置也会更改 Slack 的首选站点。

---

注意事项

问题	详情
需要先启用 Teams Salesforce Go 页面功能	OrgHasEmployeeServiceTeams 不会直接限制或依赖 ITSMTeamsEnabled，但只有启用 service-cloud-itsm-teams-integration 后，Go 页面检查清单才会显示 — 请先运行 service-itsm-teams-configure。
OrgHasEmployeeServiceTeams 不会解除对 ITSMTeamsEnabled 的限制	这是两个独立的设置 — 启用此首选项本身不会解除对 Teams Salesforce Go 页面切换首选项的限制，反之亦然。
“选择 Digital Experience 站点”会写入组织值，而非调用 Teams API	此检查清单项目会通过 PATCH /services/data/v67.0/setup/org/values/SLACK_PREFERRED_SITE 写入组织值 SLACK_PREFERRED_SITE（请求正文 {"orgValue": "<site Id>"}）— 无需 Azure/Entra 凭据，也不需要 Teams 许可证。已在线验证：使用某个站点的 Network Id 执行 PATCH 后成功（200），且不依赖 Teams 设置的其他部分。如果组织没有 Digital Experience 站点，请先通过 experience-portal-create 创建一个。请注意，尽管名称中有 SLACK_，此组织值与 Slack ITSM 集成中对应的选择器共用，并非 Teams 专属。
权限集 / PSL	本次会话中，功能启用后立即自动配置了 TeamsForEmployeeUser（权限集）和 PSL TeamsForEmployeePsl，并确认状态为 Active（10 个许可证）— 只要已获得 TeamsITSrvcsAddOn+IncidentManagementAddOn 许可证，就无需手动创建 PSL/权限集。
必须指定版本前缀	headless-360 dispatch/dispatch_readonly 无法解析 API 版本 — 始终传入完整的 /services/data/vXX.0/... 前缀。
UEL 用户无法在 Teams 中登录 IT Service	仅分配 TeamsForEmployeeUser 并不足够。登录还受另外三项先决条件限制（参见 步骤 3 → 登录先决条件）：登录配置文件中的 Allow OAuth for employees（仅限 Setup UI — Metadata/SObject/Tooling 均没有可用的写入路径；已验证全部失败）、CORS Allowed Origins 中同时包含 https://teams.cloud.microsoft 和 https://cdn.scs.static.lightning.force.com，以及用户的 API Enabled 系统权限。每一项都已确认会单独导致静默登录失败。

---

故障排除：Teams for Employee Service 登录与 Agent

当用户报告 Teams for Employee Service 出现故障（无法登录、弹出“Service Not Available”窗口，或 Agent 不回复）时，请按顺序执行这些检查 — 每一项都是带有精确查询和修复方法的通过/失败检查点。遇到第一项失败时即停止；这些检查按最常见且最易处理到最深入的顺序排列。

如需对所有 Teams ITSM 症状进行更广泛的引导式诊断（IT Desk 登录、功能启用、选项卡加载、服务目录、Agentforce、Swarming、SSO — 不仅限于 IT Service 登录），请使用专用的 service-itsm-teams-debug 技能，它会将报告的问题导向匹配的通过/失败检查清单。以下流程是其中专注于 IT Service 登录的子集。

使用 dispatch_readonly 执行只读检查（需要 Tooling API 的查询会特别注明 Tooling 对象检查）。在检查过程中，将占位符 ID 替换为找到的实际 ID。

A. Community 登录本身

SELECT LoginTime, Status, LoginType FROM LoginHistory
  WHERE UserId='<userId>' ORDER BY LoginTime DESC LIMIT 5

• No community access → 对于内部/UEL 用户，该站点的 Network.OptionsAllowInternalUserLogin 已关闭。请在站点的登录设置中启用“Allow internal users to log in directly”（参见 portal-create 技能中的内部登录标志）。这与下文所述的故障不同 — 如果遇到此问题，请先修复。
• Employee Login to Community = Success → 登录正常；故障发生在后续的 OAuth 或 Agent 运行时环节。继续执行 B。

B. 静默登录的三个前提条件（参见 步骤 3 → 登录前提条件）

1. 在登录配置文件中允许员工使用 OAuth（仅限 Setup UI 的复选框）。没有 API 读取方式 — 请通过下文 C 中的 OAuth 令牌检查（实际症状）进行验证。
2. CORS 允许的来源 — 必须包含以下两个来源：

   SELECT Id, UrlPattern FROM CorsWhitelistEntry
   

   缺少 https://teams.cloud.microsoft 或 https://cdn.scs.static.lightning.force.com → 创建条目（POST /sobjects/CorsWhitelistEntry {"UrlPattern":"<origin>"}），然后强制刷新。
3. 为用户启用系统权限 API Enabled（通过权限集，而非仅通过配置文件）。

C. OAuth 令牌签发 — 判定门户用户问题的关键检查

此检查可区分门户/UEL OAuth 故障与登录故障。用户从一个新 Teams 聊天中重试登录后：

SELECT Id, AppName, UserId, User.Username, CreatedDate FROM OauthToken
  WHERE AppName='ServiceCloudMSTeamsEca'

• 存在失败用户的令牌记录 → OAuth 成功；问题出在 Agent 运行时，而非登录 — 跳转到 E。
• 不存在失败用户的令牌，但社区登录显示 Success（B） → OAuth 授权步骤没有签发令牌。这对应 /<sitePrefix>/setup/secur/RemoteAccessAuthorizationPage 上的“Service Not Available”弹窗。请按 D 处理。

诊断提示（已验证）：如果 Standard 配置文件用户可以签发 ServiceCloudMSTeamsEca 令牌，而 UEL / portal 用户不能 — 即使权限集完全相同 — 则阻碍来自门户用户的 OAuth 授权路径（配置文件中的 OAuth 标志，或在社区主机上提供的自批准页面），而非任何 ECA 权限授权。在已验证的组织中，Standard 用户在没有任何 SetupEntityAccess 记录的情况下签发了令牌，而拥有所有权限的 UEL 用户却无法签发，因此 ECA SetupEntityAccess 配置无法解释这一差异。

D. 门户用户 OAuth 授权（社区主机上的自批准页面）

ServiceCloudMSTeamsEca External Client App 由 Go 页面开关自动安装，无需配置 — 不要更改其 OAuth 策略或添加 SetupEntityAccess 记录。症状：Teams 弹窗标题为 “Service Not Available / An unexpected connection error occurred”，显示在 /<sitePrefix>/setup/secur/RemoteAccessAuthorizationPage，和/或流式端点返回访问检查错误正文 {"acc":8}。

此故障仅出现在门户/UEL 用户中，并非 ECA 权限问题（根据上述诊断提示，Standard 用户在没有任何 SetupEntityAccess 记录的情况下可以签发令牌）。OAuth 授权请求被路由到社区主机（https://<org>.my.site.com/<prefix>/setup/secur/...），而不是 My Domain；社区主机无法呈现自批准页面。ECA 是打包的第一方应用 — 不要手动编辑其 OAuth 策略、callbackUrl、isFirstPartyAppEnabled 或 oauthLink。先确认“允许员工使用 OAuth”（B）和 API Enabled（C）；如果门户令牌仍无法签发，请记录弹窗 URL 和任何 acc 代码，并升级给 Teams ITSM 产品团队 — 这超出了可配置设置修复的范围。

E. 嵌入式 Agentforce Agent 加入后离开（没有回复）

如果登录和 OAuth 均成功，但“Ask AI Agent” Agent 不回复，请转交给 service-itsm-teams-employee-agent-configure — 已验证的两个修复方案是：(1) Teams_AgentForce 通道的用户验证已开启，并由 JWKS_URL Key Set 提供支持；(2) 设置 Agent Access 权限集，为门户用户启用 IT Service Employee Agent。该技能的参考文档包含完整的运行时链路诊断（scrt2 令牌、SSE 401、ConversationEntry 查询）。

---

相关技能

技能	何时单独或配合使用
service-itsm-teams-configure	启用基础 Teams Salesforce Go 页面开关、注册 Azure/Entra 应用、填充 Named Credential，以及注册 Teams 扩展——这是使用本技能的前置条件
service-itsm-teams-itdesk-configure	清单中 IT Desk/服务人员部分（Turn on IT Desk、Install IT Desk app、Manage User Access、Set Teams as Collaboration Tool for Swarming）
service-itsm-teams-employee-agent-configure	IT Service Agent 设置的最后一部分——让嵌入式 Agentforce Agent 真正能在 Teams 自定义客户端中回复（Web 渠道、User Verification ON + JWKS_URL Key Set、Teams_AgentForce 部署、将路由流指向实际启用的 Agent、Agent Access 权限集）。完成第 4 步后转交给此技能。
service-itsm-teams-debug	诊断 Teams ITSM 设置中的各种故障（登录、功能启用、选项卡加载、Agentforce、Swarming、SSO）——将问题导向通过/失败清单，并报告修复方案
service-itsm-channels-coordinate	Teams、Slack、Swarming、Notifications、Portal 的顶层菜单