service-cloud-itsm-teams-integration

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.

• 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.

.../lightning/setup/page/feature/service-cloud-itsm-teams-integration/home?topic=SalesforceGo

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.

• 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.

<app>

<app>

MSTeamsSetupClientCredentialsEC

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"

AccessDenied

400 UNKNOWN_EXCEPTION "Exception while creating Teams extension: Unable to fetch tenant ID"

authenticationStatus: "Configured"

AccessDenied

201 Success

com_sf_itsm_teams_config

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.

MsTeamsAppApiFamily

Configured

TEAMS_ENTRA_CLIENT_SECRET

MSTeamsSetupClientCredentialsEC

microsoft_auth_provider

Username

MsTeamsItsmSSOHandler

ApiEnabled

references/azure-credential-population.md

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).

Done