analyzing-omnistudio-dependencies

analyzing-omnistudio-dependencies：OmniStudio クロスコンポーネント分析

名前空間の検出、依存関係のマッピング、OmniStudio コンポーネントスイート全体にわたる影響分析を専門とする、熟練した OmniStudio アナリストです。OmniScript、FlexCard、Integration Procedure、Data Mapper の組織全体のインベントリを実行し、依存関係グラフの自動構築と Mermaid による可視化を行います。

---

対象範囲

• 対象：名前空間の検出（Core / vlocity_cmt / vlocity_ins）、組織全体のコンポーネントインベントリ、依存関係グラフの構築、影響分析、Mermaid 図の生成
• 対象外：OmniScript の作成または変更（building-omnistudio-omniscript を使用）、FlexCard の構築（building-omnistudio-flexcard を使用）、Integration Procedure の作成（building-omnistudio-integration-procedure を使用）、Data Mapper の設定（building-omnistudio-datamapper を使用）

---

必須入力

開始前に、次の情報をユーザーに確認するか、推定してください。

入力	指定がない場合のデフォルト
対象 org のエイリアス	ユーザーに確認
分析範囲	組織全体（OmniStudio のすべてのコンポーネントタイプ）
影響分析の対象コンポーネント	なし（まず全体のインベントリを作成）
希望する出力形式	3 種類すべて：Mermaid 図 + JSON サマリー + 人が読めるレポート

---

出力内容

各分析の実行では、次のうち 1 つ以上を生成します。

1. 名前空間の検出結果 — 有効な名前空間（Core / vlocity_cmt / vlocity_ins / 未インストール）
2. コンポーネントインベントリ — OmniScript、Integration Procedure、FlexCard、Data Mapper の数（有効とドラフト）
3. 依存関係グラフ — エッジタイプのラベルが付いた、すべての OmniStudio コンポーネント間の有向エッジ
4. Mermaid 図 — ドキュメントにコピーして貼り付けられる Mermaid の graph LR ブロック
5. JSON サマリー — 名前空間、コンポーネント、依存関係、影響分析を含む機械可読形式
6. 人が読めるレポート — コンポーネント数、エッジ数、循環参照、最も依存されているコンポーネントをまとめたプレーンテキストのサマリー
7. 循環参照の警告 — 検出された各循環について、サイクルのパスとリスクに関する説明

---

主な役割

1. 名前空間の検出：組織が Core（Industries）、vlocity_cmt（Communications, Media & Energy）、vlocity_ins（Insurance & Health）のどの名前空間を使用しているかを特定します
2. 依存関係の分析：循環参照の検出を行いながら BFS トラバーサルを使用し、コンポーネント間の依存関係を表す有向グラフを構築します
3. 影響分析：特定の OmniScript、IP、FlexCard、Data Mapper が変更されたときに、どのコンポーネントが影響を受けるかを特定します
4. Mermaid による可視化：ドキュメント作成やレビュー用に、Mermaid 構文で依存関係図を生成します
5. 組織全体のインベントリ：すべての OmniStudio コンポーネントをタイプ、ステータス、言語、バージョンごとに一覧化します

---

重要：オーケストレーションの順序

複数の OmniStudio スキルが関係する場合は、次の依存関係チェーンに従ってください。

analyzing-omnistudio-dependencies → building-omnistudio-datamapper → building-omnistudio-integration-procedure → building-omnistudio-omniscript → building-omnistudio-flexcard

このスキルは最初に実行し、後続のスキルが使用する名前空間のコンテキストと依存関係マップを確立します。

---

主な知見

知見	詳細
3 つの名前空間が共存します	Core（OmniProcess）、vlocity_cmt（vlocity_cmt__OmniScript__c）、vlocity_ins（vlocity_ins__OmniScript__c）
依存関係は JSON に保存されます	PropertySetConfig（要素）、Definition（FlexCard）、InputObjectName/OutputObjectName（Data Mapper）
循環参照が発生する可能性があります	埋め込み呼び出しを介した OmniScript A → IP B → OmniScript A
FlexCard のデータソースにはタイプがあります	DataSourceConfig JSON 内で dataSource.type === 'IntegrationProcedures'（複数形）
有効とドラフトの区別が重要です	ランタイムの依存関係チェーンに含まれるのは、有効なコンポーネントのみです

---

ワークフロー（4 フェーズパターン）

フェーズ 1：名前空間の検出

目的：コンポーネントのメタデータをクエリする前に、組織が使用している OmniStudio の名前空間を特定します。

検出アルゴリズム — クエリが成功するまで、次の順にオブジェクトを確認します。

1. Core（Industries 名前空間）：

   SELECT COUNT() FROM OmniProcess
   

   成功した場合、組織は Core 名前空間を使用しています（API 234.0 以降／Spring '22 以降）。

2. vlocity_cmt（Communications, Media & Energy）：

   SELECT COUNT() FROM vlocity_cmt__OmniScript__c
   

3. vlocity_ins（Insurance & Health）：

   SELECT COUNT() FROM vlocity_ins__OmniScript__c
   

いずれも成功しない場合、組織に OmniStudio はインストールされていません。

名前空間検出用 CLI コマンド：

# Core namespace probe
sf data query --query "SELECT COUNT() FROM OmniProcess" --target-org myorg --json 2>/dev/null

# vlocity_cmt namespace probe
sf data query --query "SELECT COUNT() FROM vlocity_cmt__OmniScript__c" --target-org myorg --json 2>/dev/null

# vlocity_ins namespace probe
sf data query --query "SELECT COUNT() FROM vlocity_ins__OmniScript__c" --target-org myorg --json 2>/dev/null

結果の評価：クエリが成功した場合（JSON に totalSize があり、終了コードが 0）、その名前空間が確認されます。クエリが失敗した場合（INVALID_TYPE または sObject type not found）、その名前空間は存在しません。

参照：references/namespace-guide.md で、3 つすべての名前空間におけるオブジェクトとフィールドの完全なマッピングを確認できます。

---

フェーズ 2：コンポーネントの検出

目的：組織内のすべての OmniStudio コンポーネントの一覧を作成します。

検出した名前空間を使用して、各コンポーネントタイプをクエリします。

OmniScripts（Core の例。大規模な組織では LIMIT/OFFSET を使用してページネーションします）：

SELECT Id, Type, SubType, Language, IsActive, VersionNumber,
       PropertySetConfig, LastModifiedDate
FROM OmniProcess
WHERE IsIntegrationProcedure = false
ORDER BY Type, SubType, Language, VersionNumber DESC
LIMIT 200

Integration Procedures（Core の例）：

SELECT Id, Type, SubType, Language, IsActive, VersionNumber,
       PropertySetConfig, LastModifiedDate
FROM OmniProcess
WHERE IsIntegrationProcedure = true
ORDER BY Type, SubType, Language, VersionNumber DESC
LIMIT 200

FlexCards（Core の例）：

SELECT Id, Name, IsActive, DataSourceConfig, PropertySetConfig,
       AuthorName, LastModifiedDate
FROM OmniUiCard
ORDER BY Name
LIMIT 200

IMPORTANT：OmniUiCard オブジェクトには Definition フィールドがありません。データソースのバインディングには DataSourceConfig を、カードのレイアウト／状態の設定には PropertySetConfig を使用してください。

Data Mappers（Core の例）：

SELECT Id, Name, IsActive, Type, LastModifiedDate
FROM OmniDataTransform
ORDER BY Name
LIMIT 200

Data Mapper Items（オブジェクト依存関係の抽出用）：

SELECT Id, OmniDataTransformationId, InputObjectName, OutputObjectName,
       InputObjectQuerySequence
FROM OmniDataTransformItem
WHERE OmniDataTransformationId IN ({datamapper_ids})

IMPORTANT：外部キーのフィールドは OmniDataTransformationId（「Transformation」全体）であり、OmniDataTransformId ではありません。

CLI コマンドのパターン：

sf data query --query "SELECT Id, Type, SubType, Language, IsActive FROM OmniProcess WHERE IsIntegrationProcedure = false" \
  --target-org myorg --json

---

フェーズ 3：依存関係の分析

目的：コンポーネントのメタデータを解析し、有向依存関係グラフを作成します。

アルゴリズム：循環検出を伴う BFS

1. Initialize empty graph G and visited set V
2. For each root component C:
   a. Enqueue C into work queue Q
   b. While Q is not empty:
      i.   Dequeue component X from Q
      ii.  If X is in V, record circular reference and skip
      iii. Add X to V
      iv.  Parse X's metadata for dependency references
      v.   For each dependency D found:
           - Add edge X → D to graph G
           - If D is not in V, enqueue D into Q
3. Return graph G and any circular references detected

要素タイプ → 依存関係の抽出

OmniScript と IP の要素は、PropertySetConfig JSON フィールドに参照を格納します。各要素を解析して依存関係を抽出します。

要素タイプ	PropertySetConfig 内の JSON パス	依存先
DataRaptor Transform Action	bundle、bundleName	Data Mapper（名前で指定）
DataRaptor Turbo Action	bundle、bundleName	Data Mapper（名前で指定）
Remote Action	remoteClass、remoteMethod	Apex Class.Method
Integration Procedure Action	integrationProcedureKey	IP（Type_SubType）
OmniScript Action	omniScriptKey または Type/SubType	OmniScript（Type_SubType）
HTTP Action	httpUrl、httpMethod	外部エンドポイント（URL）
DocuSign Envelope Action	docuSignTemplateId	DocuSign テンプレート
Apex Remote Action	remoteClass	Apex Class

PropertySetConfig の解析：

For each OmniProcessElement:
  1. Read PropertySetConfig (JSON string)
  2. Parse JSON
  3. Check element.Type against extraction table
  4. Extract referenced component name/key
  5. Resolve reference to an OmniProcess/OmniDataTransform record
  6. Add edge: parent component → referenced component

FlexCard のデータソース解析

FlexCard は、データソースの設定を DataSourceConfig JSON フィールドに格納します（OmniUiCard には Definition フィールドがないため、使用しません）。

Parse DataSourceConfig JSON:
  1. Access dataSource object (singular, not array)
  2. For each dataSource where type === 'IntegrationProcedures' (note: PLURAL):
     - Extract dataSource.value.ipMethod (IP Type_SubType)
     - Add edge: FlexCard → Integration Procedure
  3. For each dataSource where type === 'ApexRemote':
     - Extract dataSource.value.className
     - Add edge: FlexCard → Apex Class
  4. For childCard references, parse PropertySetConfig:
     - Add edge: FlexCard → child FlexCard

IMPORTANT：IP のデータソースタイプは IntegrationProcedures（複数形で P は大文字）であり、IntegrationProcedure ではありません。

Data Mapper のオブジェクト依存関係

Data Mapper は、アイテムを介して Salesforce オブジェクトを参照します。

For each OmniDataTransformItem:
  1. Read InputObjectName → source sObject
  2. Read OutputObjectName → target sObject
  3. Add edge: Data Mapper → sObject (read from InputObjectName)
  4. Add edge: Data Mapper → sObject (write to OutputObjectName)

参照：references/dependency-patterns.md で、依存関係の抽出ルールと例の全容を確認できます。

---

フェーズ 4：可視化とレポート

目的：依存関係グラフから、人が読みやすい出力を生成します。

出力形式 1: Mermaid 依存関係図

graph LR
    subgraph OmniScripts
        OS1["createOrder<br/>English v3"]
        OS2["updateAccount<br/>English v1"]
    end
    subgraph Integration Procedures
        IP1["fetchAccountData<br/>English v2"]
        IP2["submitOrder<br/>English v1"]
    end
    subgraph Data Mappers
        DM1["AccountExtract"]
        DM2["OrderTransform"]
    end
    subgraph FlexCards
        FC1["AccountSummaryCard"]
    end

    OS1 -->|IP Action| IP2
    OS1 -->|DR Action| DM2
    OS2 -->|IP Action| IP1
    IP1 -->|DR Action| DM1
    FC1 -->|Data Source| IP1

    style OS1 fill:#dbeafe,stroke:#1d4ed8,color:#1f2937
    style OS2 fill:#dbeafe,stroke:#1d4ed8,color:#1f2937
    style IP1 fill:#fef3c7,stroke:#b45309,color:#1f2937
    style IP2 fill:#fef3c7,stroke:#b45309,color:#1f2937
    style DM1 fill:#d1fae5,stroke:#047857,color:#1f2937
    style DM2 fill:#d1fae5,stroke:#047857,color:#1f2937
    style FC1 fill:#fce7f3,stroke:#be185d,color:#1f2937

カラースキーム:

コンポーネント種別	塗りつぶし	ストローク
OmniScript	#dbeafe (blue-100)	#1d4ed8 (blue-700)
Integration Procedure	#fef3c7 (amber-100)	#b45309 (amber-700)
Data Mapper	#d1fae5 (green-100)	#047857 (green-700)
FlexCard	#fce7f3 (pink-100)	#be185d (pink-700)
Apex Class	#e9d5ff (purple-100)	#7c3aed (purple-700)
External (HTTP)	#f1f5f9 (slate-100)	#475569 (slate-600)

出力形式 2: JSON サマリー

{
  "namespace": "Core",
  "components": {
    "omniScripts": 12,
    "integrationProcedures": 8,
    "flexCards": 5,
    "dataMappers": 15
  },
  "dependencies": [
    { "from": "OS:createOrder", "to": "IP:submitOrder", "type": "IPAction" },
    { "from": "IP:fetchAccountData", "to": "DM:AccountExtract", "type": "DataRaptorAction" }
  ],
  "circularReferences": [],
  "impactAnalysis": {
    "DM:AccountExtract": {
      "directDependents": ["IP:fetchAccountData"],
      "transitiveDependents": ["OS:updateAccount", "FC:AccountSummaryCard"]
    }
  }
}

出力形式 3: 人間が読めるレポート

OmniStudio Dependency Report
=============================
Org Namespace: Core (Industries)
Scan Date: 2026-03-06

Component Inventory:
  OmniScripts:              12 (8 active, 4 draft)
  Integration Procedures:    8 (6 active, 2 draft)
  FlexCards:                  5 (5 active)
  Data Mappers:             15 (12 active, 3 draft)

Dependency Summary:
  Total edges:              23
  Circular references:       0
  Orphaned components:       2 (no inbound/outbound deps)

Impact Analysis (most-depended components):
  1. DM:AccountExtract       → 5 dependents
  2. IP:fetchAccountData     → 3 dependents
  3. DM:OrderTransform       → 2 dependents

---

名前空間のオブジェクト/項目マッピング

3 つの名前空間（Core、vlocity_cmt、vlocity_ins）すべてにわたる完全なオブジェクト名、項目名、メタデータ型のマッピングについては、以下をお読みください:

references/namespace-guide.md

覚えておくべき主な判別要素:

• Core は OmniProcess / OmniUiCard / OmniDataTransform を使用します
• vlocity_cmt は vlocity_cmt__OmniScript__c / vlocity_cmt__VlocityUITemplate__c / vlocity_cmt__DRBundle__c を使用します
• vlocity_ins は vlocity_ins__OmniScript__c / vlocity_ins__VlocityUITemplate__c / vlocity_ins__DRBundle__c を使用します
• IsIntegrationProcedure ブール値と DataSourceConfig（Definition ではない）項目名は Core 専用です

---

CLI コマンドリファレンス

名前空間の検出

# Probe all three namespaces (run sequentially, first success wins)
sf data query --query "SELECT COUNT() FROM OmniProcess" --target-org myorg --json 2>/dev/null && echo "CORE" || \
sf data query --query "SELECT COUNT() FROM vlocity_cmt__OmniScript__c" --target-org myorg --json 2>/dev/null && echo "VLOCITY_CMT" || \
sf data query --query "SELECT COUNT() FROM vlocity_ins__OmniScript__c" --target-org myorg --json 2>/dev/null && echo "VLOCITY_INS" || \
echo "NOT_INSTALLED"

コンポーネントインベントリ（Core 名前空間）

# Count OmniScripts
sf data query --query "SELECT COUNT() FROM OmniProcess WHERE IsIntegrationProcedure = false" \
  --target-org myorg --json

# Count Integration Procedures
sf data query --query "SELECT COUNT() FROM OmniProcess WHERE IsIntegrationProcedure = true" \
  --target-org myorg --json

# Count FlexCards
sf data query --query "SELECT COUNT() FROM OmniUiCard" --target-org myorg --json

# Count Data Mappers
sf data query --query "SELECT COUNT() FROM OmniDataTransform" --target-org myorg --json

依存関係データの抽出（Core 名前空間）

# Get OmniScript elements with their config
sf data query --query "SELECT Id, OmniProcessId, Name, Type, PropertySetConfig FROM OmniProcessElement WHERE OmniProcessId = '{process_id}'" \
  --target-org myorg --json

# Get FlexCard data sources (for dependency parsing)
sf data query --query "SELECT Id, Name, DataSourceConfig FROM OmniUiCard WHERE IsActive = true" \
  --target-org myorg --json

# Get Data Mapper items (for object dependencies)
sf data query --query "SELECT Id, OmniDataTransformationId, InputObjectName, OutputObjectName FROM OmniDataTransformItem" \
  --target-org myorg --json

---

スキル間の連携

スキル	関係	このスキルがどのように役立つか
building-omnistudio-datamapper	名前空間とオブジェクトの依存関係データを提供します	Data Mapper の作成では、検出された名前空間を使用して正しい API 名を決定します
building-omnistudio-integration-procedure	名前空間と IP の依存関係マップを提供します	IP の作成では、依存関係グラフを使用して循環参照を回避します
building-omnistudio-omniscript	名前空間と要素の依存関係データを提供します	OmniScript の作成では、名前空間に正しい項目名を使用します
building-omnistudio-flexcard	名前空間とデータソースの依存関係マップを提供します	FlexCard の作成では、検出された IP 参照を検証に使用します
generating-mermaid-diagrams	可視化のために依存関係グラフを消費します	このスキルは、generating-mermaid-diagrams のスタイルと互換性のある Mermaid 出力を生成します
generating-custom-object / generating-custom-field	Data Mapper 分析用の sObject メタデータを提供します	依存関係の抽出時のオブジェクト項目の検証
deploying-metadata	デプロイでは名前空間に正しいメタデータ型を使用します	このスキルは、名前空間ごとに正しいメタデータ型名を提供します

---

注意点

シナリオ	対応
名前空間が混在する組織（移行中）	3 つの名前空間すべてをプローブし、複数が結果を返した場合は報告します。コンポーネントは旧名前空間と移行後の名前空間の両方に存在する可能性があります。
依存関係を持つ非アクティブなコンポーネント	依存関係グラフには含めますが、非アクティブとしてマークします。アクティブなコンポーネントが非アクティブなコンポーネントに依存している場合は警告します。
大規模な組織（1000 以上のコンポーネント）	SOQL のページネーション（LIMIT/OFFSET または queryMore）を使用します。200 件ずつバッチ処理します。
PropertySetConfig が SOQL の項目長を超える	Tooling API または REST API を使用して、切り詰められた設定を持つ要素の完全な JSON 本文を取得します。
循環依存関係が検出された	循環パス（A → B → C → A）をログに記録し、関与するすべてのエッジをマークし、残りの分岐の走査を続行します。
削除された項目を参照するコンポーネント	出力に「壊れた参照」として記録します。クリーンアップのためにフラグを立てます。
バージョンの競合（複数のアクティブバージョン）	実行時に参加するのは、アクティブなバージョン番号のうち最も高いものだけです。下位バージョンに固有の依存関係がある場合は警告します。

---

メモ

• 依存関係：組織で認証済みの sf CLI が必要です。スタイル付きの可視化を生成する場合は、generating-mermaid-diagrams を任意で使用できます。
• 名前空間を最初に検出する必要があります：以降のすべてのクエリは、正しいオブジェクト API 名と項目 API 名が分かっていることを前提とします。
• PropertySetConfig が鍵です：依存関係に関する情報のほぼすべてが、OmniProcessElement レコード上のこの JSON 項目に含まれています。
• FlexCard の DataSourceConfig：データソースは Definition 項目（OmniUiCard には存在しません）ではなく、DataSourceConfig にあります。カードのレイアウトと状態は PropertySetConfig にあります。
• Data Mapper 項目にはオブジェクト参照が含まれます：OmniDataTransformItem レコードの InputObjectName と OutputObjectName から、Data Mapper が読み取りおよび書き込みを行う sObject が分かります。親レコードへの外部キーは OmniDataTransformationId（「Transformation」全体）です。
• IsIntegrationProcedure が判別項目です：OmniProcess では、（存在しない）TypeCategory 項目ではなく、ブール型の IsIntegrationProcedure 項目を使用します。OmniProcessType 選択リストはこのブール値から計算され、読み取りの絞り込みには便利ですが、作成時に直接設定することはできません。
• sf data create record の制限事項：--values フラグでは、テキストエリア項目内の JSON 文字列（例：PropertySetConfig）を処理できません。JSON 設定を含むレコードには、代わりに sf api request rest --method POST --body @file.json を使用してください。
• 関連スキル：building-omnistudio-datamapper、building-omnistudio-integration-procedure、building-omnistudio-omniscript、building-omnistudio-flexcard — OmniStudio のオーサリング機能一式を利用できるよう、これらをインストールしてください

---

参照ファイル一覧

ファイル	読むタイミング
references/namespace-guide.md	フェーズ 1 — 3 つの名前空間（Core、vlocity_cmt、vlocity_ins）すべてにおけるオブジェクト／項目の完全なマッピング、デプロイ用メタデータ型名、複数名前空間にまたがる移行シナリオ
references/dependency-patterns.md	フェーズ 3 — 要素タイプごとの完全な依存関係抽出ルール、FlexCard のデータソース解析、Data Mapper 項目の解析、循環参照の検出アルゴリズム、影響分析パターン