service-itsm-agentic-setup-cmdb-configure

CMDB 機能を有効化する（Service Cloud ITSM）

CMDB の前提条件スタックの最初の 3 層を順にたどり、組織を「CMDB がオフ」の状態から「CMDB 機能が有効」の状態にします。すべての呼び出しは、4 つのメタツール（discover、describe、dispatch_readonly、dispatch）を介して、Salesforce がホストする Headless-360 MCP サーバー（サーバーキー headless-360）を通じて実行されます。対象の組織は、現在の MCP セッションに紐づいた OAuth JWT から特定されます。このスキルが組織 ID、エイリアス、認証情報を扱うことはありません。そのため、ユーザーごとに MCP をインストールする必要なく、本番環境でもサンドボックスでも同じように動作します。

このスキルの対象はレイヤー 0～2です。ユーザーアクセス（レイヤー 3）とコンテンツバンドル（レイヤー 4）は別のスキルで扱います。詳しくはこのファイルの末尾を参照してください。

このスキルが解除するゲート

CMDB Connect API はすべて、次の項目を確認します。

orgHasCMDBEnabled = orgHasCMDBPermission (org perm ITSrvcsCnfgMgmnt)  &&  OrgPreferences.CMDBEnabled

orgHasCMDBEnabled が true になるまでは、CMDB API は 403 FUNCTIONALITY_NOT_ENABLED を返します。CMDBEnabled は直接設定できるプリファレンスではありません。レイヤー 2 で機能を有効にした副作用として切り替わります。このスキルの目的は、このゲートが true を返すようにすることです。

必要条件ですが、特定のユーザーにとって常に十分とは限りません。 組織レベルのこのゲートを解除しても、それだけで特定のユーザーが CMDB データを読み取れるようになるわけではありません。一部の CMDB 読み取り（例：bundleListView）では、ユーザーレベルの CMDB アクセスも適用されます。実行ユーザーに CMDB 権限セットが割り当てられていない場合、機能が正しく ENABLED になっていても、「このユーザーでは有効になっていません」という同じ 403 FUNCTIONALITY_NOT_ENABLED が返されます。これはレイヤー 3（service-itsm-agentic-setup-cmdb-access-assign）で扱うものであり、このスキルの失敗ではありません。このスキルの成功は、CMDB データの読み取りではなく、機能の status == ENABLED で確認してください。

対象範囲

• 対象：CMDB 組織権限の確認（レイヤー 0）、CMDB テナントのプロビジョニング開始とポーリング（レイヤー 1）、CMDB 機能の有効化前チェック、有効化、確認（レイヤー 2）。
• 対象外：権限セットの割り当て（レイヤー 3 — service-itsm-agentic-setup-cmdb-access-assign）、バンドルのインストール（レイヤー 4 — service-itsm-agentic-setup-cmdb-bundle-deploy）、CMDB レコードの CRUD、Discovery / Service Graph Connector、識別ルール。

仕組み

すべての操作は、headless-360 MCP ツールを介して実行されます。読み取りには mcp__headless-360__dispatch_readonly、書き込みには mcp__headless-360__dispatch を使用します。どちらも生の HTTP を受け取ります：{"url": "<path>", "method": "GET|POST", "body"?: {...}, "queryParams"?: {...}} — {operation_id, arguments} ではありません。各呼び出しの正確な url / method / body については、references/mcp-invocation.md を参照してください。4 つのツールは次のとおりです。

• mcp__headless-360__discover — インデックス化された操作カタログをセマンティック検索します。このスキルで使用する Setup/Connect のルートは、常に検索上位に表示されるとは限らず（またはインデックス化されていない場合があり）、見つからなくてもルートが存在しないことを意味しません。references/mcp-invocation.md を参照し、正確なパスを直接ディスパッチしてください。
• mcp__headless-360__describe — POST の前に、完全な入力スキーマと正規ルートを取得します。
• mcp__headless-360__dispatch_readonly — すべての読み取り（GET）に使用するディスパッチャーです。
• mcp__headless-360__dispatch — すべての書き込み（POST/PATCH）に使用するディスパッチャーです。

このスキルが認証情報を扱うことはありません。組織は現在の OAuth セッションに紐づいています。dispatch* の呼び出しで認証エラーが返された場合は、headless-360 MCP 接続を再認証し（セッションが意図した組織を参照していることも確認するよう）ユーザーに伝えて、その後は停止してください。

---

確認事項

会話から推測できないことだけを尋ねてください。

• どの組織ですか？ 対象の組織を確認し、テナントのプロビジョニングと機能の有効化は書き込み操作であるため、この組織が変更されることを明確に伝えてください。本番環境の場合は、明示的な確認を得てください。

ユーザーがすでに伝えた内容を再度尋ねないでください。「（会話から）」と記して事前入力してください。

---

ワークフロー

すべての手順は順番に実行し、各段階の条件を満たす必要があります。レイヤーで失敗した場合は先に進まないでください。 書き込む前に必ず読み取ってください。変更を加える前に、読み取り専用の確認を実行してください。

レイヤー 0 — CMDB の組織 SKU を確認する（読み取り専用、必須ゲート）

CMDB には組織権限 ITSrvcsCnfgMgmnt が必要です。この権限はエディション、ライセンス、または組織テンプレートによってのみ付与されます。API で設定することはできません。 組織に CMDB SKU が含まれていることを確認する、最も確実で、どの組織でも利用できる方法は、CMDB の権限セットライセンスを照会することです。このライセンスが存在するのは、そのライセンスでプロビジョニングされた組織だけです。

dispatch_readonly({ "url": "/services/data/v63.0/query", "method": "GET", "queryParams": { "q": "SELECT Id FROM PermissionSetLicense WHERE DeveloperName = 'ItSrvcCnfgItmReadPsl'" } })
→ totalSize == 1  (licensed)   |   totalSize == 0  (not licensed)

• totalSize == 1 → 組織は CMDB のライセンスを保有しています。レイヤー 1 に進みます。
• totalSize == 0 → 停止します。ユーザーには平易な言葉で伝えます（ユーザーに表示されるメッセージに開発者向けの名前や API への言及を含めないでください）。

  この組織には CMDB のライセンスがありません。CMDB が利用できるかどうかは、組織のエディションまたはライセンスによって決まり、セットアップから有効にすることはできません。組織のプロビジョニング時に含める必要があります。組織に CMDB を設定してもらう（または、すでに CMDB がある組織を使用する）うえで、もう一度実行してください。

コア Connect API の GET /services/data/v63.0/setup/org/permissions/ITSrvcsCnfgMgmnt （{"isPermissionEnabled": true|false}）も代替手段ですが、一部の組織タイプ（orgfarm のテスト組織など）では 404 が返るため、上記の PSL の照会を優先してください。詳細は references/mcp-invocation.md を参照してください。どの照会でも確認できない場合は、組織権限を検証できなかったことを報告し、続行する前に組織が CMDB のライセンスを保有しているかユーザーに確認してください。

レイヤー 1 — CMDB テナントをプロビジョニングする

CMDB は専用テナント（CMDB テナント）上で動作し、そのステータスが PROVISIONED に達する必要があります（非同期）。

1. 現在のステータスを確認する（読み取り）：

   dispatch_readonly({ "url": "/services/data/v67.0/connect/tenantProvisioningStatus", "method": "GET" })
   

   status に応じて分岐します。

   • PROVISIONED → すでに完了しています。レイヤー 2 に進みます（トリガーもポーリングも不要です）。
   • UNPROVISIONED → ジョブは実行されていません。手順 2 に進み、トリガーします。この状態では待機やポーリングを行わないでください。待ってもプロビジョニングは開始されず、予算を消費するだけです。
   • PROVISIONING_IN_PROGRESS → ジョブはすでに実行中です。トリガーは省略し、手順 3 のポーリングに進みます。
   • FAILED → 手順 3 の FAILED ケースとして扱います（理由を伝え、API で再試行しないでください）。

2. プロビジョニングをトリガーする（書き込み）— 手順 1 で UNPROVISIONED と確認された場合のみ行います。最初にユーザーに確認してください。

   dispatch({ "url": "/services/data/v67.0/connect/tenantProvisioningStatus", "method": "POST" })
   

   トリガーの応答後、プロビジョニングが開始され、通常は 2 分以上かかるため、まだ確認しても何もないことをユーザーに伝えます。

3. GET をポーリングし、status == PROVISIONED になるまで確認します。これは非同期で、確実に 2 分以上かかります（完了時間の測定値は、ほぼ 約 2 分 40 秒に集中しています）。そのため、すぐにポーリングしても必ず何も起きません。すべての時間計測の基準には、この実行の開始時刻ではなく、応答の triggeredAt を使用してください。ジョブは以前の実行でトリガーされている可能性があります（手順 1 の PROVISIONING_IN_PROGRESS の項目）。triggeredAt を UTC のエポックとして解析し、elapsed = max(0, now − triggeredAt) を計算します。時計のずれ（またはサーバーとエージェント間のタイムゾーンの不一致）によって elapsed が負になり（いつまでも待ち続ける）、誤ったタイムアウトが発生しないよう、≥ 0 にクランプしてください。triggeredAt がない、または解析できない場合（トリガー POST の応答にまだ値が反映されていない場合や、以前の実行による進行中の行で値が省略されている場合があります）は、この実行の開始時刻を基準にします。elapsed = 0 として約 2 分の待機時間をすべて確保し、常に分岐が確定的に実行されるようにしてください。そのうえで、次のようにします。

   • elapsed < ~2 min → 最初の確認は triggeredAt から約 2 分後まで待ちます（確実に無駄になる早すぎるポーリングを避けます）。その後は 30 秒ごとにポーリングします。
   • ~2 min ≤ elapsed < 10 min → すぐにポーリングします（初回の待機時間はすでに経過しているため、新たに 2 分待たないでください）。その後は 30 秒ごとにポーリングします。
   • elapsed ≥ 10 min → 新たに待機を開始せず、以下のタイムアウトケースとして扱います（最後に確認したステータスを報告し、ユーザーに判断を委ねます）。 全体の制限時間は、triggeredAt から 10 分 です（約 2 分の最低待機時間の後、約 16 回確認します）。約 2 分の最低待機時間は最低時間であり、追加の遅延ではありません。通常は約 2 分 40 秒で完了するため、1～2 回のポーリングで完了を確認できます。それ以上延ばさないでください。初期待機中はポーリングしないでください。次のいずれかになったら、すぐにループを終了します。
   • status == PROVISIONED → 成功です。Layer 2 に進みます。
   • status == FAILED → ただちに停止します。API 経由で再試行してはいけません。次の 3 点を平易な言葉でユーザーに伝えてください。
     1. 失敗理由を、人が読めるテキストに変換して伝えます。 レスポンスボディから読み取ってください（FAILED ペイロードには error／failureReason／message などの詳細フィールドが含まれています。<／> などの HTML エンティティをアンエスケープし、マークアップを取り除いてください）。レスポンスに詳細が含まれていない場合は、理由が返されないままテナントのプロビジョニングに失敗したと伝えてください。
     2. 組織のテナントプロビジョニング設定ページへのリンク。対象組織のインスタンス URL を使って、<org instance URL>/lightning/setup/CMDBProvisionalSettings/home を作成します。
     3. そのページを開いて手動でプロビジョニングを試すようユーザーに依頼し、テナントのステータスが PROVISIONED になったら、このスキルを再実行するよう伝えます。 手動での再試行も失敗した場合に限り、Salesforce サポートへの問い合わせが必要です。
   • 10 分の制限時間が経過した → 停止し、最後に確認したステータスを報告して、待機を続ける（再実行する）か調査するかをユーザーに判断してもらいます。10 分の上限を超えて待機し続けないでください。

   バックグラウンドでのポーリング（ランタイムが対応している場合）。 プロビジョニングには数分かかるため、ユーザーを待たせたままにしないでください。実行中のランタイムがバックグラウンド処理に対応している場合に限り（切り離したサブエージェントを起動できるエージェントランタイムや、スケジュールされたウェイクアップなど）、待機からポーリングまでのループをバックグラウンドタスクに委任して、ユーザーが作業を続けられるようにし、完了時に結果（PROVISIONED／FAILED／タイムアウト）を報告します。ランタイムが単一スレッドのターンである場合（ADK／Agentforce／headless-360 の本番環境のパスは単一スレッドであり、ポーリングループが会話をブロックします）、代わりにインラインでポーリングします。いずれの場合も、（a）数分かかることを事前にユーザーに伝え、（b）再開方法を案内してください。ユーザーが離席してターンが終了した場合、このスキルを再実行すれば、Layer 1 が現在のステータスから再開します（すでに PROVISIONED になっているテナントは、Layer 2 に直接進みます）。ランタイムに備わっていない可能性のあるバックグラウンド処理機能を、決して必須にしないでください。

Layer 2 — CMDB 機能を有効にする（これにより 403 の制限が解除されます）

機能の API 名は service-cloud-itsm-cmdb-integration です。

1. ステータスを事前確認（読み取り）：

   dispatch_readonly({ "url": "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-cmdb-integration/status", "method": "GET" })
   

   • status == ENABLED → すでに完了しています。検証に進みます。
   • status == NOT_ENABLED かつ enableBlockedReasons: [] → 有効化できます。
   • enableBlockedReasons が空でない → 停止し、各理由を平易な言葉でユーザーに伝えます（これらは組織で未対応の前提条件です。有効化を試みないでください）。
2. ユーザーに確認してから、有効化します（書き込み）：

   dispatch({ "url": "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-cmdb-integration/enable", "method": "POST", "body": {} })
   → {"success": true}
   

3. 検証します（読み取り）。POST レスポンスだけを信用しないでください。

   dispatch_readonly({ "url": "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-cmdb-integration/status", "method": "GET" })
   → expect status == ENABLED
   

   status == ENABLED が、このスキルに必要な唯一かつ決定的な確認です。 Layer 2 の成否は、この確認だけで判定します。ゲートを確認するための CMDB データ読み取りは実行しません。CMDB データの読み取り（例：bundleListView）は、実行中のユーザー自身の CMDB アクセスにも依存するため、組織レベルの有効化を正確に確認できません。詳細は「このスキルが解除するゲート」の注記を参照してください。機能のステータスが ENABLED になったら、Layer 2 は完了です。

ルール／制約

制約	理由
何よりも先に Layer 0 を確認する	ITSrvcsCnfgMgmnt がオフの場合、それ以降の手順は成功しません。明確なメッセージを表示して、早い段階で処理を中止してください
API 経由で ITSrvcsCnfgMgmnt を設定しようとしない	セッターはありません。ライセンス／エディション／テンプレートでのみ設定できます
CMDBEnabled を直接設定しない（例：updateDefaultOrgPrefs 経由）	設定可能な環境設定の許可リストに含まれていないため、サーバーは 500 で拒否します。Layer 2 の機能を有効にしたときの副作用としてのみ切り替わります
書き込みの前に必ず読み取りを行い、書き込みの後に必ず確認する	テナントと機能は非同期で状態が変化するため、POST のレスポンスが実際の状態に遅れて反映されることがあります
対象の組織と各書き込みについて、ユーザーに確認する	これらは稼働中の組織に対する実際の変更であり、元に戻すのは困難です
失敗またはブロックされたレイヤーの先へ進まない	後続のレイヤーは先行するレイヤーに依存しており、403 になります
ポーリングのタイミングは、実行開始時ではなくレスポンスの triggeredAt を基準にする（UTC のエポックとして解析し、経過時間 = max(0, 現在時刻 − triggeredAt)）。最初の確認までは約 2 分の待機時間を設け、その後は 30 秒ごとに確認し、triggeredAt から合計 10 分を上限とする。triggeredAt がない、または解析できない場合は、この実行の開始時刻を基準にする（経過時間 = 0）	プロビジョニングには確実に 2 分以上（計測値は約 2 分 40 秒）かかるため、それより早いポーリングは必ず何も行いません。PROVISIONING_IN_PROGRESS のエントリは以前の実行で開始された可能性があります。すでに約 2 分の待機時間を過ぎている場合は直ちにポーリングし、すでに 10 分を過ぎている場合は、新たに 2 分待たずにタイムアウトを報告してください。経過時間を 0 以上に制限することで、時計のずれやタイムゾーンの不一致による無限待機や誤ったタイムアウトを防ぎます。フォールバックにより、タイムスタンプがない場合も分岐が実行されます。10 分の上限を超えて待ち続けないでください
ランタイムがサポートする場合にのみポーリングループをバックグラウンドで実行し、それ以外の場合はインラインでポーリングする。バックグラウンド実行の仕組みを必須にしない	数分間、ユーザーを何もできない状態にしてはいけません。一方、本番環境の headless-360／ADK パスはシングルスレッドのターンであるため、バックグラウンドポーラーを必須とするスキルはそこで動作しません。必ず再実行して続行する方法を案内してください
FAILED の場合、API 経由で再試行しない。理由を解読して Setup URL を提示し、手動で再試行するよう依頼する	API によるトリガーはすでに失敗しています。ユーザーは CMDB プロビジョニングの Setup ページから再試行できます。このページには実際のエラーと、必要な手動対応が表示されます
内部用語をユーザーに見せない	レコード ID、組織 ID、HTTP ステータスコード（403／500 など）、API エラーコード（FUNCTIONALITY_NOT_ENABLED など）、エンドポイント名（bundleListView、tenantProvisioningStatus）、開発者向けの名前（ITSrvcsCnfgMgmnt、CMDBEnabled）、ツールの内部情報（dispatch、headless-360）をユーザー向けの出力に含めないでください。平易な言葉に言い換え、人が理解しやすい名称とステータスを使ってください

---

確認チェックリスト

• Layer 0：ITSrvcsCnfgMgmnt が true であることを確認した（または、ライセンスに関する明確なメッセージを表示して停止した）か？
• Layer 1：テナントの status == PROVISIONED を確認したか？
• Layer 2：有効化の前に、事前確認で enableBlockedReasons: [] が表示されたか？
• Layer 2：有効化の結果、success: true が返されたか？
• Layer 2：確認用 GET で status == ENABLED が表示されたか？ （これのみを成功基準とし、CMDB データの読み取りによる確認は行いません）
• 事前に、対象の組織と各書き込みについてユーザーに確認したか？

---

出力に関する要件

CMDB Feature Enable — Complete (via service-itsm-agentic-setup-cmdb-configure)

Target org: <org>

  CMDB license .................. Present
  CMDB tenant ................... Provisioned
  CMDB feature .................. Enabled

CMDB is now enabled on this org. Next steps:
  • Assign user access  → service-itsm-agentic-setup-cmdb-access-assign
  • Install base bundle  → service-itsm-agentic-setup-cmdb-bundle-deploy

ユーザー向けの出力に内部用語を含めないでください（レコード ID、HTTP ステータスコード、エラーコード、エンドポイント名、開発者向けの名前は使用しません）。いずれかの手順が失敗した場合は停止し、どのセットアップが成功しなかったのか、それがユーザーにとって何を意味するのかを平易な言葉で伝え、該当する修正方法を案内してください。生のエラー（403 や FUNCTIONALITY_NOT_ENABLED など）はコードをそのまま伝えるのではなく、「CMDB はまだ有効になっていません」のように、その意味を説明してください。

---

よくある失敗（平易な言葉で伝えてください）

症状	考えられる原因	ユーザーへの説明
Layer 0 が false を返す	組織に CMDB SKU がありません	ライセンス／エディションの前提条件です。どの API でも付与できません。CMDB を備えた組織を用意してください
CMDB の読み取り時に 403 FUNCTIONALITY_NOT_ENABLED が発生し、機能の status != ENABLED	機能がまだ有効になっていません（Layer 2 が未完了です）	Layer 2 を完了してください。機能が ENABLED になって初めて制限が解除されます
bundleListView で 403 FUNCTIONALITY_NOT_ENABLED が発生し、機能の status == ENABLED	機能は有効ですが、実行中のユーザーに CMDB 権限セットがありません（bundleListView はユーザーレベルのアクセスも確認します）	Layer 2 の失敗ではなく、Layer 3 の問題です。service-itsm-agentic-setup-cmdb-access-assign を実行して、ユーザーに CMDB アクセス権を付与してください
機能の有効化がブロックされる（enableBlockedReasons が空ではない）	組織に必要な依存関係が不足しています	各理由を伝えてください。まずそれらを解決してから再試行してください
テナントが UNPROVISIONED／PROVISIONING_IN_PROGRESS のままになる、または処理に時間がかかる	プロビジョニングは非同期です	通常は約 2〜3 分かかります。10 分の制限時間内でポーリングを続けるか、トリガーを再試行してください
テナントが FAILED になる	Salesforce 側でプロビジョニングジョブが失敗しました	デコードした失敗理由と、組織の /lightning/setup/CMDBProvisionalSettings/home リンクを共有し、そこで手動でプロビジョニングを再試行するようユーザーに伝えてください。手動での再試行も失敗した場合に限り、Salesforce サポートにエスカレーションしてください
dispatch* の認証エラー	headless-360 MCP セッションが認証されていないか、トークンの有効期限が切れています	headless-360 MCP 接続を再認証し、セッションが意図した組織を参照していることを確認してください

---

参照ファイル一覧

ファイル	確認するタイミング
references/mcp-invocation.md	Layer 0〜2 の各呼び出しに使う正確な dispatch* の URL／メソッド／本文、レスポンスのエンベロープ、エラー一覧