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 组件类型）
需要进行影响分析的特定组件	无（先生成完整清单）
输出格式偏好	全部三种：Mermaid 图表 + JSON 摘要 + 易读报告

---

输出预期

每次分析会生成以下一种或多种结果：

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

此技能首先运行，以建立命名空间上下文和依赖关系映射，供下游技能使用。

---

关键见解

见解	详情
三种命名空间并存	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 命名空间。

检测算法——按顺序探测对象，直到 COUNT() 成功返回：

1. Core（Industries 命名空间）：

   SELECT COUNT() FROM OmniProcess
   

   如果成功，则组织使用 Core 命名空间（API 234.0+ / Spring '22+）。

2. vlocity_cmt（通信、媒体与能源）：

   SELECT COUNT() FROM vlocity_cmt__OmniScript__c
   

3. vlocity_ins（保险与健康）：

   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

评估结果：查询成功（退出代码为 0，且 JSON 中包含 totalSize）即确认该命名空间。查询失败（INVALID_TYPE 或 sObject type not found）表示该命名空间不存在。

参见：references/namespace-guide.md，了解三个命名空间中完整的对象/字段映射。

---

阶段 2：组件发现

目的：整理组织中所有 OmniStudio 组件的清单。

使用检测到的命名空间，查询每种组件类型：

OmniScript（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 Procedure（Core 示例）：

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

FlexCard（Core 示例）：

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

IMPORTANT：OmniUiCard 对象没有 Definition 字段。使用 DataSourceConfig 获取数据源绑定，使用 PropertySetConfig 获取卡片布局/状态配置。

Data Mapper（Core 示例）：

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

Data Mapper 项（用于提取对象依赖）：

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 类方法
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 类

解析 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 字段中（而非 Definition——OmniUiCard 上不存在该字段）：

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

---

命名空间对象／字段映射

如需查看三个命名空间（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	使用依赖关系图进行可视化	此技能生成的 Mermaid 输出与 external-diagram-mermaid-generate 的样式兼容
platform-custom-object-generate / platform-custom-field-generate	提供用于 Data Mapper 分析的 sObject 元数据	在依赖关系提取期间验证对象字段
platform-metadata-deploy	部署时使用符合命名空间的元数据类型	此技能提供各命名空间对应的正确元数据类型名称

---

注意事项

场景	处理方式
混合命名空间组织（迁移进行中）	探测所有三个命名空间；如果多个命名空间返回结果，则报告此情况。组件可能同时存在于旧命名空间和已迁移的命名空间中。
存在依赖项的非活动组件	将其纳入依赖关系图，但标记为非活动。如果活动组件依赖于非活动组件，则发出警告。
大型组织（1000+ 个组件）	使用 SOQL 分页（LIMIT/OFFSET 或 queryMore）。每批处理 200 个。
PropertySetConfig 超出 SOQL 字段长度限制	使用 Tooling API 或 REST API 获取配置被截断的元素的完整 JSON 正文。
检测到循环依赖	记录循环路径（A → B → C → A），标记所有相关边，并继续遍历其余分支。
组件引用了已删除的项目	在输出中将其记录为“损坏的引用”，并标记以便清理。
版本冲突（存在多个活动版本）	运行时仅使用编号最高的活动版本。如果较低版本包含独有依赖项，则发出警告。

备注

• 依赖项：需要带有组织身份验证的 sf CLI。可选：external-diagram-mermaid-generate，用于生成样式化可视化图。
• 必须先检测命名空间：所有后续查询都依赖于正确的对象和字段 API 名称。
• PropertySetConfig 是关键：几乎所有依赖信息都存储在 OmniProcessElement 记录的这个 JSON 字段中。
• FlexCards 的 DataSourceConfig：数据源位于 DataSourceConfig 中，而非 Definition 字段（OmniUiCard 上不存在此字段）。卡片布局和状态位于 PropertySetConfig 中。
• Data Mapper 项包含对象引用：OmniDataTransformItem 记录上的 InputObjectName 和 OutputObjectName 可揭示 Data Mapper 读取和写入哪些 sObject。指向父级的外键是 OmniDataTransformationId（完整的“Transformation”）。
• IsIntegrationProcedure 是判别字段：OmniProcess 使用布尔型 IsIntegrationProcedure 字段，而非 TypeCategory 字段（此字段不存在）。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 — 完整的三种命名空间（Core、vlocity_cmt、vlocity_ins）中的对象/字段映射、用于部署的元数据类型名称、混合命名空间迁移场景
references/dependency-patterns.md	阶段 3 — 各元素类型的完整依赖提取规则、FlexCard 数据源解析、Data Mapper 项解析、循环引用检测算法、影响分析模式