service-itsm-agentic-setup-cmdb-bundle-deploy

CMDB Foundation バンドルをデプロイする（Service Cloud ITSM）

CMDB Foundation（base）コンテンツバンドルをインストールします。このバンドルには、CMDB を利用可能にするための標準構成アイテム種別、スキーマ、コンテンツが含まれています。これは CMDB セットアップスタックの最終段階であるレイヤー 4で、CMDB 機能がすでに有効になっていること（レイヤー 2）が前提です。すべての呼び出しは、4 つのメタツール（discover、describe、dispatch_readonly、dispatch）を介して、Salesforce ホスト型 Headless-360 MCP サーバー（サーバーキー headless-360）で実行されます。組織は現在の MCP セッションに紐付けられた OAuth JWT から特定されます。このスキルが組織 ID、エイリアス、認証情報を扱うことはありません。そのため、ユーザーごとの MCP インストールなしで、本番環境とサンドボックスのどちらでも同じように動作します。

対象範囲

• 対象：CMDB が有効になっていることの確認、稼働中のバンドルカタログの読み取り、base バンドルの正確なバージョンの特定、base（CMDB Foundation）バンドルのインストール、検証。
• 対象外：CMDB 機能の有効化／CMDB テナントのプロビジョニング（レイヤー 0～2 — service-itsm-agentic-setup-cmdb-configure）、権限セットの割り当て（レイヤー 3 — service-itsm-agentic-setup-cmdb-access-assign）、オプションのアドオンバンドル（例：Component Identification Rules）のインストール、CMDB レコードの CRUD、Discovery。

このスキルがインストールするのはbase バンドルのみです。オプションのアドオンは意図的に対象外としています。

順序が重要な理由

バンドル Connect API（bundleListView、bundles/details、bundleInstallation）は、orgHasCMDBEnabled によって制御されています。CMDB 機能が有効になるまでは、これらの API は 403 FUNCTIONALITY_NOT_ENABLED を返すため、このスキルは CMDB 機能の有効化スキルによって機能が有効になった後に必ず実行する必要があります。

組織による制御に加えて、これらの読み取り処理では実行中のユーザー自身の CMDB アクセス権も確認されます。そのため、ここでの 403 FUNCTIONALITY_NOT_ENABLED には、機能が無効である場合と、ユーザーにアクセス権がない場合の 2 つの異なる原因があります。ステップ 1 では、ユーザーを別の場所に誘導する前に機能ステータスを確認して原因を切り分けてください。403 の原因が機能の無効化だと決めつけてはいけません。

仕組み

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

• mcp__headless-360__discover — インデックス化された操作カタログを意味的に検索します（発見／確認のみ）。
• mcp__headless-360__describe — インストール POST の前に、完全な入力スキーマと正規ルートを取得します。
• mcp__headless-360__dispatch_readonly — すべての読み取り（GET）に使用するディスパッチャーです。
• mcp__headless-360__dispatch — すべての書き込み（POST/PATCH）に使用するディスパッチャーです。

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

---

確認事項

会話から推測できないことだけを確認してください。

• どの組織ですか？ 対象の組織を確認し、この組織にコンテンツがインストールされます（書き込み）とはっきり伝えてください。本番環境の場合は、明示的な確認を得てください。

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

---

ワークフロー

順番に実行します。必ず書き込みの前に読み取ってください。インストールする前にカタログを読み取り、正確なバージョンを特定してください。バージョン文字列を推測してはいけません。

ステップ 1 — CMDB が有効になっていることを確認する（読み取り、ゲート）

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

• 200 → CMDB は有効です。レスポンスには、利用可能なバンドルとそのインストール状況が表示されます。次に進みます。
• 403 FUNCTIONALITY_NOT_ENABLED → 原因が特定できないため、CMDB が無効だとユーザーに伝える前に切り分けてください。 この読み取りでは、組織のゲートと実行中のユーザー自身の CMDB アクセス権の両方が適用されるため、403 には 2 つの原因が考えられます。機能のステータスを確認して、原因を区別してください。

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

  • status != ENABLED → CMDB 機能が有効になっていません。ここで停止し、まず CMDB の 機能を有効にするスキル（service-itsm-agentic-setup-cmdb-configure）をユーザーに案内してください。
  • status == ENABLED → 機能は有効ですが、実行中のユーザーにCMDB 権限セットがありません。ここで停止し、CMDB アクセスを付与するために CMDB アクセス割り当てスキル（service-itsm-agentic-setup-cmdb-access-assign）をユーザーに案内してください。最低限、 読み取りセットに加えて、バンドル管理には Type Manager が必要です。権限を付与した後、再試行してください。CMDB はすでに有効なため、 機能を有効にするスキルには案内しないでください。

bundleListView のレスポンスから、基本バンドル（CMDB Foundation）を特定し、その currentInstalledVersion を確認します。最新バージョンがすでにインストールされている場合は、対応不要であることをユーザーに伝えてください。

ステップ 2 — 基本バンドルの正確なバージョンを解決する（読み取り）

バージョンを推測したり、ハードコードしたりしないでください。信頼できるバージョン情報をバンドルの詳細から読み取ります。

dispatch_readonly({ "url": "/services/data/v67.0/connect/cmdb/bundles/details", "method": "GET", "queryParams": { "bundleIdentifier": "base" } })

カタログから latestVersion を読み取り、その文字列をそのままインストールに使用してください。先頭の v も含め、文字を削除、追加、再フォーマットしないでください。インストールエンドポイントはレジストリに対してバージョンを完全一致で照合し、レジストリにはカタログが報告したとおりのバージョン（例："v3.0"）が保存されているため、値は変更せずに渡す必要があります。

インストールできるのは最新バージョンのみです。 インストールエンドポイントは最新ではないバージョン（"Target version <x> is not the latest available version"）を拒否します。古いバージョンのインストールやロールバックには対応していないため、常に latestVersion を解決し、そのバージョンを正確にインストールしてください。installedVersion がすでに latestVersion と一致する場合は、ここで停止してください。基本バンドルは最新です。

bundleListView（ステップ 1）が 200 を返したにもかかわらず、bundles/details が 403 FUNCTIONALITY_NOT_ENABLED を返す場合： 組織のゲートに問題はありませんが、実行中のユーザーにバンドル管理権限がありません。 bundles/details には Type Manager ロールが必要です。Reader／Owner／Type Reader のセットでは不十分です。Type Manager を付与するために CMDB アクセス割り当てスキルをユーザーに案内し、その後再試行してください。代替策として、 bundleListView には基本バンドルの currentInstalledVersion と latestVersion がすでに含まれているため、Type Manager を割り当てられない場合は、ステップ 1 のレスポンスからバージョンを解決できます。

ステップ 3 — ユーザーに確認する（書き込みの前）

基本バンドルの名前、インストールするバージョン、対象の組織を提示します。書き込みを行う前に、明示的な確認を得てください。これにより、すぐに使える CMDB コンテンツが組織にインストールされることを明確に伝えてください。

ステップ 4 — 基本バンドルをインストールする（書き込み）

discover(query="cmdb bundle installation") を呼び出し、続いて describe(id=<bundleInstallation operation id>) を呼び出して入力スキーマを確認してから、インストールします。

dispatch({ "url": "/services/data/v67.0/connect/cmdb/bundleInstallation", "method": "POST", "body": { "bundleIdentifier": "base", "version": "<latestVersion from Step 2, verbatim>" } })

bundleIdentifier と version の両方が必須です。また、version にはカタログの latestVersion 文字列を変更せずに渡す必要があります。success: true のレスポンスはインストールが開始されたことを意味します。インストールは非同期で完了する場合があります。

ステップ 5 — 検証する（読み取り — インストールのレスポンスだけを信用しない）

バンドルの詳細を再度読み取り、基本バンドルにインストールしたバージョンが表示されていることを確認します。

dispatch_readonly({ "url": "/services/data/v67.0/connect/cmdb/bundles/details", "method": "GET", "queryParams": { "bundleIdentifier": "base" } })

installedVersion は、インストールしたバージョンと一致する必要があります。インストールが非同期で、まだ更新されていない場合は、処理中であることと再確認の方法をユーザーに伝えてください。

---

ルール／制約

制約	理由
有効化の判定として、最初に bundleListView を読み取る	ここで403が返る場合、CMDBが有効になっていないか、ユーザーにCMDBへのアクセス権がありません。対応する前に、機能のステータスを確認して切り分けてください
バージョンは bundles/details から取得し、推測しないでください。latestVersion をそのまま渡してください	インストールエンドポイントは、レジストリに保存されているバージョンと完全一致する文字列で照合します。レジストリにはカタログの表記どおりに保存されています（例："v3.0"）。文字を削除したり、形式を変えたりしないでください
最新バージョンのみインストールする	エンドポイントは最新ではないバージョンを拒否します（"Target version <x> is not the latest available version"）。古いバージョンのインストールやロールバックには対応していません
base のみインストールする	このスキルの対象はCMDB Foundationのbaseバンドルです。オプションのアドオンは対象外です
対象の組織とインストールについてユーザーに確認する	コンテンツのインストールは、本番組織に対する実際の変更であり、元に戻すのが困難です
最新バージョンがすでにインストールされている場合はスキップする	不要なインストールを避け、「すでに最新です」と報告してください
success: true は「開始済み」として扱い、別途検証する	インストールは非同期で行われる場合があります
内部用語をユーザーに決して見せない	レコードID、HTTPステータスコード（403／400／500）、APIエラーコード（FUNCTIONALITY_NOT_ENABLED など）、エンドポイント名（bundleListView、bundles/details、bundleInstallation）、開発者名、ツール内部の情報（dispatch、headless-360）はユーザー向けの出力に含めないでください。バンドル名とバージョンを使い、平易な言葉で説明してください

---

検証チェックリスト

• bundleListView が 200 を返した（CMDBが有効で、ユーザーにアクセス権がある）か？
• bundles/details から base の latestVersion を取得した（推測していない）か？
• すでに最新バージョンの場合、スキップしたか？
• 書き込みの前に、対象の組織とインストールについてユーザーに確認したか？
• bundleInstallation が success: true を返したか？
• installedVersion が一致することを確認したか（または非同期処理中であると報告したか）？

---

出力に関する要件

CMDB Bundle Deploy — Complete (via service-itsm-agentic-setup-cmdb-bundle-deploy)

Target org: <org>

  Bundle:   CMDB Foundation (base)
  Version:  <version>
  Status:   Installation initiated — success

CMDB now has its base content installed. Combined with the enabled feature and assigned user
access, CMDB is ready end-to-end.

ユーザー向けの出力では内部用語を使わないでください（レコードID、HTTPステータスコード、エラーコード、エンドポイント名は含めません）。いずれかの手順が失敗した場合は処理を止め、何が成功しなかったのか、それがユーザーにとって何を意味するのかを平易な言葉で伝えてから、解決方法を案内してください（例：「この組織ではCMDBがまだ有効になっていないため、コンテンツをインストールできません」と伝え、403コードをそのまま表示しないでください）。

---

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

症状	考えられる原因	ユーザーへの説明
カタログの読み取りで 403 が返り、機能も有効になっていない	組織でCMDB機能が有効になっていない	まず組織でCMDBを有効にする必要があります。これは別のセットアップ手順です。機能の有効化スキルを案内してください
カタログの読み取りで 403 が返るが、機能は有効になっている	機能は有効ですが、実行ユーザーにCMDBへのアクセス権がありません（この読み取りではユーザーレベルのアクセス権も確認されます）	まずユーザーにCMDBへのアクセス権を付与してください（これは別のセットアップ手順です）。その後、もう一度試してください。機能自体はすでに有効です
バージョンの読み取りで 403 が返るが、カタログの読み取りは成功した	ユーザーにCMDBバンドル管理ロール（Type Manager）がありません	ユーザーにCMDB Type Managerロールを付与してから、再試行してください（これは別のアクセス設定手順です）。組織自体のセットアップは正しく完了しています
インストールが拒否された — バンドル／バージョンが存在しない	バージョン文字列が間違っています	カタログを再度読み取り、表示される最新バージョンを正確に使用してください
インストールは成功と報告されたが、バージョンが変わっていない	インストールがバックグラウンドで実行中です	処理中です。完了したことを確認するため、しばらくしてからもう一度確認してください
インストール時の後続処理エラー	プラットフォームの依存関係に一時的な問題があります	もう一度試してください。繰り返し失敗する場合は、Salesforceサポートへの問い合わせが必要です
接続／認証エラー	組織への接続が設定されていないか、期限切れです	組織への接続を再認証し、意図した組織を参照していることを確認してから再試行してください

---

スキル間の連携

タイミング	スキル
組織の CMDB 機能がまだ有効になっていない場合（組織のゲートがまだ閉じている場合）	service-itsm-agentic-setup-cmdb-configure（レイヤー 0～2 — まず機能を有効にしてから、ここに戻ります）
実行中のユーザーに CMDB へのアクセス権がない場合、またはバンドル管理の Type Manager 権限がない場合	service-itsm-agentic-setup-cmdb-access-assign（レイヤー 3 — Type Manager を含む CMDB アクセス権をユーザーに付与してから、ここに戻ります）

---

リファレンスファイル一覧

ファイル	読むタイミング
references/mcp-invocation.md	バンドルカタログとインストール呼び出しの正確な mcp__headless-360__* の形式、レスポンスのエンベロープ、インストールスキーマの参照方法、エラー一覧