analyzing-omnistudio-dependencies

analyzing-omnistudio-dependencies：OmniStudio 跨组件分析

OmniStudio 专家分析师，专注于命名空间检测、依赖关系映射，以及对完整 OmniStudio 组件套件进行影响分析。执行组织范围的 OmniScripts、FlexCards、Integration Procedures 和 Data Mappers 清单盘点，并自动构建依赖关系图和 Mermaid 可视化图。

---

范围

• 范围内：命名空间检测（Core / vlocity_cmt / vlocity_ins）、组织范围的组件清单盘点、依赖关系图构建、影响分析、Mermaid 图表生成
• 范围外：编写或修改 OmniScripts（使用 building-omnistudio-omniscript）、构建 FlexCards（使用 building-omnistudio-flexcard）、创建 Integration Procedures（使用 building-omnistudio-integration-procedure）、配置 Data Mappers（使用 building-omnistudio-datamapper）

---

必需输入

开始前询问或推断以下信息：

输入	未提供时的默认值
目标组织别名	询问用户
分析范围	整个组织（所有 OmniStudio 组件类型）
要进行影响分析的特定组件	无（先生成完整清单）
输出格式偏好	全部三种：Mermaid 图表 + JSON 摘要 + 易读报告

---

输出预期

每次分析会生成以下一项或多项：

1. 命名空间检测结果 — 当前使用的命名空间（Core / vlocity_cmt / vlocity_ins / 未安装）
2. 组件清单 — OmniScripts、Integration Procedures、FlexCards、Data Mappers 的数量（活动与草稿）
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

此技能最先运行，用于建立下游技能所需的命名空间上下文和依赖关系映射。

---

关键见解

见解	详情
三种命名空间共存	Core（OmniProcess）、vlocity_cmt（vlocity_cmt__OmniScript__c）、vlocity_ins（vlocity_ins__OmniScript__c）
依赖关系存储在 JSON 中	PropertySetConfig（元素）、Definition（FlexCards）、InputObjectName/OutputObjectName（Data Mappers）
可能存在循环引用	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)
集成过程	#fef3c7 (amber-100)	#b45309 (amber-700)
Data Mapper	#d1fae5 (green-100)	#047857 (green-700)
FlexCard	#fce7f3 (pink-100)	#be185d (pink-700)
Apex 类	#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

---

跨技能集成

技能	关系	此技能的作用
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	部署使用符合命名空间的元数据类型	此技能为每个命名空间提供正确的元数据类型名称

---

注意事项

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

---

注意事项

• 依赖项：需要已完成组织身份验证的 sf CLI。可选：使用 generating-mermaid-diagrams 生成样式化可视化图表。
• 必须先检测命名空间：所有后续查询都依赖于正确的对象和字段 API 名称。
• PropertySetConfig 是关键：几乎所有依赖项信息都存储在 OmniProcessElement 记录的这个 JSON 字段中。
• FlexCard 的 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。
• 相关技能：building-omnistudio-datamapper、building-omnistudio-integration-procedure、building-omnistudio-omniscript、building-omnistudio-flexcard — 安装这些技能即可启用完整的 OmniStudio 创作套件。

---

参考文件索引

文件	阅读时机
references/namespace-guide.md	阶段 1 — 三个命名空间（Core、vlocity_cmt、vlocity_ins）中完整的对象/字段映射、部署用元数据类型名称、混合命名空间迁移场景
references/dependency-patterns.md	阶段 3 — 各元素类型的完整依赖项提取规则、FlexCard 数据源解析、Data Mapper 项解析、循环引用检测算法、影响分析模式