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

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Deploy the CMDB Foundation Bundle (Service Cloud ITSM)

部署CMDB Foundation包（Service Cloud ITSM）

Installs the CMDB Foundation (base) content bundle — the out-of-the-box configuration-item types, schema, and content that make CMDB usable. This is Layer 4, the final layer of the CMDB setup stack, and it requires the CMDB feature to already be enabled (Layer 2). Every call runs through the Salesforce-hosted Headless-360 MCP server (server key

headless-360

) via its four meta-tools (

discover

describe

dispatch_readonly

dispatch

). The org is derived from the OAuth JWT bound to the current MCP session — the skill never handles an org id, alias, or credentials — so this works identically against production and sandbox with no per-user MCP install.

安装CMDB Foundation（基础版）内容包——即让CMDB可用的开箱即用配置项类型、架构和内容。这是CMDB配置栈的第4层，也是最后一层，要求CMDB功能已启用（第2层）。所有调用都通过Salesforce托管的Headless-360 MCP服务器（服务器密钥

headless-360

）及其四个元工具（

discover

、

describe

、

dispatch_readonly

、

dispatch

）执行。组织信息来自绑定到当前MCP会话的OAuth JWT——该skill从不处理组织ID、别名或凭据——因此它在生产环境和沙盒环境中的工作方式完全相同，无需为每个用户安装MCP。

Scope

范围

In scope: confirming CMDB is enabled, reading the live bundle catalog, resolving the exact version of the base bundle, installing the base (
```
CMDB Foundation
```
) bundle, and verifying.
Out of scope: enabling the CMDB feature / provisioning the ITOM tenant (Layers 0–2 —
```
service-itsm-agentic-setup-cmdb-configure
```
), assigning permission sets (Layer 3 —
```
service-itsm-agentic-setup-cmdb-access-assign
```
), installing optional add-on bundles (e.g. Component Identification Rules), CMDB record CRUD, or Discovery.

This skill installs the base bundle only. Optional add-ons are intentionally out of scope.

包含范围：确认CMDB已启用、读取实时包目录、解析基础包的确切版本、安装基础版（
```
CMDB Foundation
```
）包并进行验证。
排除范围：启用CMDB功能/配置ITOM租户（第0-2层——
```
service-itsm-agentic-setup-cmdb-configure
```
）、分配权限集（第3层——
```
service-itsm-agentic-setup-cmdb-access-assign
```
）、安装可选附加包（如组件识别规则）、CMDB记录增删改查（CRUD）或Discovery。

本skill仅安装基础包。可选附加包不在范围内。

Why order matters

顺序重要性

The bundle Connect APIs (

bundleListView

bundles/details

bundleInstallation

) are gated by

orgHasCMDBEnabled

. Until the CMDB feature is enabled they return

403 FUNCTIONALITY_NOT_ENABLED

, so this skill must run after the CMDB feature-enable skill has turned the feature on.

On top of the org gate, these reads also enforce the running user's own CMDB access, so a

403 FUNCTIONALITY_NOT_ENABLED

here has two distinct causes — feature-off or user-has-no-access. Step 1 disambiguates them via the feature status before sending the user anywhere; never assume a 403 means the feature is off.

包连接API（

bundleListView

、

bundles/details

、

bundleInstallation

）受

orgHasCMDBEnabled

限制。在CMDB功能启用前，它们会返回

403 FUNCTIONALITY_NOT_ENABLED

，因此本skill必须在CMDB功能启用skill开启功能后运行。

除了组织层面的限制外，这些读取操作还会验证当前用户自身的CMDB访问权限，因此此处的

403 FUNCTIONALITY_NOT_ENABLED

有两种不同原因——功能未开启或用户无访问权限。步骤1会先通过功能状态区分这两种情况，再引导用户；切勿假设403意味着功能未开启。

Mechanism

机制

All operations dispatch through headless-360 MCP tools. Reads go through

mcp__headless-360__dispatch_readonly

, writes through

mcp__headless-360__dispatch

— both take raw HTTP:

{"url": "<path>", "method": "GET|POST", "body"?: {...}, "queryParams"?: {...}}

— not

{operation_id, arguments}

. See

references/mcp-invocation.md

for the exact

url

method

body

of every call. The four tools:

```
mcp__headless-360__discover
```
— semantic search over the indexed operation catalog (discovery / confirmation only).
```
mcp__headless-360__describe
```
— pull the full input schema and canonical route before the install POST.
```
mcp__headless-360__dispatch_readonly
```
— the dispatcher for every read (GET).
```
mcp__headless-360__dispatch
```
— the dispatcher for every write (POST/PATCH).

The skill never handles credentials — the org is bound to the current OAuth session. If a

dispatch*

call returns an auth error, tell the user to re-authenticate the headless-360 MCP connection (and confirm the session points at the intended org), then stop.

所有操作都通过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

。四个工具的作用如下：

```
mcp__headless-360__discover
```
——对已索引的操作目录进行语义搜索（仅用于发现/确认）。
```
mcp__headless-360__describe
```
——在安装POST请求前拉取完整的输入架构和规范路由。
```
mcp__headless-360__dispatch_readonly
```
——所有读取（GET）操作的调度器。
```
mcp__headless-360__dispatch
```
——所有写入（POST/PATCH）操作的调度器。

该skill从不处理凭据——组织信息绑定到当前OAuth会话。如果

dispatch*

调用返回认证错误，请告知用户重新认证headless-360 MCP连接（并确认会话指向目标组织），然后停止操作。

Clarifying questions

澄清问题

Ask only what you cannot infer from conversation:

Which org? Confirm the target org and state plainly that content will be installed into this org (a write). For production, get explicit confirmation.

Do not re-ask for anything the user already provided; pre-populate and note "(from conversation)".

仅询问无法从对话中推断出的信息：

目标组织是哪个？确认目标组织，并明确告知用户内容将安装到该组织中（写入操作）。对于生产环境，需获得用户明确确认。

请勿重复询问用户已提供的信息；预先填充并标注“（来自对话）”。

Workflow

工作流

Sequential. Always read before you write — read the catalog and resolve the exact version before installing. Never guess a version string.

按顺序执行。始终先读取再写入——在安装前先读取目录并解析确切版本。切勿猜测版本字符串。

Step 1 — Confirm CMDB is enabled (read, gate)

步骤1——确认CMDB已启用（读取，限制）

text

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

```
200
```
→ CMDB is enabled; the response lists available bundles and their install status. Proceed.
```
403 FUNCTIONALITY_NOT_ENABLED
```
→ ambiguous — disambiguate before telling the user CMDB is off. This read enforces both the org gate and the running user's own CMDB access, so a 403 has two possible causes. Check the feature status to tell them apart:
text
```
dispatch_readonly({ "url": "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-cmdb-integration/status", "method": "GET" })
```
- ```
status != ENABLED
```
  → the CMDB feature isn't enabled. STOP and route the user to the CMDB feature-enable skill (
```
service-itsm-agentic-setup-cmdb-configure
```
  ) first.
- ```
status == ENABLED
```
  → the feature is enabled; the running user simply lacks CMDB permission sets. STOP and route the user to the CMDB access-assign skill (
```
service-itsm-agentic-setup-cmdb-access-assign
```
  ) to grant themselves CMDB access — at minimum the read set, plus Type Manager for bundle management — then retry. Do NOT send them to the feature-enable skill; CMDB is already enabled.

From the

bundleListView

response, identify the base bundle (CMDB Foundation) and note its

currentInstalledVersion

. If it is already installed at the latest version, tell the user there is nothing to do.

text

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

```
200
```
→ CMDB已启用；响应中列出了可用包及其安装状态。继续执行。
```
403 FUNCTIONALITY_NOT_ENABLED
```
→ 存在歧义——告知用户CMDB未开启前需先区分原因。此读取操作同时受组织层面限制和当前用户的CMDB访问权限限制，因此403有两种可能原因。通过功能状态检查区分：
text
```
dispatch_readonly({ "url": "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-cmdb-integration/status", "method": "GET" })
```
- ```
status != ENABLED
```
  → CMDB功能未启用。停止操作并引导用户先使用CMDB功能启用skill（
```
service-itsm-agentic-setup-cmdb-configure
```
  ）。
- ```
status == ENABLED
```
  → 功能已启用；当前用户只是缺少CMDB权限集。停止操作并引导用户使用CMDB权限分配skill（
```
service-itsm-agentic-setup-cmdb-access-assign
```
  ）为自己授予CMDB访问权限——至少需要读取权限集，加上Type Manager权限用于包管理——然后重试。请勿引导用户到功能启用skill；CMDB已启用。

从

bundleListView

响应中识别基础包（CMDB Foundation）并记录其

currentInstalledVersion

。如果已安装最新版本，告知用户无需进行任何操作。

Step 2 — Resolve the exact base version (read)

步骤2——解析基础包的确切版本（读取）

Do NOT guess or hard-code the version. Read the authoritative version from bundle details:

text

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

Read

latestVersion

from the catalog and use that string verbatim for the install — do NOT strip, add, or reformat any characters (including a leading

). The install endpoint matches the version by exact string equality against the registry, and the registry stores versions exactly as the catalog reports them (e.g.

"v3.0"

), so the value must be passed through unchanged.

You may only install the latest version. The install endpoint rejects any non-latest version (

"Target version <x> is not the latest available version"

) — it does not support installing or rolling back to an older version, so always resolve

latestVersion

and install exactly that. If

installedVersion

already equals

latestVersion

, stop — the base bundle is up to date.

If
bundles/details
returns
403 FUNCTIONALITY_NOT_ENABLED
while
bundleListView
(Step 1) returned
200
: the org gate is fine, but the running user lacks the bundle-management permission.
bundles/details
requires the Type Manager role — the Reader / Owner / Type Reader sets are not sufficient. Route the user to the CMDB access-assign skill to grant Type Manager, then retry. As a fallback,
bundleListView
already returns the base bundle's
currentInstalledVersion
and
latestVersion
, so you can resolve the version from Step 1's response if Type Manager cannot be assigned.

请勿猜测或硬编码版本。从包详情中读取权威版本：

text

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

从目录中读取

latestVersion

，并原样使用该字符串进行安装——请勿删除、添加或重新格式化任何字符（包括开头的

）。安装端点会通过与注册表的精确字符串匹配来验证版本，而注册表存储的版本与目录报告的完全一致（例如

"v3.0"

），因此必须原封不动地传递该值。

仅可安装最新版本。安装端点会拒绝任何非最新版本（错误信息：

"Target version <x> is not the latest available version"

）——它不支持安装或回滚到旧版本，因此始终要解析

latestVersion

并安装该版本。如果

installedVersion

已等于

latestVersion

，则停止操作——基础包已是最新版本。

如果
bundles/details
返回
403 FUNCTIONALITY_NOT_ENABLED
但步骤1的
bundleListView
返回
200
：组织层面的限制已满足，但当前用户缺少包管理权限。
bundles/details
需要Type Manager角色——Reader/Owner/Type Reader权限集不足以访问。引导用户使用CMDB权限分配skill授予Type Manager权限，然后重试。作为备选方案，
bundleListView
已返回基础包的
currentInstalledVersion
和
latestVersion
，因此如果无法分配Type Manager权限，可从步骤1的响应中解析版本。

Step 3 — Confirm with the user (before the write)

步骤3——向用户确认（写入前）

Show the base bundle name, the version to be installed, and the target org. Get explicit confirmation before the write. State plainly that this installs out-of-the-box CMDB content into the org.

展示基础包名称、待安装版本和目标组织。在写入操作前获得用户明确确认。明确说明这会将开箱即用的CMDB内容安装到组织中。

Step 4 — Install the base bundle (write)

步骤4——安装基础包（写入）

Call

discover(query="cmdb bundle installation")

then

describe(id=<bundleInstallation operation id>)

to confirm the input schema, then install:

text

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

Both

bundleIdentifier

and

version

are required, and

version

must be the catalog's

latestVersion

string passed through unchanged. A

success: true

response means the installation was initiated — it may complete asynchronously.

调用

discover(query="cmdb bundle installation")

，然后调用

describe(id=<bundleInstallation操作ID>)

确认输入架构，接着执行安装：

text

dispatch({ "url": "/services/data/v67.0/connect/cmdb/bundleInstallation", "method": "POST", "body": { "bundleIdentifier": "base", "version": "<步骤2中的latestVersion，原样>" } })

bundleIdentifier

和

version

都是必填项，且

version

必须是原封不动传递的目录

latestVersion

字符串。

success: true

响应表示安装已启动——可能会异步完成。

Step 5 — Verify (read — do NOT trust the install response alone)

步骤5——验证（读取——请勿仅信任安装响应）

Re-read bundle details and confirm the base bundle now reports the installed version:

text

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

installedVersion

should equal the version you installed. If installation is async and it has not updated yet, tell the user it is in progress and how to re-check.

重新读取包详情并确认基础包现在显示已安装的版本：

text

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

installedVersion

应等于您安装的版本。如果安装是异步的且尚未更新，告知用户安装正在进行中以及如何重新检查。

Rules / Constraints

规则/约束

Constraint	Rationale
Read `bundleListView` first as the enablement gate	A 403 here means either CMDB isn't enabled or the user lacks CMDB access — disambiguate via feature status before acting
Resolve the version from `bundles/details` ; never guess; pass `latestVersion` verbatim	The install endpoint matches the version by exact string equality against the registry, which stores it exactly as the catalog reports (e.g. `"v3.0"` ) — do not strip or reformat any characters
Install only the latest version	The endpoint rejects any non-latest version ( `"Target version <x> is not the latest available version"` ); it cannot install or roll back to an older version
Install `base` only	This skill is scoped to the CMDB Foundation base bundle; optional add-ons are out of scope
Confirm the target org and the install with the user	Installing content is a real, hard-to-reverse write on a live org
Skip if already installed at latest	Avoid redundant installs; report "already up to date"
Treat `success: true` as "initiated"; verify separately	Installation can be asynchronous
Never expose internal jargon to the user	Keep record IDs, HTTP status codes (403/400/500), API error codes ( `FUNCTIONALITY_NOT_ENABLED` , …), endpoint names ( `bundleListView` , `bundles/details` , `bundleInstallation` ), developer names, and tooling internals ( `dispatch` , `headless-360` ) out of user-facing output. Use bundle names and versions and plain language

约束	理由
先读取 `bundleListView` 作为启用限制	此处的403意味着CMDB未启用或用户无CMDB访问权限——操作前需通过功能状态区分原因
从 `bundles/details` 解析版本；切勿猜测；原样传递 `latestVersion`	安装端点通过与注册表的精确字符串匹配验证版本，注册表存储的版本与目录报告的完全一致（例如 `"v3.0"` ）——请勿删除或重新格式化任何字符
仅安装最新版本	端点会拒绝任何非最新版本（错误信息： `"Target version <x> is not the latest available version"` ）；无法安装或回滚到旧版本
仅安装 `base` 包	本skill的范围仅限于CMDB Foundation基础包；可选附加包不在范围内
向用户确认目标组织和安装操作	安装内容是对实时组织的真实写入操作，难以撤销
如果已安装最新版本则跳过	避免重复安装；告知用户“已是最新版本”
将 `success: true` 视为“已启动”；单独进行验证	安装可能是异步的
切勿向用户暴露内部术语	用户可见的输出中不得包含记录ID、HTTP状态码（403/400/500）、API错误代码（ `FUNCTIONALITY_NOT_ENABLED` 等）、端点名称（ `bundleListView` 、 `bundles/details` 、 `bundleInstallation` ）、开发者名称和工具内部信息（ `dispatch` 、 `headless-360` ）。使用包名称、版本和通俗易懂的语言

Verification checklist

验证清单

```
bundleListView
```
returned
```
200
```
(CMDB is enabled and the user has access)?
Resolved
```
latestVersion
```
for
```
base
```
from
```
bundles/details
```
(not guessed)?
Skipped if already at the latest version?
Confirmed the target org + install with the user before writing?
```
bundleInstallation
```
returned
```
success: true
```
?
Verified
```
installedVersion
```
matches (or reported async in-progress)?

```
bundleListView
```
返回
```
200
```
（CMDB已启用且用户有访问权限）？
从
```
bundles/details
```
解析了
```
base
```
包的
```
latestVersion
```
（未猜测）？
如果已是最新版本则跳过操作？
写入前向用户确认了目标组织和安装操作？
```
bundleInstallation
```
返回
```
success: true
```
？
验证
```
installedVersion
```
匹配（或报告异步安装进行中）？

Output expectations

输出预期

text

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.

Keep internal jargon out of user-facing output (no record IDs, HTTP status codes, error codes, or endpoint names). If any step fails, stop and tell the user — in plain language — what didn't succeed and what it means for them (e.g. "CMDB isn't turned on for this org yet, so the content can't be installed" rather than echoing a 403 code), then point to the fix.

text

CMDB包部署——完成（通过service-itsm-agentic-setup-cmdb-bundle-deploy）

目标组织：<org>

  包：   CMDB Foundation（基础版）
  版本：  <version>
  状态：   安装已启动——成功

CMDB现已安装基础内容。结合已启用的功能和已分配的用户访问权限，CMDB已完全就绪。

用户可见的输出中不得包含内部术语（无记录ID、HTTP状态码、错误代码或端点名称）。如果任何步骤失败，停止操作并以通俗易懂的语言告知用户操作失败的内容及其影响（例如，“此组织尚未开启CMDB功能，因此无法安装内容”，而非回显403代码），然后指出解决方法。

Common failures (surface these in plain language)

常见故障（以通俗易懂的语言呈现）

Symptom	Likely cause	What to tell the user
`403` on the catalog read and feature not enabled	CMDB feature not enabled for the org	CMDB must be turned on for the org first; that's a separate setup step — point to the feature-enable skill
`403` on the catalog read but feature is enabled	Feature is on; the running user lacks CMDB access (this read enforces user-level access too)	Grant the user CMDB access first (a separate setup step), then try again — the feature itself is already on
`403` on the version read but the catalog read succeeded	The user lacks the CMDB bundle-management role (Type Manager)	Grant the user the CMDB Type Manager role (a separate access step), then retry; the org itself is set up correctly
Install rejected — bundle/version doesn't exist	Wrong version string	Re-read the catalog and use the exact latest version it reports
Install reported success but the version hasn't changed	Installation is running in the background	It's in progress; check again shortly to confirm it finished
Downstream error on install	Temporary platform dependency issue	Try again; if it keeps failing, this needs Salesforce support
Connection/authentication error	The org connection isn't set up or has expired	Re-authenticate the org connection and confirm it points at the intended org, then retry

症状	可能原因	告知用户的内容
目录读取返回 `403` 且功能未启用	组织未启用CMDB功能	必须先为组织开启CMDB功能，这是一个单独的配置步骤——引导用户使用功能启用skill
目录读取返回 `403` 但功能已启用	功能已开启，但当前用户无CMDB访问权限（此读取操作也会验证用户级访问权限）	先为用户授予CMDB访问权限（单独的配置步骤），然后重试——功能本身已开启
版本读取返回 `403` 但目录读取成功	用户缺少CMDB包管理角色（Type Manager）	为用户授予CMDB Type Manager角色（单独的权限步骤），然后重试——组织本身已配置正确
安装被拒绝——包/版本不存在	版本字符串错误	重新读取目录并使用其报告的精确最新版本
安装报告成功但版本未更改	安装在后台运行	安装正在进行中；稍后重新检查确认是否完成
安装时出现下游错误	临时平台依赖问题	重试；如果持续失败，需要联系Salesforce支持
连接/认证错误	组织连接未配置或已过期	重新认证组织连接并确认其指向目标组织，然后重试

Cross-skill integration

跨skill集成

When	Skill
The org CMDB feature is not enabled yet (org gate still closed)	`service-itsm-agentic-setup-cmdb-configure` (Layers 0–2 — enable the feature first, then return here)
The running user lacks CMDB access, or lacks Type Manager for bundle management	`service-itsm-agentic-setup-cmdb-access-assign` (Layer 3 — grant the user CMDB access, including Type Manager, then return here)

场景	Skill
组织CMDB功能尚未启用（组织层面限制仍未解除）	`service-itsm-agentic-setup-cmdb-configure` （第0-2层——先启用功能，再返回此skill）
当前用户缺少CMDB访问权限，或缺少包管理所需的Type Manager角色	`service-itsm-agentic-setup-cmdb-access-assign` （第3层——为用户授予CMDB访问权限，包括Type Manager，再返回此skill）

Reference file index

参考文件索引

File	When to read
`references/mcp-invocation.md`	Exact `mcp__headless-360__*` call shapes for the bundle catalog + install calls, response envelopes, the install schema lookup, and the error table

文件	读取时机
`references/mcp-invocation.md`	包目录+安装调用的确切 `mcp__headless-360__*` 调用格式、响应信封、安装架构查找和错误表