omnistudio-dependencies-analyze

omnistudio-dependencies-analyze：OmniStudio コンポーネント間分析

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

---

対象範囲

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

---

必要な入力

開始前に確認するか、推定してください。

入力	指定がない場合のデフォルト
対象組織のエイリアス	ユーザーに確認
分析範囲	組織全体（すべての 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 スキルを使用する場合は、次の依存関係の順序に従ってください。

omnistudio-dependencies-analyze → omnistudio-datamapper-generate → omnistudio-integration-procedure-generate → omnistudio-omniscript-generate → omnistudio-flexcard-generate

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

---

主な知見

知見	詳細
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)
外部（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

---

Namespace オブジェクト／項目の対応表

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

---

スキル間の連携

スキル	関係	このスキルが役立つ内容
omnistudio-datamapper-generate	名前空間とオブジェクトの依存関係データを提供します	Data Mapper の作成では、検出された名前空間を使用して正しい API 名を指定します
omnistudio-integration-procedure-generate	名前空間と IP の依存関係マップを提供します	IP の作成では、依存関係グラフを使用して循環参照を回避します
omnistudio-omniscript-generate	名前空間と要素の依存関係データを提供します	OmniScript の作成では、名前空間に対応した項目名を使用します
omnistudio-flexcard-generate	名前空間とデータソースの依存関係マップを提供します	FlexCard の作成では、検出された IP 参照を検証に使用します
external-diagram-mermaid-generate	可視化のために依存関係グラフを利用します	このスキルは、external-diagram-mermaid-generate のスタイルに対応した Mermaid 出力を生成します
platform-custom-object-generate / platform-custom-field-generate	Data Mapper の分析用に sObject メタデータを提供します	依存関係の抽出時にオブジェクト項目を検証します
platform-metadata-deploy	デプロイでは、名前空間に対応したメタデータ型を使用します	このスキルは、名前空間ごとに正しいメタデータ型名を提供します

---

注意事項

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

---

メモ

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

---

提供前チェックリスト

• 後続のクエリを実行する前に名前空間を検出した
• オーケストレーションの順序に従った（このスキルはチェーン内で最初に実行されます）

---

参照ファイル一覧

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