@salesforce/afv-skills 1.40.0 → 1.41.0

package/skills/service-itsm-teams-configure/SKILL.md

@@ -0,0 +1,395 @@
+---
+name: service-itsm-teams-configure
+description: "Enable Microsoft Teams for Employee Service (ITSM) in Salesforce — the Salesforce Go feature service-cloud-itsm-teams-integration gating Teams-based IT Desk and IT Service collaboration. Use this for: 'enable Teams for employee service', 'turn on ITSM Teams integration', 'enable Microsoft Teams for IT Service', 'set up Salesforce IT Desk Teams app', 'enable ITSMTeamsEnabled', 'why can't I enable the Teams org preference', or any request to enable/verify this Salesforce Go feature. DO NOT TRIGGER for configuring the TeamsNotifications notification-channel preference or for enabling the Swarming feature itself (service-itsm-swarming-configure)."
+metadata:
+  version: "1.0"
+  domains: ["Service"]
+  minApiVersion: "67.0"
+  relatedSkills:
+    - "experience-portal-create"
+    - "service-itsm-channels-coordinate"
+    - "service-itsm-swarming-configure"
+    - "service-itsm-teams-employee-agent-configure"
+    - "service-itsm-teams-itdesk-configure"
+    - "service-itsm-teams-itservice-configure"
+  mcpTools:
+    headless-360:
+      tools: ["describe", "discover", "dispatch", "dispatch_readonly"]
+      semver: ">=1.0.0"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  accessCheck:
+    - type: "orgPerm"
+      value: "MSTeamsSetupAutomationAccess"
+allowed-tools: |
+  Read AskUserQuestion Bash
+  mcp__headless-360__discover
+  mcp__headless-360__describe
+  mcp__headless-360__dispatch
+  mcp__headless-360__dispatch_readonly
+---
+
+# Enable Microsoft Teams for Employee Service (ITSM)
+
+Enable the Salesforce Go feature **"Microsoft Teams for Employee Service"**
+(`service-cloud-itsm-teams-integration`) — the feature that lets IT Desk and IT Service
+agents track tickets, request catalog items, and get Agentforce assistance from inside
+Microsoft Teams. Every operation dispatches through **headless-360**.
+
+> **Execute one step at a time.** These steps make real, state-changing API calls. Run a single
+> operation, show its result, confirm it succeeded, then proceed — do not batch multiple setup
+> calls into one parallel block.
+
+## Scope
+
+- **In scope**: Enabling the `service-cloud-itsm-teams-integration` Go feature via its
+  feature-enablement Connect API; verifying feature and `ITSMTeamsEnabled` preference state
+  afterward; explaining why the direct org-preference PATCH route fails and why this route
+  works instead; disabling the feature if requested; giving the user step-by-step instructions
+  for the Azure/Entra app registration (Step 4a) since no Salesforce API can perform that part;
+  once the user provides the resulting Client ID/Tenant ID (in chat) and the Client Secret (via the
+  `TEAMS_ENTRA_CLIENT_SECRET` env var / secret file, never in chat), writing them
+  directly into the `MSTeamsSetupClientCredentialsEC` Named Credential via API — this
+  Salesforce-side write is always automated by this skill, never deferred back to the user;
+  registering the Experience Cloud site as the Teams "preferred site" extension via
+  `/connect/service-itsm-teams/graph-api/extensions` once that credential exists.
+- **Out of scope**: Notification-channel preferences (`Notifications`, `TeamsNotifications`) —
+  a separate concern from this feature. Enabling the `service-cloud-swarming` Go feature itself —
+  delegate to `service-itsm-swarming-configure`. The IT Desk/fulfiller checklist group (Turn on
+  IT Desk, Install IT Desk app, Manage User Access, Set Teams as Collaboration Tool for
+  Swarming) — delegate to `service-itsm-teams-itdesk-configure`. The IT Service/employee
+  checklist group (Turn on IT Service, Install IT Service app, Manage User Access, Select a
+  Digital Experience Site) — delegate to `service-itsm-teams-itservice-configure`. Portal/site
+  creation — use `experience-portal-create`. The actual Azure-side actions (clicking through the
+  Azure portal, generating the client secret, granting Microsoft admin consent) must be
+  performed by the user in the Microsoft admin center — no Salesforce API reaches Azure/Entra —
+  but this skill still provides the exact instructions for those steps (see Gotchas and Step 4a)
+  rather than treating them as someone else's problem.
+
+---
+
+## The problem this skill solves
+
+`ITSMTeamsEnabled` is the Salesforce Go page toggle preference gating Microsoft Teams ITSM integration. Its
+UDD definition (`ServiceItsmTeams.settings.xml`) declares `orgAccess="always"` but has **no
+`editAccess` attribute** — unlike working preferences such as `Notifications`/`TeamsNotifications`,
+which explicitly set `editAccess="always"`. As a result, the direct Setup preferences Connect
+API route is blocked:
+
+```text
+GET  /services/data/vXX.0/setup/org/preferences/ITSMTeamsEnabled
+PATCH /services/data/vXX.0/setup/org/preferences/ITSMTeamsEnabled  body: {"desiredState": true}
+```
+
+Both return `401`:
+```json
+{"error_code":"API_ERROR","status_code":401,"body":"[{\"errorCode\":\"INSUFFICIENT_ACCESS\",\"message\":\"Cannot read data!\"}]"}
+```
+(`"Cannot update preference value!"` on the PATCH). This is a real, code-level access gate
+(`StandardMetadataChecker` in `setup-connect-impl` relays an Aura `NoAccessException` — "bit(s)
+do not have READ/WRITE access" — for this preference specifically), **not** a version-prefix or
+routing mistake. Do not retry this route with different API versions or bodies.
+
+**The verified working path is different: enable the Go *feature*, not the preference
+directly.** The Salesforce Go feature-enablement Connect API sits behind a different access
+check and, on enable, flips `ITSMTeamsEnabled` (and related feature state) as a side effect.
+
+---
+
+## Workflow
+
+### Step 1 — Check current feature status
+
+```text
+mcp__headless-360__dispatch(
+  method: "POST",
+  url:    "/services/data/v67.0/connect/setup/discovery/features/status",
+  body:   { "featureApiNames": ["service-cloud-itsm-teams-integration"] }
+)
+```
+
+Response shape:
+```json
+{
+  "items": [
+    {
+      "apiName": "service-cloud-itsm-teams-integration",
+      "status": "ENABLED",          // or "NOT_ENABLED" / "DISABLED"
+      "blockedByApexLock": false,
+      "dependencyStatuses": [],
+      "enableBlockedReasons": [],
+      "disableBlockedReasons": []
+    }
+  ]
+}
+```
+
+If `status` is already `"ENABLED"`, skip to Step 3 (verification) — do not re-enable.
+If `enableBlockedReasons` is non-empty, surface those reasons to the user (typically a missing
+license/add-on) before attempting Step 2.
+
+### Step 2 — Enable the feature
+
+```text
+mcp__headless-360__dispatch(
+  method: "POST",
+  url:    "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-teams-integration/enable",
+  body:   {}
+)
+```
+
+**Known gotcha (verified):** this call can return `500 INTERNAL_ERROR` even when the feature
+successfully ends up `ENABLED`. Do not treat a `500` here as a hard failure — always re-run
+Step 1 (`features/status`) and Step 3 (`ITSMTeamsEnabled` read) afterward to check actual state
+before reporting failure to the user. If status still shows `NOT_ENABLED` after retrying once,
+then report the failure with the raw error.
+
+### Step 3 — Verify `ITSMTeamsEnabled` flipped
+
+```text
+mcp__headless-360__dispatch_readonly(
+  method: "GET",
+  url:    "/services/data/v67.0/setup/org/preferences/ITSMTeamsEnabled"
+)
+```
+
+Expect `200 {"isPreferenceEnabled": true}`. This confirms the underlying preference — otherwise
+inaccessible via direct PATCH — is now enabled as a side effect of the feature enable.
+
+### Step 4 — Report *interim* status (setup is NOT complete yet)
+
+Report feature status and whether `ITSMTeamsEnabled` reads `true` — but **frame this as progress,
+not completion.** Enabling the Go feature is only the first half. The integration is **not
+functional** until the Microsoft Entra app is registered, its credentials are written into the
+Named Credential + Auth Provider, and admin consent is granted (Step 4a). Do **not** call this an
+"optional manual tail," do **not** mark Teams "Done"/"configured"/"complete," and do **not** hand
+back to any coordinator as done. State plainly: *"The Salesforce feature is enabled; Teams
+integration is not yet complete — the required Microsoft Entra app registration comes next."* Then
+proceed directly into Step 4a. See the **Completion contract** below for what "complete" requires.
+
+### Step 4a — Follow the Go page's own order: Create Entra app → Configure Named Credentials → Grant consent
+
+The Salesforce Go feature page (Setup → Salesforce Go → this feature,
+`.../lightning/setup/page/feature/service-cloud-itsm-teams-integration/home?topic=SalesforceGo`)
+renders a **"Complete the Required Steps" → "Integrate Salesforce with Teams"** checklist with
+exactly three items, in this order — verified from a live screenshot of the page. Follow this
+order; do not skip ahead to Named Credentials before the Entra app exists, and do not treat
+"Grant Azure Administrator Consent" as optional:
+
+1. **Create Microsoft Entra ID App** ("Set Up Microsoft Entra ID App" button — opens
+   portal.azure.com). There is no Salesforce API for this sub-step; give the user these exact
+   clicks and wait for them to provide the resulting values:
+   - **portal.azure.com** → **Microsoft Entra ID** → **App registrations** → **New registration**.
+     Name it something identifiable (e.g. `Salesforce ITSM Teams Integration`); single-tenant is
+     fine unless the user's org spans multiple tenants; no redirect URI is needed for the
+     client-credentials flow used here.
+   - From the app's **Overview** page, note the **Application (client) ID** and **Directory
+     (tenant) ID**.
+   - **Certificates & secrets** → **New client secret** → copy the secret **value** immediately
+     (unrecoverable after leaving the page).
+   - **API permissions** → **Add a permission** → **Microsoft Graph** → **Application
+     permissions** → add the Graph permissions this integration needs (at minimum
+     `ChannelMessage.Send`, `Team.ReadBasic.All`, `Channel.ReadBasic.All`,
+     `TeamworkAppSettings.ReadWrite.All` — confirm against the org's current Teams for Employee
+     Service documentation, since required scopes can change between releases).
+   - Provide the credentials **without exposing the secret in chat**: the **Client ID** and
+     **Tenant ID** are non-secret identifiers and may be given in the conversation, but the
+     **Client Secret is a confidential credential — NEVER ask for it in chat and never accept it
+     there.** The user places the secret in the `TEAMS_ENTRA_CLIENT_SECRET` environment variable
+     (or a gitignored secret file whose path they give you); you read it from that source at write
+     time and never print, echo, or log its value.
+2. **Configure Setup Named Credentials** ("Go to Setup" button on the Go page — the manual
+   equivalent of what this skill automates). **Once you have the Client ID / Tenant ID and the
+   secret is available in the env var / file, do not tell the user to enter anything into Setup —
+   call the Named Credential APIs directly**, per "Populating `MSTeamsSetupClientCredentialsEC`
+   given a user-supplied client ID/secret" under Step 5 below. **This same set of values must ALSO be written into the
+   `microsoft_auth_provider` Auth Provider** (the inbound-SSO side, distinct from the outbound-Graph
+   Named Credential) — the org provisions this Auth Provider empty. Do this automatically too; see
+   "Populating the `microsoft_auth_provider` Auth Provider" under Step 5. Both artifacts share the
+   same Client ID / Tenant ID / Client Secret and must be populated together — populating only the
+   Named Credential leaves portal SSO login broken.
+3. **Grant Azure Administrator Consent** ("Grant Consent" button on the Go page). Clicking it
+   opens a modal with a one-time consent link to a **fixed Salesforce-owned Entra app**
+   (`client_id=cd6bd63f-41ef-47cc-9465-86e986179a29`, tenant segment `organizations` — not the
+   user's own tenant ID, and not the app created in step 1) requesting the
+   `Organization.ReadWrite.All` delegated scope:
+   ```text
+   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
+   ```
+   This link is static — it does not need to be fetched per-org or per-user, and headless-360 has
+   no operation that generates or dispatches it (it's rendered by an internal Aura controller with
+   no public Connect API mirror). **Paste this exact link and tell the user to click it, signed in
+   as a Microsoft tenant admin, to grant consent** — this action authenticates as the Microsoft
+   admin and cannot be performed by this skill via API.
+
+Everything the user does above (steps 1's Azure clicks and step 3's consent click) is their
+manual responsibility because no Salesforce API reaches Azure/Entra. Everything Salesforce-side —
+writing the supplied credential (secret read from the env var / secret file, never from chat) into
+the Named Credential in step 2 — is this skill's job to automate; that division of labor is the
+entire point of this skill.
+
+### Step 4b — Delegate to the IT Desk / IT Service child skills
+
+Before touching the "Set Up Salesforce IT Desk" / "Set Up Salesforce IT Service" checklist
+groups, ask the user which they want — these are two independent halves of the feature
+(fulfiller side vs. employee side) and a user may only need one:
+
+- **Salesforce IT Desk** — for IT agents/fulfillers to swarm on and resolve tickets from Teams.
+  Invoke `service-itsm-teams-itdesk-configure`.
+- **Salesforce IT Service** — for employees to create and manage their own tickets from Teams.
+  Invoke `service-itsm-teams-itservice-configure`.
+- **Both** — invoke both child skills.
+
+Each child skill handles its own 3-4 item checklist group (Turn on `<app>` → Install `<app>`
+App on Teams → Manage User Access → optional 4th item) end-to-end — do not duplicate that logic
+here.
+
+### Step 4c — Delegate the embedded Agentforce agent (Teams "Ask AI Agent")
+
+If the user wants the embedded Agentforce agent to **reply** inside the Teams custom client
+("Salesforce Employee Assist" → "Ask AI Agent") — i.e. build the `Teams_AgentForce` MIAW
+deployment, its Web channel (**User Verification ON + a `JWKS_URL` Key Set**), the routing flow to the
+IT Service Employee Agent, and the **Agent Access permission set** for the portal user — **invoke
+`service-itsm-teams-employee-agent-configure`.** That is a distinct, large capability with its own
+object model; do not attempt it inline here. It requires the employee portal site
+(`experience-portal-create`) to exist first.
+
+### Step 5 — Register the preferred site (Teams extension), once the Azure credential exists
+
+Once the org has an external credential named `MSTeamsSetupClientCredentialsEC` (see Step 4a and
+"Populating..." below), register the Experience Cloud site that should back the Teams integration:
+
+```text
+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>"] }
+)
+```
+
+Update later with:
+```text
+mcp__headless-360__dispatch(
+  method: "PATCH",
+  url:    "/services/data/v67.0/connect/service-itsm-teams/graph-api/extensions/{extensionId}",
+  body:   { "siteUrlPathPrefixes": ["<updated prefix list>"] }
+)
+```
+
+If this returns `400 UNKNOWN_EXCEPTION "...external credential \"MSTeamsSetupClientCredentialsEC\"
+might not exist"`, the Azure/Entra step (Gotchas) has not been completed yet — this is not a bug
+in the call itself.
+
+If instead it returns `AccessDenied` (or `400 UNKNOWN_EXCEPTION "Exception while creating Teams
+extension: Unable to fetch tenant ID"`) **even after** the external credential shows
+`authenticationStatus: "Configured"`, the cause is almost always the **Azure app's Graph
+permissions being of type _Delegated_ rather than _Application_** (client-credentials token flow
+cannot use delegated-only permissions). This is a **fixable Azure/Entra misconfiguration, not a
+hard license wall** — verified live this session: the same call went from `AccessDenied` to
+`201 Success` (`com_sf_itsm_teams_config`) after two changes on the Azure side, with no license
+change:
+
+1. In the Azure app registration → **API permissions**, ensure the Microsoft Graph permissions are
+   the **Application** type (not Delegated), then click **"Grant admin consent"** for the tenant.
+2. **Repopulate the credential** (see "Populating..." below) — re-provisioning or any feature
+   re-enable can leave the EC/Auth Provider empty; a freshly-populated `MSTeamsSetupClientCredentialsEC`
+   showing `authenticationStatus: "Configured"` is required at the moment of the retry.
+
+Retry Step 5 after both. Only treat this as a genuine org-license blocker (the `MsTeamsAppApiFamily`
+gotcha below) if the call **still** fails once Application-type Graph permissions + admin consent
+are confirmed and the credential is freshly `Configured`.
+
+Once you have the Azure Client ID and Tenant ID (given in chat) and the Client Secret (read from the
+`TEAMS_ENTRA_CLIENT_SECRET` env var / secret file — never requested in chat; Step 4a), do the
+Salesforce-side writes yourself — do not tell the user to enter values in Setup. The full verified
+recipe (populating `MSTeamsSetupClientCredentialsEC`, populating the `microsoft_auth_provider` Auth
+Provider for inbound SSO via the Metadata API, matching the portal user's `Username` to the Microsoft
+UPN so `MsTeamsItsmSSOHandler` resolves them, and granting the portal user `ApiEnabled` for the Teams
+Connect APIs) — with exact API bodies, the AuthProvider MDAPI template, the Web-vs-SPA callback
+constraint, and their gotchas — is in:
+
+**→ `references/azure-credential-population.md`**
+
+---
+
+## Completion contract — do NOT report Teams setup "complete" until all of these hold
+
+The Go-feature enable (Steps 1–3) is necessary but **not sufficient**. The single most common
+failure mode is declaring Teams "configured/done/complete" after Step 3 while the Microsoft Entra
+app is still unregistered — which leaves in-Teams sign-in and the outbound Graph integration
+**broken**. Treat the Entra app registration as a **blocking prerequisite of completion**, never an
+optional tail. Report **complete only when every item below is verified** (not merely instructed):
+
+1. **Feature enabled** — `service-cloud-itsm-teams-integration` reads `ENABLED` and
+   `ITSMTeamsEnabled` reads `true` (Steps 1–3).
+2. **Microsoft Entra app registered** — the user has completed Step 4a's Azure clicks and provided
+   the Client ID and Tenant ID (in chat) with the Client Secret placed in the
+   `TEAMS_ENTRA_CLIENT_SECRET` env var / secret file (never pasted in chat). Until they do, **stop
+   and wait** — this is a hard gate; you cannot proceed past it, and you must not report completion
+   around it.
+3. **Credentials populated (Salesforce-side, automated by this skill)** — `MSTeamsSetupClientCredentialsEC`
+   reads `authenticationStatus: "Configured"` **and** the `microsoft_auth_provider` Auth Provider is
+   populated with the same values (see `references/azure-credential-population.md`). Populating only
+   one leaves either outbound Graph or inbound SSO broken.
+4. **Admin consent granted** — the user has clicked the static consent link in Step 4a item 3,
+   signed in as a Microsoft tenant admin.
+5. **Preferred site registered** — the Teams extension call in Step 5 returns success (or the user
+   has explicitly deferred the employee-site half).
+
+If any of 2–4 is pending, the correct status is **"Blocked on Microsoft-admin action — Teams
+integration incomplete,"** with the exact next step called out. A partial state is **not** a
+success; do not soften it, and do not let a coordinator mark this feature `Done`.
+
+---
+
+## Disabling (if requested)
+
+```text
+mcp__headless-360__dispatch(
+  method: "POST",
+  url:    "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-teams-integration/disable",
+  body:   {}
+)
+```
+
+Re-run Step 1/Step 3 afterward to confirm. Disabling `ITSMTeamsEnabled`'s underlying
+provisioning (SSO handler, named/external credentials, PKCE OAuth client) may not be fully
+reversed by this call alone — verify with the user whether they also need those artifacts
+removed and treat that as a separate, manual Setup exercise.
+
+---
+
+## Related, separately-enabled preferences
+
+Two sibling org preferences drive the "Fulfiller Hub" and "Employee Hub" halves of this feature
+and, unlike `ITSMTeamsEnabled`, **are** directly writable via the standard Setup preferences
+Connect API — `GET/PATCH /services/data/v67.0/setup/org/preferences/OrgHasITSMFulfillerTeams`
+("Enable Salesforce IT Desk") and `.../OrgHasEmployeeServiceTeams` ("Enable Salesforce IT
+Service"). Both take `{"desiredState": true}` and return `{"isPreferenceEnabled": true}`. They are
+independent bits — enabling them does **not** unblock `ITSMTeamsEnabled`; enable them alongside,
+not instead of, the Step 2 feature-enable call if the user wants both Hubs.
+
+---
+
+## Gotchas
+
+The verified, load-bearing pitfalls (direct-PATCH 401, empty Auth Provider, Azure Web-vs-SPA
+redirect, Username=UPN handler, portal API-Enabled, static consent link, `MsTeamsAppApiFamily`
+403 hard gate, version-prefix requirement, and more) are catalogued in
+[`references/gotchas.md`](references/gotchas.md). Read it before reporting a step as failed or
+retrying an enablement guess.
+
+---
+
+## Related Skills
+
+| Skill | When to use instead |
+|-------|---------------------|
+| `service-itsm-teams-itdesk-configure` | The "Set Up Salesforce IT Desk" checklist group (fulfiller side) — this skill delegates to it (see Step 4b) |
+| `service-itsm-teams-itservice-configure` | The "Set Up Salesforce IT Service" checklist group (employee side) — this skill delegates to it (see Step 4b) |
+| `service-itsm-teams-employee-agent-configure` | Making the embedded Agentforce agent reply in the Teams "Ask AI Agent" custom client (`Teams_AgentForce` MIAW deployment) — this skill delegates to it (see Step 4c) |
+| `service-itsm-swarming-configure` | Enabling the `service-cloud-swarming` Go feature for "Set Teams as Collaboration Tool for Swarming" — invoked by `service-itsm-teams-itdesk-configure`, not by this skill directly |
+| Notification-channel preferences | Enabling the `Notifications`/`TeamsNotifications` preferences is a distinct concern from this feature (no dedicated child skill exists yet) |
+| `experience-portal-create` | Creating the employee-service portal/site itself |
+| `service-itsm-channels-coordinate` | Top-level menu across Teams, Slack, Swarming, Notifications, Portal |

package/skills/service-itsm-teams-configure/references/azure-credential-population.md

@@ -0,0 +1,213 @@
+# Populating the Azure credentials, inbound SSO, and portal-user access (Step 5 detail)
+
+Reference for `service-itsm-teams-configure` Step 5. Once the org has an external credential named
+`MSTeamsSetupClientCredentialsEC` and the user has supplied their Azure **Client ID** and **Tenant
+ID** (non-secret identifiers, given in chat) and placed the **Client Secret** in the
+`TEAMS_ENTRA_CLIENT_SECRET` environment variable or a gitignored secret file (Step 4a — **never ask
+for the secret in chat**), these are the Salesforce-side writes that populate the outbound Graph
+credential, the inbound-SSO Auth Provider, and the portal-user access that make the Teams IT Service
+/ IT Desk apps actually work. Read the secret from that env var / file at write time; never print,
+echo, or log its value, and never send the literal `$TEAMS_ENTRA_CLIENT_SECRET` token to an API —
+always resolve it to its actual value first (see the Secret-substitution note in Step 2). Do all of
+these yourself — the user's manual responsibility ends at the Azure admin center.
+
+## Populating `MSTeamsSetupClientCredentialsEC` given a user-supplied client ID/secret
+
+**Once the user supplies the Client ID and Tenant ID (in chat) and the Client Secret is available in
+the `TEAMS_ENTRA_CLIENT_SECRET` env var / secret file (Step 4a — never in chat), write them into
+Salesforce yourself via the calls below. Do not respond by telling the user to open Setup and enter
+the values manually — that defeats the purpose of this skill.** The user's manual responsibility
+ends at the Azure admin center (Step 4a); every Salesforce-side write, including this one, is this
+skill's job.
+
+1. Fix the `AuthProviderUrl` parameter (it ships with a literal `{tenant_id}` placeholder):
+   ```text
+   mcp__headless-360__dispatch(
+     method: "PUT",
+     url:    "/services/data/v67.0/named-credentials/external-credentials/MSTeamsSetupClientCredentialsEC",
+     body:   { /* GET the record first, then re-PUT its full parameters[]/principals[] with
+                  AuthProviderUrl set to https://login.microsoftonline.com/<tenant id>/oauth2/v2.0/token */ }
+   )
+   ```
+   This endpoint is full-replace — GET the EC first and mutate, don't send a partial body.
+2. Set the principal's client ID + secret (both required together in one call; there is no
+   partial-update path for just the client ID):
+   **Secret substitution — read this first.** `mcp__headless-360__dispatch` is a JSON API call, **not
+   a shell**: it does **not** expand `$TEAMS_ENTRA_CLIENT_SECRET`. Passing the literal string
+   `"$TEAMS_ENTRA_CLIENT_SECRET"` in the body stores that literal text as the OAuth client secret and
+   Graph authentication then fails after an apparently-successful configuration. You must resolve the
+   env var to its **actual value** and place that value into `clientSecret.value` at call time. Read it
+   with a **non-logging** read (e.g. a single `printenv TEAMS_ENTRA_CLIENT_SECRET` captured into an
+   in-memory variable, or read the secret file) — never `echo`/print it, never place the resolved
+   secret in any text you emit to the user or into a log, and never write it to disk. The `<secret
+   value read from $TEAMS_ENTRA_CLIENT_SECRET>` placeholder below denotes that resolved value, not a
+   literal to send:
+   ```text
+   mcp__headless-360__dispatch(
+     method: "POST",   // or PUT (update-credential) if credentials already exist for this principal
+     url:    "/services/data/v67.0/named-credentials/credential",
+     body:   {
+       "externalCredential": "MSTeamsSetupClientCredentialsEC",
+       "principalName": "NamedAuthPrincipal",
+       "principalType": "NamedPrincipal",
+       "authenticationProtocol": "OAuth",
+       "authenticationProtocolVariant": "ClientCredentialsClientSecretBasic",
+       // clientSecret.value MUST be the resolved secret read from the TEAMS_ENTRA_CLIENT_SECRET env
+       // var / secret file — NOT the literal "$TEAMS_ENTRA_CLIENT_SECRET" token (dispatch does not
+       // expand shell variables). Resolve in memory via a non-logging read; never echo it.
+       "credentials": { "clientId": {"value": "<client id>"}, "clientSecret": {"value": "<secret value read from $TEAMS_ENTRA_CLIENT_SECRET>"} }
+     }
+   )
+   ```
+3. Verify: `GET /services/data/v67.0/named-credentials/external-credentials/MSTeamsSetupClientCredentialsEC`
+   should show `authenticationStatus: "Configured"`.
+4. If `MSTeamsSetupAutomationAccess` (the EC principal's access-gating permission set) is
+   unassigned for the running user, assign it via `POST /services/data/v67.0/sobjects/PermissionSetAssignment`
+   (`AssigneeId`, `PermissionSetId`) before retrying Step 5 — it auto-provisions but is not
+   auto-assigned.
+
+## Populating the `microsoft_auth_provider` Auth Provider (inbound SSO — do NOT skip)
+
+Enabling the Teams feature also provisions a Microsoft-type **Auth Provider** named
+`microsoft_auth_provider` (Setup → Identity → Auth Providers), left **empty** (no Consumer Key,
+Consumer Secret, or endpoint URLs). This is the **inbound SSO** side — it authenticates employees
+logging into the Experience Cloud portal that the Teams IT Service app embeds. It is a *separate
+artifact* from the outbound-Graph `MSTeamsSetupClientCredentialsEC` Named Credential, but takes the
+**same three values** the user supplied (secret from the env var / file, never chat). Populate it automatically in the same pass — a previous run
+of this skill forgot this step, leaving portal SSO login broken even though the Named Credential
+was configured.
+
+**Key constraint (verified):** `AuthProvider.ConsumerSecret` is `createable` but **NOT
+`updateable`** on the SObject — so `sf data update` / a Connect PATCH **cannot** set the secret on
+the already-provisioned (empty) record, and headless-360 `discover` exposes **no** Connect route
+that writes an Auth Provider secret. The working path is the **Metadata API**: `AuthProvider` is a
+full MDAPI type whose `<consumerSecret>` round-trips on deploy. Author a source-format file and
+deploy it (this sets every field, including the secret, with no UI):
+
+```xml
+<!-- force-app/main/default/authproviders/microsoft_auth_provider.authprovider-meta.xml -->
+<?xml version="1.0" encoding="UTF-8"?>
+<AuthProvider xmlns="http://soap.sforce.com/2006/04/metadata">
+    <authorizeUrl>https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/authorize</authorizeUrl>
+    <consumerKey><CLIENT_ID></consumerKey>
+    <consumerSecret>${TEAMS_ENTRA_CLIENT_SECRET}</consumerSecret>
+    <defaultScopes>openid profile email offline_access https://graph.microsoft.com/.default</defaultScopes>
+    <friendlyName>microsoft_auth_provider</friendlyName>
+    <includeOrgIdInIdentifier>false</includeOrgIdInIdentifier>
+    <providerType>Microsoft</providerType>
+    <sendAccessTokenInHeader>true</sendAccessTokenInHeader>
+    <sendClientCredentialsInHeader>false</sendClientCredentialsInHeader>
+    <tokenUrl>https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token</tokenUrl>
+</AuthProvider>
+```
+
+```bash
+sf project deploy start --source-dir force-app --target-org <org-alias>
+```
+
+**Secret handling:** substitute `<TENANT_ID>` / `<CLIENT_ID>` (non-secret) directly, but inject the
+`<consumerSecret>` value from `$TEAMS_ENTRA_CLIENT_SECRET` at build time (e.g. `envsubst` into a
+gitignored temp copy under a scratch dir, deploy that, then delete it). **Never commit the populated
+file** and never echo the secret. The secret comes from the env var / secret file — not from chat.
+
+Notes:
+- Use the **tenant-specific** `/…/<TENANT_ID>/oauth2/v2.0/…` endpoints, not `/common/` or
+  `/organizations/` — single-tenant Azure apps reject the generic endpoints.
+- `--metadata-dir` (MDAPI format) proved flaky here ("named in package.xml but not found in zipped
+  directory"); the **source-format `--source-dir` deploy is the reliable route** — include a minimal
+  `sfdx-project.json` with `sourceApiVersion`.
+- `<executionUser>` is optional for a Microsoft SSO Auth Provider (only needed when a registration
+  handler runs Apex); it may not bind on deploy and that is fine.
+- **Verify** with `sf data query "SELECT ConsumerKey, AuthorizeUrl, TokenUrl, DefaultScopes FROM
+  AuthProvider WHERE DeveloperName = 'microsoft_auth_provider'"`. The **Consumer Secret is
+  write-only and will not read back** — a null secret in the query is expected, not a failure;
+  confirm the ConsumerKey and URLs populated.
+- **After populating, give the user the Auth Provider's Callback URL to register in Azure.** (The
+  callback URL is not a secret.) The redirect URI the Azure app must trust is the OAuth callback endpoint on the org's My
+  Domain: `https://<my-domain>/services/authcallback/microsoft_auth_provider` (get `<my-domain>` from
+  `sf org display --json` → `instanceUrl`, or read the "OAuth-Only Initialization URL" from the Auth
+  Provider's Salesforce Configuration section in Setup). This is a **manual Azure step** — no
+  Salesforce API reaches Azure — so paste the exact URL and tell the user: **portal.azure.com → the
+  app registration → Authentication → add a platform → *Web* → add this Redirect URI → Save.**
+- **Register the redirect URI under the "Web" platform, NOT "Single-page application" (SPA) — verified.**
+  This Auth Provider is a **confidential client**: it does a server-side token exchange using the
+  ConsumerSecret. Azure rejects secret-based token requests against a redirect URI registered as SPA,
+  so if the callback is added under the SPA platform the login *appears* to start (Salesforce even logs
+  a `LoginHistory` "Success" and mints `OauthToken` rows) but the callback round-trip fails at
+  `.../services/authcallback/microsoft_auth_provider` with **`OAUTH_APPROVAL_ERROR_GENERIC`**. Moving
+  the same redirect URI from the SPA platform to the Web platform in the Azure app fixes it. When you
+  emit the callback URL, explicitly tell the user it must go under **Web**, not SPA.
+- Optionally also give the Single Logout URL (`https://<my-domain>/services/auth/rp/oidc/logout`) for
+  the app's Front-channel logout URL. Without the redirect URI registered on the Azure side, portal SSO
+  login fails with a redirect-mismatch error even though the Auth Provider is fully populated.
+
+## Making a portal user resolvable to the signed-in Microsoft user (Username = MS email — verified)
+
+Populating the Auth Provider and its callback is not enough for a person to actually log into the
+embedded Experience Cloud portal from the Teams IT Service (Employee) or IT Desk app. When a user
+signs in through Microsoft, a custom Apex registration handler bound to `microsoft_auth_provider` —
+**`MsTeamsItsmSSOHandler`** (Core module `service-itsm-teams-impl`) — resolves *which* Salesforce user
+they are. Its logic (verified against Core source):
+
+```apex
+global boolean canCreateUser(Auth.UserData data) { return false; }        // no JIT
+global User createUser(Id portalId, Auth.UserData data) {
+    String loginValue = data.email;                                       // the Microsoft email/UPN claim
+    List<User> users = [SELECT Id FROM User WHERE Username = :loginValue LIMIT 2];
+    if (users.isEmpty() || users.size() > 1) return null;                 // 0 or >1 match → no login
+    return users[0];
+}
+```
+
+So the **Microsoft `email`/UPN claim must exactly equal a Salesforce `User.Username`** — not
+`User.Email`, not `FederationIdentifier`. Exactly one active user must match; zero matches or a
+duplicate both return `null`, and the app then shows **"you don't have access to the Microsoft account
+in Salesforce."** There is **one handler / one Microsoft Auth Provider for the whole module** — both
+the IT Service (Employee) and IT Desk (Fulfiller) apps use it; the Employee-vs-Fulfiller split lives
+only in notification/adaptive-card routing, never in user resolution.
+
+**Do this automatically** (this is a Salesforce-side write — do not defer it to the user): once you
+know the Microsoft UPN the person signs in with, ensure the intended portal user's `Username` equals
+it. First confirm no other user already holds that Username (a duplicate breaks the match too), then
+set it via `PATCH /services/data/v67.0/sobjects/User/<userId>` body `{"Username": "<ms-upn>"}`. In this
+session the empPortal user's Username was renamed to the tenant UPN (e.g. `admin@<tenant>.onmicrosoft.com`)
+and login then resolved. Note UEL "Unified Employee" users are `UserType=Standard` internal users added
+directly as Experience Cloud `NetworkMember`s (ContactId can be null) — they are **not** external
+CspLitePortal users; the Username-match rule is the same regardless.
+
+## Granting the portal user API Enabled for the Teams Connect APIs (verified)
+
+Even with SSO resolving correctly, the Teams IT Service (Employee) app calls Connect (Chatter) APIs
+on the embedded portal — e.g.
+`/empPortal/services/data/v66.0/connect/it-service/permissions/EmployeeApp?networkId=<networkId>`.
+If the signed-in user lacks the **API Enabled** user permission, these calls fail with
+**`API_DISABLED_FOR_ORG`** ("...or user type") and the browser Network tab shows **403 Forbidden** —
+the app UI then fails to load its data even though login itself succeeded.
+
+The managed permission sets the child skills assign (`TeamsForEmployeeUser`, `EmployeeHubEmployeeUser`)
+do **not** grant `ApiEnabled`, and being managed-package permission sets they **cannot be edited** — a
+Metadata API retrieve reports "cannot be found" and a direct SObject PATCH fails with "invalid record
+id." The working fix is to **create a new *unmanaged* permission set with `ApiEnabled` only, deploy it,
+and assign it** to the portal user. Do this yourself (Salesforce-side write):
+
+```xml
+<!-- force-app/main/default/permissionsets/Teams_Employee_ApiAccess.permissionset-meta.xml -->
+<?xml version="1.0" encoding="UTF-8"?>
+<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>Teams Employee API Access</label>
+    <description>Grants API Enabled to Unified Employee users so the MS Teams IT Service/Employee app can call Connect APIs. Added during ITSM Teams setup.</description>
+    <hasActivationRequired>false</hasActivationRequired>
+    <userPermissions><enabled>true</enabled><name>ApiEnabled</name></userPermissions>
+</PermissionSet>
+```
+
+```bash
+sf project deploy start --source-dir force-app --target-org <org-alias>
+```
+
+Then assign it: `POST /services/data/v67.0/sobjects/PermissionSetAssignment` with `AssigneeId` (the
+portal user) and `PermissionSetId` (the new set). **Grant `ApiEnabled` only — do NOT also add
+`ChatterInternalUser`:** the Unified Employee license permits `ApiEnabled` but forbids
+`ChatterInternalUser`, and including it makes the whole assignment fail with "user license doesn't allow
+the permission: ChatterInternalUser." Verify with a query on `PermissionSet` /
+`PermissionSetAssignment` (`PermissionsApiEnabled = true`).

package/skills/service-itsm-teams-configure/references/gotchas.md

@@ -0,0 +1,23 @@
+# Gotchas — Microsoft Teams for Employee Service (ITSM) feature enablement
+
+Verified, load-bearing pitfalls encountered enabling the Teams ITSM feature and wiring the
+Azure/Entra app, Named Credential, Auth Provider, and portal user. Read these before reporting a
+step as failed or retrying an enablement guess.
+
+| Issue | Detail |
+|-------|--------|
+| Direct `PATCH /setup/org/preferences/ITSMTeamsEnabled` | Always `401 INSUFFICIENT_ACCESS`. Do not retry this route — use the feature-enable API instead. |
+| `/enable` call returns `500 INTERNAL_ERROR` | Can still succeed. Always re-check `features/status` and the preference read before concluding failure. |
+| `OrgHasITSMFulfillerTeams` / `OrgHasEmployeeServiceTeams` do not gate `ITSMTeamsEnabled` | These are separate Hub-visibility bits; enabling them does not itself unblock the Teams Salesforce Go page toggle preference. |
+| `microsoft_auth_provider` Auth Provider must be populated too (easy to forget) | Enabling the feature provisions an **empty** Microsoft Auth Provider (`microsoft_auth_provider`) for inbound portal SSO — separate from the `MSTeamsSetupClientCredentialsEC` Named Credential but needing the **same** Client ID/Tenant ID/Client Secret. `AuthProvider.ConsumerSecret` is **not `updateable`** (so `sf data update`/Connect PATCH can't set it) and no headless-360 route writes it — populate via **Metadata API source-format deploy** (`sf project deploy start --source-dir`, `<consumerSecret>` round-trips). See "Populating the `microsoft_auth_provider` Auth Provider" under Step 5. Skipping this leaves portal login broken even with the Named Credential configured. |
+| Azure redirect URI must be under the **Web** platform, not SPA | The `microsoft_auth_provider` Auth Provider is a **confidential client** (server-side token exchange using the ConsumerSecret). Azure rejects secret-based token requests against a redirect URI registered as **Single-page application (SPA)**. Symptom: login *appears* to start (Salesforce logs `LoginHistory` "Success" and mints `OauthToken` rows) but the callback fails at `.../services/authcallback/microsoft_auth_provider` with **`OAUTH_APPROVAL_ERROR_GENERIC`**. Fix (verified): register the callback URI under the Azure app's **Web** platform, not SPA. When emitting the callback URL to the user, always say **Web**. See the callback-URL note under "Populating the `microsoft_auth_provider` Auth Provider." |
+| Portal login "you don't have access to the Microsoft account in Salesforce" → Username must equal the MS email/UPN | A custom Apex registration handler **`MsTeamsItsmSSOHandler`** (Core `service-itsm-teams-impl`, bound to `microsoft_auth_provider`) resolves the signed-in Microsoft user by `SELECT Id FROM User WHERE Username = :data.email` — the **Microsoft `email`/UPN claim must exactly equal a Salesforce `User.Username`** (not `User.Email`, not `FederationIdentifier`); `canCreateUser` returns false (no JIT), and 0 or >1 matches both return null → login denied. **One handler serves BOTH the IT Service (Employee) and IT Desk (Fulfiller) apps.** Fix (verified): set the intended portal user's `Username` to the MS UPN (after confirming no duplicate) via `PATCH .../sobjects/User/<id>` `{"Username":"<ms-upn>"}`. See "Making a portal user resolvable..." under Step 5. |
+| Portal Connect API `API_DISABLED_FOR_ORG` / 403 → user needs API Enabled | The Teams IT Service (Employee) app calls Connect APIs on the embedded portal (e.g. `/connect/it-service/permissions/EmployeeApp`); without the **API Enabled** user permission these return `API_DISABLED_FOR_ORG` (403 in the Network tab) and the app fails to load data despite a successful login. The managed permission sets (`TeamsForEmployeeUser`, `EmployeeHubEmployeeUser`) don't grant `ApiEnabled` and **can't be edited** (managed-package: MDAPI retrieve "cannot be found", SObject PATCH "invalid record id"). Fix (verified): create + deploy a new **unmanaged** permission set with `ApiEnabled` only and assign it. **Do not add `ChatterInternalUser`** — the Unified Employee license forbids it (assignment fails "user license doesn't allow the permission: ChatterInternalUser"). See "Granting the portal user API Enabled..." under Step 5. |
+| Azure/Entra app registration + admin consent have no Salesforce API | Salesforce only exposes a consent URL via an internal Aura controller (no public REST contract) — the user must click through the Azure admin center themselves. Give them the exact steps in Step 4a rather than a vague pointer, and once they provide the Client ID/Tenant ID (in chat) with the Client Secret in the `TEAMS_ENTRA_CLIENT_SECRET` env var / secret file (**never request the secret in chat**), take over immediately and write the credential into Salesforce yourself (see "Populating `MSTeamsSetupClientCredentialsEC`..." under Step 5) — do not tell them to enter it manually in Setup. |
+| Go page's real checklist order (verified from a live screenshot) | The "Integrate Salesforce with Teams" group on the feature's Go page has exactly 3 items, in this order: **Create Microsoft Entra ID App** → **Configure Setup Named Credentials** → **Grant Azure Administrator Consent**. This is a *separate* checklist group from "Set Up Salesforce IT Desk" / "Set Up Salesforce IT Service" (delegated to `service-itsm-teams-itdesk-configure` / `service-itsm-teams-itservice-configure`) — do not conflate the groups when reporting progress to the user. |
+| "Grant Azure Administrator Consent" consent link is static, not per-org | Clicking "Grant Consent" on the Go page opens a modal with this exact link: `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`. The `client_id` here is Salesforce's own multi-tenant Entra app (**not** the app the user registers in step 1, and **not** related to the Client ID/Secret that go into the Named Credential) — it requests `Organization.ReadWrite.All` from whichever Microsoft tenant the signed-in admin belongs to (`organizations` tenant segment, not a specific tenant ID). headless-360 has no operation that generates this link or reads the Go page's live checklist state (searched `discover` for "grant Azure administrator consent generate consent URL" and "guided setup checklist progress Salesforce Go" — no matching SOR) — paste the link above verbatim and tell the user to click it themselves, signed in as a Microsoft tenant admin. |
+| `preferredSite` / Teams extension registration **is** a public Connect API (verified) — corrects an earlier assumption | `POST /services/data/v67.0/connect/service-itsm-teams/graph-api/extensions` body `{"siteUrlPathPrefixes": ["<site urlPathPrefix>"]}` registers the Experience Cloud site as the Teams extension target; `PATCH .../extensions/{extensionId}` updates it. Verified live: it dispatches and reaches real logic (not a stub) — it fails with `400 UNKNOWN_EXCEPTION "We couldn't access the credential(s)... external credential \"MSTeamsSetupClientCredentialsEC\" might not exist"` until the Azure/Entra app registration is done and that named/external credential is wired up in Setup. Once the credential exists, call this to complete preferred-site selection — do not treat it as Aura-only. |
+| `service-itsm-teams-connect-api` SOR (headless-360 `discover`) | Also exposes `get-teams-get-teams-list`, `get-teams-get-channel-list`, `post-teams-channel-message-send`, `get-teams-get-permissions`, `get-service-itsm-teams-collaboration-app-settings` (valid `targetApplication` values are `TeamsFulfillerApp` / `TeamsEmployeeApp`, not `teams`) — useful for verifying end-to-end Teams connectivity after the manual tail is complete. |
+| `ms-teams-app-connect-api` (`/connect/ms-teams-app/tenant-config`) gates Step 5 and has **no known unlock path** | `GET`/`PUT`/`DELETE` all return `403 FUNCTIONALITY_NOT_ENABLED [MsTeamsAppApiFamily]`, even after `service-cloud-itsm-teams-integration` is enabled and `MSTeamsSetupClientCredentialsEC` is fully configured. **Verified this is the same blocker as Step 5's "Unable to fetch tenant ID" error** — `post-teams-extension`/`patch-teams-extension-update` internally depend on this tenant-config lookup. Checked and ruled out: (a) no Go feature-enablement API name unlocks it — tried `ms-teams-app`, `ms-teams-app-integration`, `microsoft-teams-app-integration`, `teams-app-connect-api`, `msteams-app-api`, `service-cloud-ms-teams-app-api`, `MsTeamsAppApiFamily` itself, all `400 NOT_FOUND "Could not find the requested feature"`; (b) no `PermissionSetLicense` among all 112 in the org grants it — only `TeamsForEmployeePsl`/`TeamsForITSrvcsPsl` relate to Teams, and neither gates this family. This appears to be a hard org/edition-level license gate with no self-service unlock via headless-360 — if a user hits this, Step 5 cannot be completed in this org; do not keep retrying enablement guesses. |
+| A `MSTeamsSetupAutomationAccess` ("Automate Microsoft Teams Setup") permission set also auto-provisions | Was unassigned in this session — assign it to the Setup admin driving this flow if further automation steps need it. (The IT Desk/IT Service checklist permission sets — `TeamsForITSrvcsUser`, `TeamsForEmployeeUser`, `MicrosoftGraphAccess` — are documented in the child skills.) |
+| Version prefix required | headless-360 `dispatch`/`dispatch_readonly` do not resolve API versions — always pass the full `/services/data/vXX.0/...` prefix. |