service-itsm-agentic-setup-cmdb-access-assign

ユーザーに CMDB アクセスを割り当てる（Service Cloud ITSM）

特定のユーザーに、ライセンスに紐づく CMDB 権限セットとその権限セットライセンスを割り当て、CMDB（構成管理データベース）データの読み取りと操作を行う権限を付与します。すべての呼び出しは、4 つのメタツール（discover、describe、dispatch_readonly、dispatch）を介して、Salesforce ホスト型 Headless-360 MCP サーバー（サーバーキー headless-360）で実行されます。組織は現在の MCP セッションに紐づく OAuth JWT から特定されます。このスキルが組織 ID、エイリアス、または認証情報を扱うことはありません。そのため、ユーザーごとに MCP をインストールしなくても、本番環境とサンドボックスで同じように動作します。

これは CMDB セットアップのレイヤー 3です。組織レベルの CMDB ゲートがすでに解除されている（機能が ENABLED になっている）ことを前提としています。これは別のスキル（service-itsm-agentic-setup-cmdb-configure、レイヤー 0～2）で行います。このスキルはユーザーにアクセス権を付与するものであり、組織で機能を有効化するものではありません。

このスキルで解消する問題

CMDB 機能を有効にすると組織レベルのゲートは解除されますが、一部の CMDB 読み取り（例：bundleListView）では、ユーザーレベルのアクセス権も確認されます。CMDB 権限セットが割り当てられていないユーザーは、組織で機能が正しく ENABLED になっていても、403 FUNCTIONALITY_NOT_ENABLED（「このユーザーでは有効になっていません」）を受け取ります。このスキルは、そのユーザーに CMDB 権限セットを割り当て、読み取りが成功するようにします。

組織の機能が有効になっていない場合、このスキルは何も行いません。 組織レベルの CMDB 機能が ENABLED になるまで、ユーザーレベルのアクセス権は効果がありません。組織のゲートがまだ閉じている場合は、処理を中止し、先に組織で CMDB 機能を有効にする必要があることをユーザーに伝えてください。末尾のスキル間の注記を参照してください。

4 つの CMDB 権限セット

いずれもライセンスに紐づく標準権限セットです。割り当てには対応する権限セットライセンス（PSL）も必要であり、このスキルで割り当てます。

役割	権限セット（Name）	対応する PSL（DeveloperName）	付与される権限
リーダー	ItSrvcCnfgItmReadPermissionSet	ItSrvcCnfgItmReadPsl	CMDB 構成アイテムの読み取り
オーナー	ItSrvcCnfgItmOwnerPermissionSet	ItSrvcCnfgItmOwnerPsl	構成アイテムの所有／編集
タイプリーダー	ItSrvcCnfgItmTypReadPermissionSet	ItSrvcCnfgItmTypReadPsl	構成アイテムタイプの読み取り
タイプマネージャー	ItSrvcCnfgItmTypManagerPermissionSet	ItSrvcCnfgItmTypMgrPsl	構成アイテムタイプの管理

読み取り専用の CMDB アクセスには、リーダー（＋タイプリーダー）が最小限のセットです。CMDB レコードを編集するユーザーにはオーナーを追加し、タイプカタログを管理するユーザーにはタイプマネージャーを追加してください。ユーザーが役割を指定していない場合は、確認してください（「確認事項」を参照）。閲覧者にはリーダー＋タイプリーダーをデフォルトとして割り当てます。

バンドル管理にはタイプマネージャーが必要です。 ユーザーの目的がCMDB コンテンツバンドルのインストールまたは管理である場合（または GET /connect/cmdb/bundles/details など、バンドル管理の読み取りで 403 が発生した場合）、それを解消する役割はタイプマネージャーです。リーダー／オーナー／タイプリーダーのみを持つユーザーは、バンドル操作で引き続き 403 FUNCTIONALITY_NOT_ENABLED を受け取ります。バンドルをデプロイまたは管理するユーザーには、対応する PSL ItSrvcCnfgItmTypMgrPsl とともにタイプマネージャーを割り当ててください。

対象範囲

• 対象：対象ユーザーの特定、要求された CMDB 権限セットの特定、既存の割り当ての確認、権限セットライセンスと権限セットの割り当て、および検証。
• 対象外：CMDB 機能の有効化／CMDB テナントのプロビジョニング（レイヤー 0～2 — service-itsm-agentic-setup-cmdb-configure）、コンテンツバンドルのインストール、CMDB レコードの CRUD、カスタム権限セットの作成、組織権限やエディションの変更。

仕組み

すべての操作は 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 — インデックス化された操作カタログを対象にしたセマンティック検索です。このスキルで使用する標準の /query および /sobjects/... REST ルートは、常にインデックス化されているとは限りません。そのため、見つからなくてもルートが存在しないとは限りません。正確なパスを直接ディスパッチしてください（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 接続を再認証し、セッションが意図した組織を指していることを確認するようユーザーに伝えてから、処理を中止してください。

---

確認事項

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

• どのユーザーですか？ ユーザー名（または、正確に 1 人のユーザーに特定できる名前／メールアドレス）。「アクセス権を付与して」／「現在のユーザーに」と依頼された場合は、実行ユーザーを特定してください。
• どのロールですか？ Reader、Owner、Type Reader、Type Manager、または「読み取り専用アクセス」（→ Reader + Type Reader）。指定がなければ、閲覧者には Reader + Type Reader をデフォルトで割り当ててください。ユーザーが CMDB のコンテンツバンドルをインストールまたは管理する場合（またはバンドル管理に関する 403 を解決する場合）は、Type Manager を含めてください。これがないと、バンドル操作は 403 になります。
• どの組織ですか？ 対象組織を確認し、パーミッションセットの割り当ては書き込みであるため、この組織が変更されますとはっきり伝えてください。本番環境の場合は、明示的な確認を得てください。

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

---

ワークフロー

必ず書き込みの前に読み取りを行ってください。割り当ての前に読み取り専用のチェックを実行してください。割り当てはすべてユーザーごとに行われ、冪等です。重複した割り当てはエラーではなく、割り当て済みとして扱ってください。

手順 1 — 組織レベルの CMDB 機能が有効になっていることを確認する（読み取り専用、前提条件）

組織側のゲートが解除されていなければ、ユーザーアクセスに意味はありません。機能のステータスを読み取ります。

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

• status == ENABLED → 次に進みます。
• status != ENABLED（または呼び出しで 403 FUNCTIONALITY_NOT_ENABLED が返された場合）→ 停止します。ユーザーに、ユーザーへアクセス権を付与する前に組織で CMDB を有効にする必要があると、平易な言葉で伝え、CMDB 機能を有効化するスキルを案内してください（スキル間の注記を参照）。何も割り当てないでください。

手順 2 — 対象ユーザーを特定する（読み取り）

「現在のユーザー」／「自分」／「自分のユーザー」の場合（USER_ID() は使用しないでください。Apex 専用であり、REST クエリ API では拒否されます。また、/chatter/users/me や /connect/user-profiles/me に依存しないでください。Chatter／Communities がオフの場合、これらは 403 FUNCTIONALITY_NOT_ENABLED を返します）。代わりに API ルートを読み取り、identity URL を解析します。

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

応答の identity フィールドは、/<orgId>/<userId> で終わる URL です（ユーザー ID は最後のパスセグメントで、005 から始まります）。その ID を対象ユーザーとして直接使用するか、次のように確認してください。

dispatch_readonly({ "url": "/services/data/v67.0/query", "method": "GET", "queryParams": { "q": "SELECT Id, Username, Name, IsActive FROM User WHERE Id = '<userId>'" } })

名前が指定されたユーザーの場合（ユーザー名／メールアドレスが指定されている場合）：

dispatch_readonly({ "url": "/services/data/v67.0/query", "method": "GET", "queryParams": { "q": "SELECT Id, Username, Name, IsActive FROM User WHERE Username = '<username>'" } })

• 有効なユーザーがちょうど 1 人 → Id を取得します。
• 該当する結果が 0 件 → 停止し、一致するユーザーが見つからなかったことをユーザーに伝えて、ユーザー名の確認を依頼します。
• 複数件 → 停止し、候補（Name + Username）を一覧表示して、どのユーザーかを尋ねます。
• ユーザーが無効 → ユーザーに警告します。割り当ては続行できますが、アクセスが有効になるのはユーザーが有効になってからです。

ステップ 3 — 要求された権限セットを解決する（読み取り）

要求された各ロールについて、権限セットと、それを支えるライセンスを解決します。

dispatch_readonly({ "url": "/services/data/v67.0/query", "method": "GET", "queryParams": { "q": "SELECT Id, Name, LicenseId FROM PermissionSet WHERE Name = '<psName>'" } })

上の表の Name の値を使用します。各 Id（権限セット）と LicenseId（割り当てる PSL）を取得します。権限セットが見つからない場合、この組織には CMDB ライセンスがない可能性があります。そこで処理を停止し、この組織では CMDB が設定されていないようだと報告してください。

ステップ 4 — 既存の割り当てを確認する（読み取り — 冪等性、権限セットグループ対応）

ロールを付与する方法は 2 通りあり、この確認では どちらも受け入れる必要があります。そうしないと、すでに付与されているロールを未割り当てと誤判定し、誤って割り当てを求めることになります。

1. 直接 — ロール固有の権限セットを PermissionSetId に持つ PermissionSetAssignment。
2. 権限セットグループ（PSG）経由 — ロールの権限セットが、ユーザーに割り当てられている PSG の メンバーである場合。この場合、ユーザーの PermissionSetAssignment 行には PermissionSetGroupId が設定され、PermissionSetId にはグループ内部の 集約セットが入ります。メンバー権限セットは入りません。そのため、PermissionSetId = '<psId>' で絞り込むクエリは、ユーザーが実質的にロールを保持していても 0 件を返します。

ロールごとに権限セットの読み取りを 両方実行してください。いずれかの結果が totalSize >= 1 であれば、権限セットは割り当て済みです（2 つ目はトップレベルのセミジョインです。OR の中にネストすると MALFORMED_QUERY が発生します）。

dispatch_readonly({ "url": "/services/data/v67.0/query", "method": "GET", "queryParams": { "q": "SELECT Id FROM PermissionSetAssignment WHERE AssigneeId = '<userId>' AND PermissionSetId = '<psId>'" } })
dispatch_readonly({ "url": "/services/data/v67.0/query", "method": "GET", "queryParams": { "q": "SELECT Id FROM PermissionSetAssignment WHERE AssigneeId = '<userId>' AND PermissionSetGroupId IN (SELECT PermissionSetGroupId FROM PermissionSetGroupComponent WHERE PermissionSetId = '<psId>')" } })

次に、それを支えるライセンスを確認します（ロールを含む PSG もそれを支える PSL を直接割り当てるため、この読み取り 1 回で PSG のケースも確認できます）。

dispatch_readonly({ "url": "/services/data/v67.0/query", "method": "GET", "queryParams": { "q": "SELECT Id FROM PermissionSetLicenseAssign WHERE AssigneeId = '<userId>' AND PermissionSetLicenseId = '<pslId>'" } })

いずれかの経路で権限セットが存在し、かつライセンスの読み取り結果が totalSize >= 1 の場合、そのロールは すでに割り当て済みです。書き込みをスキップし、すでに完了したものとして記録してください。本当に不足しているものだけを割り当て、ユーザーが PSG 経由ですでに保持しているメンバー権限セットを直接再割り当てしないでください。

ステップ 5 — 権限セットライセンスを割り当ててから、権限セットを割り当てる（書き込み — 先に確認）

対象ユーザー、組織、ロールをユーザーに確認してから、不足している各ロールについて、まず PSL を割り当て、次に権限セットを割り当てます。

dispatch({ "url": "/services/data/v67.0/sobjects/PermissionSetLicenseAssign", "method": "POST", "body": { "AssigneeId": "<userId>", "PermissionSetLicenseId": "<pslId>" } })

dispatch({ "url": "/services/data/v67.0/sobjects/PermissionSetAssignment", "method": "POST", "body": { "AssigneeId": "<userId>", "PermissionSetId": "<psId>" } })

• 201 → 割り当て済みです。
• 400 DUPLICATE_VALUE → ユーザーはすでに保持していました。失敗ではなく、成功（冪等）として扱います。
• ライセンス上限エラー（例：INSUFFICIENT_ACCESS／利用可能なシートがない）→ そのロールの処理を停止します。CMDB ライセンスに空きシートがないことと、使用中の数をユーザーに伝えてください（シート数のクエリについては references/mcp-invocation.md を参照）。再試行しないでください。

ステップ 6 — 検証する（読み取り — POST の応答だけを信用しない）

ステップ 4 の読み取りを再実行します。直接および PSG 経由の権限セット確認の両方と、ライセンスの確認を行ってください。権限セットがいずれかの経路で存在し、かつそれを支えるライセンスも読み取れた場合にのみ、そのロールを完了とします。ロールごとに、割り当て済み／すでに保持していた、のいずれかを報告してください。この読み取りで存在が確認できたロールのみを完了として数えます。

---

ルール／制約事項

制約事項	理由
割り当てる前に、組織の機能が ENABLED であることを確認する	組織レベルの CMDB ゲートが解除されるまで、ユーザーアクセスは有効になりません。先に割り当てると、何も起きないのに完了したかのような誤解を招きます
書き込みを行う前に、ユーザーが該当するレコードに一意に特定できることを確認する	誤ったユーザー（または特定できないユーザー）に割り当てると、元に戻すのが難しく、セキュリティ上の懸念があります
割り当てのたびに、既存の割り当てを読み取る	割り当てはユーザーごとに行われます。再割り当てすると DUPLICATE_VALUE が発生するため、既存の割り当てはスキップします
権限セットの前に PSL を割り当てる	権限セットはライセンスに紐づいています。割り当てを有効にするには、先にライセンスシートを確保する必要があります
DUPLICATE_VALUE は成功として扱う	これは、ユーザーがすでにそのアクセス権を持っていることを意味します。べき等であり、エラーではありません
権限セットを作成または編集しない	このスキルでは、標準の CMDB 権限セットを「割り当てる」だけです。権限セットの作成は対象外です
対象の組織、ユーザー、および各書き込みについて、ユーザーに確認する	これらは、稼働中の組織でユーザーにデータアクセス権を付与する実際の変更です
内部用語をユーザーに見せない	レコード ID、HTTP ステータスコード（403／400／…）、API エラーコード（FUNCTIONALITY_NOT_ENABLED、DUPLICATE_VALUE）、オブジェクト名（PermissionSetLicenseAssign）、開発者名（ItSrvcCnfgItmReadPsl）、ツールの内部情報（dispatch、headless-360）をユーザー向けの出力に含めないでください。人が理解しやすい役割名と平易な言葉を使ってください

---

検証チェックリスト

• 割り当てる前に、組織の CMDB 機能が ENABLED であることを確認したか？
• 対象ユーザーを一意に特定したか？
• 要求された各役割について、権限セットと、それを支えるライセンスを特定したか？
• 書き込みの前に、既存の割り当てを確認したか（べき等性）？
• 要求された各役割について、権限セットとそのライセンスの両方を割り当てたか？
• 書き込み後に読み取りを行って検証したか（POST レスポンスだけに頼らず）？
• 事前に、対象の組織、ユーザー、および各書き込みについてユーザーの確認を得たか？

---

出力に関する要件

CMDB Access Assignment — Complete (via service-itsm-agentic-setup-cmdb-access-assign)

Target org: <org>
User: <name> (<username>)

  Configuration Item Reader ......... Assigned
  Configuration Item Type Reader .... Already had access

This user can now read CMDB data in this org. If they still can't, confirm the org's
CMDB feature is turned on (that's a separate setup step).

ユーザー向けの出力に内部用語を含めないでください（レコード ID、HTTP ステータスコード、エラーコード、オブジェクト名、開発者名は記載しません）。いずれかの手順に失敗した場合は、そこで停止し、どの処理が成功しなかったのか、ユーザーにとって何を意味するのかを平易な言葉で伝えてください。生のエラー（例：403 や FUNCTIONALITY_NOT_ENABLED）をそのまま伝えるのではなく、それが何を意味するのか（「この組織では、まだ CMDB が有効になっていません」）に置き換えてください。

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

症状	考えられる原因	ユーザーに伝える内容
機能のステータスが ENABLED ではない（またはステータスの読み取りで 403 が返る）	組織レベルの CMDB ゲートが解除されていない	まず組織で CMDB を有効にする必要があります。これは別のセットアップ手順です。機能を有効化するスキルを案内してください
権限セットが見つからない	組織に CMDB ライセンスがない、またはセットアップされていない	この組織では CMDB を利用できないようです。ライセンスがあり、有効になっていることを確認してください
割り当て後、機能が ENABLED なのに、バンドル管理の読み取り（例：bundles/details、bundleListView）で 403 FUNCTIONALITY_NOT_ENABLED` が返る	ユーザーは Reader／Owner／Type Reader を保持しているものの、Type Manager を保持していない — バンドル操作にはこのロールが必要です	Type Manager を割り当ててください。このロールは CMDB のバンドル管理に必要です。他の CMDB ロールではバンドル操作を実行できません
スキルが CMDB ロールの不足を検出して割り当てを求めるが、ユーザーはすでにそのロールを持っている（例：権限セットグループ経由）	冪等性チェックでは直接割り当てられた権限セットのみを確認し、グループ経由の権限付与を見落としていました — Step 4 でグループへの所属も確認するよう修正済みです	ユーザーはすでに権限セットグループ経由でそのアクセス権を持っています。そのロールは付与済みとして扱ってください。新たな割り当ては不要です
割り当て時に 400 DUPLICATE_VALUE が返る	ユーザーはすでにそのアクセス権を持っている	エラーではありません。そのロールはすでに割り当て済みと伝えてください
割り当て時にライセンス上限／シート不足エラーが返る	CMDB 権限セットのライセンスシートを使い切っている	使用中と利用可能なシート数を伝えてください。割り当てるには、シートが空くか、ライセンスが追加される必要があります
dispatch* の認証エラー	headless-360 MCP セッションが認証されていない、またはトークンの有効期限が切れている	headless-360 MCP 接続を再認証し、セッションが意図した組織を参照していることを確認してください

---

スキル間連携

条件	スキル
組織の CMDB 機能がまだ有効になっていない（組織ゲートがまだ閉じている）	service-itsm-agentic-setup-cmdb-configure（Layers 0–2 — まず機能を有効にしてから、ここに戻ってください）
ユーザーが CMDB の基本コンテンツバンドルをインストールする必要がある	service-itsm-agentic-setup-cmdb-bundle-deploy（Layer 4 — コンテンツ。ユーザーアクセスとは別です）。このスキルでバンドル管理を読み取るには、ユーザーが Type Manager を保持している必要があるため、まずここで割り当ててください

---

参照ファイル一覧

ファイル	読むタイミング
references/mcp-invocation.md	すべての読み取りと書き込みに使う dispatch* の正確な URL／メソッド／本文、レスポンスのエンベロープ、ライセンスシートのクエリ、エラー表を確認するとき