sf-industry-commoncore-omnistudio-analyze

sf-industry-commoncore-omnistudio-analyze：OmniStudio 跨组件分析

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

核心职责

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 技能时，请遵循以下依赖链：

sf-industry-commoncore-omnistudio-analyze → sf-industry-commoncore-datamapper → sf-industry-commoncore-integration-procedure → sf-industry-commoncore-omniscript → sf-industry-commoncore-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（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 中的退出代码为 0 且包含 totalSize）即可确认命名空间。查询失败（INVALID_TYPE 或 sObject type not found）表示不存在该命名空间。

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

---

阶段 2：组件发现

目的：清点组织中的所有 OmniStudio 组件。

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

OmniScripts（Core 示例）：

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

Integration Procedures（Core 示例）：

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

FlexCards（Core 示例）：

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

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

Data Mappers（Core 示例）：

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

Data Mapper Items（用于提取对象依赖关系）：

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

重要：外键字段为 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 字段中存储数据源配置（而非 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)
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

---

命名空间对象/字段映射

三个命名空间中 OmniStudio 对象和字段的完整映射：

主要对象

概念	Core	vlocity_cmt	vlocity_ins
OmniScript / IP 容器	OmniProcess	vlocity_cmt__OmniScript__c	vlocity_ins__OmniScript__c
OmniScript / IP 元素	OmniProcessElement	vlocity_cmt__Element__c	vlocity_ins__Element__c
FlexCard	OmniUiCard	vlocity_cmt__VlocityUITemplate__c	vlocity_ins__VlocityUITemplate__c
Data Mapper	OmniDataTransform	vlocity_cmt__DRBundle__c	vlocity_ins__DRBundle__c
Data Mapper 项目	OmniDataTransformItem	vlocity_cmt__DRMapItem__c	vlocity_ins__DRMapItem__c

关键字段

概念	核心字段	vlocity_cmt 字段	vlocity_ins 字段
脚本类型	Type	vlocity_cmt__Type__c	vlocity_ins__Type__c
脚本子类型	SubType	vlocity_cmt__SubType__c	vlocity_ins__SubType__c
语言	Language	vlocity_cmt__Language__c	vlocity_ins__Language__c
是否处于活动状态	IsActive	vlocity_cmt__IsActive__c	vlocity_ins__IsActive__c
版本	VersionNumber	vlocity_cmt__Version__c	vlocity_ins__Version__c
元素配置	PropertySetConfig	vlocity_cmt__PropertySet__c	vlocity_ins__PropertySet__c
是否为集成过程	IsIntegrationProcedure	vlocity_cmt__IsIntegrationProcedure__c	vlocity_ins__IsIntegrationProcedure__c
FlexCard 数据源	DataSourceConfig	vlocity_cmt__Definition__c	vlocity_ins__Definition__c
FlexCard 布局/状态	PropertySetConfig	（相同字段）	（相同字段）
DM 输入对象	InputObjectName（位于 Item 上）	vlocity_cmt__InterfaceObject__c	vlocity_ins__InterfaceObject__c
DM 输出对象	OutputObjectName（位于 Item 上）	vlocity_cmt__TargetFieldObjectType__c	vlocity_ins__TargetFieldObjectType__c

参见：references/namespace-guide.md，了解包含部署元数据类型名称的完整参考。

---

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"

组件清单（核心命名空间）

# 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

依赖数据提取（核心命名空间）

# 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

---

跨技能集成

技能	关系	此技能的帮助方式
sf-industry-commoncore-datamapper	提供命名空间和对象依赖数据	Data Mapper 编写时使用检测到的命名空间，确保 API 名称正确
sf-industry-commoncore-integration-procedure	提供命名空间和 IP 依赖映射	IP 编写时使用依赖关系图，避免循环引用
sf-industry-commoncore-omniscript	提供命名空间和元素依赖数据	OmniScript 编写时使用命名空间正确的字段名称
sf-industry-commoncore-flexcard	提供命名空间和数据源依赖映射	FlexCard 编写时使用检测到的 IP 引用进行验证
sf-diagram-mermaid	使用依赖关系图进行可视化	此技能生成与 sf-diagram-mermaid 样式兼容的 Mermaid 输出
sf-metadata	提供用于 Data Mapper 分析的 sObject 元数据	在提取依赖时验证对象字段
sf-deploy	部署使用命名空间正确的元数据类型	此技能提供各命名空间对应的正确元数据类型名称

---

边缘情况

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

---

备注

• 依赖项：需要使用已通过组织身份验证的 sf CLI。可选：使用 sf-diagram-mermaid 进行样式化可视化。
• 必须先检测命名空间：所有后续查询都依赖于正确的对象和字段 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。
• 安装相关技能：/plugin install github:Jaganpro/sf-skills/sf-industry-commoncore-datamapper、/plugin install github:Jaganpro/sf-skills/sf-industry-commoncore-integration-procedure、/plugin install github:Jaganpro/sf-skills/sf-industry-commoncore-omniscript、/plugin install github:Jaganpro/sf-skills/sf-industry-commoncore-flexcard

---

许可证

MIT License。 版权所有 (c) 2026 David Ryan (weytani)