service-itsm-teams-configure

Employee Service（ITSM）向け Microsoft Teams を有効にする

Salesforce Go の機能 「Microsoft Teams for Employee Service」 （service-cloud-itsm-teams-integration）を有効にします。この機能を使うと、IT デスクおよび IT サービスの エージェントは Microsoft Teams 内からチケットを追跡し、カタログ項目をリクエストして、Agentforce の支援を受けられます。すべての操作は headless-360 を介して実行されます。

手順は一度に 1 つずつ実行してください。 これらの手順では、実際に状態を変更する API 呼び出しを行います。操作を 1 つ実行し、その結果を表示して成功を確認してから次に進んでください。複数のセットアップ呼び出しを 1 つの並列ブロックにまとめないでください。

対象範囲

• 対象範囲内：機能有効化 Connect API を使って service-cloud-itsm-teams-integration Go 機能を有効にすること、その後に機能と ITSMTeamsEnabled 設定の状態を検証すること、組織設定への直接の PATCH 経由が失敗する理由とこの経由なら機能する理由を説明すること、依頼に応じて機能を無効にすること、Salesforce API では実行できないため Azure／Entra アプリ登録（ステップ 4a）の手順をユーザーに順を追って案内すること、ユーザーから結果の Client ID／Tenant ID を（チャットで）受け取り、Client Secret をステップ 4a のコピー＆ペーストコマンドを使って gitignore 対象のシークレットファイルに書き込んでもらった後（チャットでは絶対に送らないこと）、それらを API 経由で MSTeamsSetupClientCredentialsEC Named Credential に直接書き込むこと。この Salesforce 側の書き込みは、このスキルが常に自動で行い、ユーザーに差し戻しません。この認証情報が存在するようになったら、/connect/service-itsm-teams/graph-api/extensions 経由で Experience Cloud サイトを Teams の「優先サイト」拡張機能として登録すること。
• 対象範囲外：通知チャネルの設定（Notifications、TeamsNotifications）—この機能とは別の事項です。service-cloud-swarming Go 機能自体の有効化—service-itsm-swarming-configure に委任してください。IT デスク／フルフィラーのチェックリストグループ（IT デスクを有効にする、IT デスクアプリをインストールする、ユーザーアクセスを管理する、Swarming のコラボレーションツールとして Teams を設定する）—service-itsm-teams-itdesk-configure に委任してください。IT サービス／従業員のチェックリストグループ（IT サービスを有効にする、IT サービスアプリをインストールする、ユーザーアクセスを管理する、デジタルエクスペリエンスサイトを選択する）—service-itsm-teams-itservice-configure に委任してください。ポータル／サイトの作成—experience-portal-create を使用してください。Azure 側での実作業（Azure ポータルでの操作、クライアントシークレットの生成、Microsoft 管理者の同意の付与）はユーザーが Microsoft 管理センターで実行する必要があります。Salesforce API から Azure／Entra にアクセスすることはできません。ただし、このスキルはそれらを他者任せにするのではなく、該当する手順（「注意点」とステップ 4a を参照）を正確に案内します。

---

このスキルが解決する問題

ITSMTeamsEnabled は、Microsoft Teams ITSM 統合を制御する Salesforce Go ページの切り替え設定です。その UDD 定義（ServiceItsmTeams.settings.xml）では orgAccess="always" が宣言されていますが、editAccess 属性がありません。これは、editAccess="always" が明示的に設定されている Notifications／TeamsNotifications などの正常に機能する設定とは異なります。そのため、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（および関連する機能状態）を切り替えます。

---

ワークフロー

Step 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" の場合は、Step 3（検証）に進みます。再度有効化しないでください。 enableBlockedReasons が空でない場合は、Step 2 を試みる前に、その理由（通常はライセンスまたはアドオンの不足）をユーザーに伝えてください。

Step 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 を致命的な失敗として扱わないでください。実際の状態を確認してからユーザーに失敗を報告するため、必ずその後に Step 1（features/status）と Step 3（ITSMTeamsEnabled の読み取り）を再実行してください。一度再試行してもステータスが NOT_ENABLED のままの場合に限り、エラーの生データを添えて失敗を報告してください。

Step 3 — ITSMTeamsEnabled が切り替わったことを確認する

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

200 {"isPreferenceEnabled": true} が返ることを確認してください。これにより、直接の PATCH ではアクセスできない基盤となる設定が、機能の有効化に伴って有効になったことを確認できます。

Step 4 — 途中経過 のステータスを報告する（設定はまだ完了していません）

機能のステータスと、ITSMTeamsEnabled の読み取り結果が true かどうかを報告します。ただし、完了ではなく進捗として伝えてください。 Go 機能の有効化は最初の半分にすぎません。Microsoft Entra アプリが登録され、その認証情報が Named Credential と Auth Provider に書き込まれ、管理者の同意が付与されるまでは（Step 4a）、統合は機能しません。Teams を「完了」とマークしたり、完了したものとしてコーディネーターに引き継いだりしないでください。次のように明確に伝えてください。「Salesforce の機能は有効になりましたが、Teams との統合はまだ完了していません。次に Microsoft Entra アプリを登録します。」 その後、Step 4a に進んでください。「完了」に必要な条件については、以下の完了条件を参照してください。

Step 4a — Go ページに記載された順序で進める：Entra アプリの作成 → Named Credentials の設定 → 同意の付与

Salesforce Go の機能ページ（設定 → Salesforce Go → この機能、 .../lightning/setup/page/feature/service-cloud-itsm-teams-integration/home?topic=SalesforceGo）には、スクリーンショットで確認したとおり、**「必要な手順を完了」→「Salesforce を Teams と統合」**というチェックリストがこの順序で表示され、項目はちょうど 3 つです。この順序に従ってください。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 は機密情報ではないため、会話内で共有してもかまいません。クライアント シークレットは機密情報です — チャットで尋ねることは絶対にしないでください。 ユーザーに gitignore 対象のファイル に書き込んでもらいます。<secret-file> をジョブ／一時パスに置き換え（例：$CLAUDE_JOB_DIR/tmp/teams-secret）、Claude Code のプロンプトにコピー＆ペーストするよう、次の内容をそのまま渡します（引用符の間には Secret ID ではなく Secret の値を入れます）。

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

     先頭の ! はそのままにしてください — このセッションの Bash で行が実行されるため、ファイルが保持されます。written と表示されたら、書き込み時（手順 5）に <secret-file> から読み取り、表示したりログに記録したりしないでください。

     注： ! で始まる行はチャットの記録に表示されます — そこにシークレットが現れた場合は、漏えいしたものとして扱い、セットアップが完了した後に Azure でローテーションするようユーザーに伝えてください。

2. セットアップの名前付き認証情報を構成（Go ページの「設定に移動」ボタン — このスキルが自動化する処理を手動で行う方法です）。クライアント ID／テナント ID を受け取り、シークレットファイルからシークレットを利用できるようになったら、ユーザーにセットアップ画面で何かを入力するよう指示せず、手順 5 の「ユーザーから提供されたクライアント ID／シークレットを使用して MSTeamsSetupClientCredentialsEC に値を設定する」に従って、Named Credential API を直接呼び出します。この同じ値を microsoft_auth_provider Auth Provider にも書き込む必要があります（アウトバウンド Graph Named Credential とは別の、インバウンド SSO 側です） — 組織ではこの Auth Provider が空の状態でプロビジョニングされています。これも自動的に行います。手順 5 の「microsoft_auth_provider Auth Provider に値を設定する」を参照してください。両方のアーティファクトで同じクライアント ID／テナント ID／クライアント シークレットを共有しており、両方を一緒に設定する必要があります — Named Credential だけを設定すると、ポータルの SSO ログインが機能しません。
3. Azure 管理者の同意を許可（Go ページの「同意を許可」ボタン）。クリックすると、Organization.ReadWrite.All 委任スコープを要求する Salesforce 所有の固定 Entra アプリ（client_id=cd6bd63f-41ef-47cc-9465-86e986179a29、テナント部分は organizations — ユーザー自身のテナント ID でも、手順 1 で作成したアプリでもありません）への一度限りの同意リンクを含むモーダルが開きます。

   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 にリンクを生成または送信する操作はありません（公開 Connect API の対応機能がない内部 Aura コントローラーによって表示されます）。このリンクをそのまま貼り付け、Microsoft テナント管理者としてサインインした状態でクリックし、同意を許可するようユーザーに伝えてください — この操作では Microsoft 管理者として認証する必要があり、このスキルから API 経由で実行することはできません。 ユーザーが上記で行うすべての操作（手順 1 の Azure でのクリック操作と、手順 3 の同意クリック）は、ユーザー自身の手動作業です。Salesforce API から Azure／Entra にアクセスできないためです。Salesforce 側のすべての作業――手順 2 で、提供された認証情報（Git で追跡対象外のシークレットファイルから読み取ったシークレット。チャットから取得したものではありません）を Named Credential に書き込む作業――は、このスキルが自動化します。この役割分担こそ、このスキルの目的です。

Step 4b — IT Desk／IT Service の子スキルに委任する

「Set Up Salesforce IT Desk」／「Set Up Salesforce IT Service」のチェックリストグループに取りかかる前に、どちらを設定するかユーザーに確認してください。これらは機能の独立した 2 つの側面（対応担当者側と従業員側）であり、ユーザーは片方だけ必要な場合があります。

• Salesforce IT Desk — IT エージェント／対応担当者が Teams からチケットを一緒に処理し、解決するための設定です。 service-itsm-teams-itdesk-configure を呼び出します。
• Salesforce IT Service — 従業員が Teams から自分のチケットを作成、管理するための設定です。 service-itsm-teams-itservice-configure を呼び出します。
• 両方 — 2 つの子スキルを両方とも呼び出します。

各子スキルが独自の 3～4 項目のチェックリストグループ（<app> を有効にする → Teams に <app> アプリをインストールする → ユーザーアクセスを管理する → 任意の 4 項目目）を最初から最後まで処理します。このロジックをここで重複して実装しないでください。

Step 4c — 埋め込み Agentforce エージェント（Teams の「Ask AI Agent」）を委任する

ユーザーが埋め込み Agentforce エージェントに Teams カスタムクライアント内（「Salesforce Employee Assist」→「Ask AI Agent」）で応答させたい場合、つまり Teams_AgentForce MIAW デプロイメント、その Web チャネル（ユーザー検証 ON + JWKS_URL キーセット）、IT Service Employee Agent へのルーティングフロー、ポータルユーザー用の Agent Access 権限セットを構築する場合は、**service-itsm-teams-employee-agent-configure を呼び出してください。**これは独自のオブジェクトモデルを持つ、独立した大規模な機能です。ここで直接実装しようとしないでください。事前に従業員ポータルサイト（experience-portal-create）が存在している必要があります。

手順 5 — Azure 認証情報が作成されたら、優先サイトを登録する（Teams 拡張機能）

組織に 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 の手順（注意事項）がまだ完了していません。呼び出し自体の不具合ではありません。

一方、EC に authenticationStatus: "Configured" と表示されているにもかかわらず、AccessDenied（または 400 UNKNOWN_EXCEPTION "...Unable to fetch tenant ID"）が返される場合、原因はほとんどの場合、Azure/Entra の許可設定が不完全なことです。これは修正可能であり、ライセンスの制限ではありません（確認済み：以下を実施した後、同じ呼び出しが AccessDenied から 201 Success になりました）。次の順に確認してください。（1）管理者の同意が付与されていない — 手順 4a のスコープの一部には Admin consent required = Yes と表示されており、管理者が Grant admin consent をクリックするまでは 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 の後、Microsoft Entra アプリがまだ登録されていないのに、Teams が「設定済み／終了／完了」と宣言することです。その場合、Teams 内のサインインと送信 Graph 統合が機能しません。Entra アプリの登録は完了の必須前提条件として扱い、任意の最後の作業として扱わないでください。以下のすべての項目を（単に案内しただけでなく）確認できた場合に限り、完了と報告してください。

1. 機能が有効 — service-cloud-itsm-teams-integration が ENABLED を示し、ITSMTeamsEnabled が true を示していること（ステップ 1～3）。
2. Microsoft Entra アプリが登録済み — ユーザーがステップ 4a の Azure での操作を完了し、クライアント ID とテナント ID を（チャットで）提示し、ステップ 4a のコピペ用コマンドでクライアントシークレットを gitignore 対象のシークレットファイルに書き込んでいること（チャットには貼り付けないでください）。完了するまでは、停止して待ってください。これは必須のゲートです。先に進むことも、この条件を飛ばして完了を報告することもできません。
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 クライアント）は、この呼び出しだけでは完全に元に戻らない場合があります。それらの成果物も削除する必要があるか、ユーザーに確認し、別途手動でセットアップする作業として扱ってください。

---

関連する、個別に有効化する設定

この機能の「Fulfiller Hub」と「Employee Hub」の各部分は、2 つの関連する組織設定によって制御されます。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 有効化、固定の同意リンク、バージョンプレフィックスの要件など）は、references/gotchas.md にまとめられています。ステップの失敗を報告したり、有効化を推測して再試行したりする前に、必ずお読みください。

関連スキル

スキル	代わりに使用する場面
service-itsm-teams-itdesk-configure	「Salesforce IT Desk を設定する」チェックリストグループ（担当者側）— このスキルから委任されます（ステップ 4b を参照）
service-itsm-teams-itservice-configure	「Salesforce IT Service を設定する」チェックリストグループ（従業員側）— このスキルから委任されます（ステップ 4b を参照）
service-itsm-teams-employee-agent-configure	Teams の「Ask AI Agent」カスタムクライアント（Teams_AgentForce MIAW デプロイメント）で、埋め込みの Agentforce エージェントが応答するようにする場合 — このスキルから委任されます（ステップ 4c を参照）
service-itsm-swarming-configure	「スウォーミングのコラボレーションツールとして Teams を設定する」ために、service-cloud-swarming Go 機能を有効にする場合 — このスキルから直接ではなく、service-itsm-teams-itdesk-configure から呼び出されます
通知チャネルの設定	Notifications／TeamsNotifications の設定を有効にすることは、この機能とは別の項目です（専用の子スキルはまだありません）
experience-portal-create	従業員サービスのポータル／サイト自体を作成する場合
service-itsm-channels-coordinate	Teams、Slack、Swarming、Notifications、Portal を含むトップレベルのメニュー