omnistudio-dependencies-analyze

어떤 스킬인가요?

Cross-cutting OmniStudio analysis skill for namespace detection, dependency visualization, and impact analysis across OmniScripts, FlexCards, Integration Procedures, and Data Mappers. TRIGGER when: user asks about OmniStudio dependencies, wants namespace detection (Core vs vlocity_cmt vs vlocity_ins), needs impact analysis, requests dependency graphs or Mermaid diagrams, or asks which components are affected by a change. DO NOT TRIGGER when: authoring OmniScripts (use omnistudio-omniscript-generate), building FlexCards (use omnistudio-flexcard-generate), creating Integration Procedures (use omnistudio-integration-procedure-generate), or configuring Data Mappers (use omnistudio-datamapper-generate).

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

<!-- Parent: omnistudio-dependencies-analyze/SKILL.md -->

# OmniStudio Dependency Patterns

## Overview

OmniStudio components form a directed graph where each component type can reference others. Dependencies are not stored in lookup fields — they are embedded in JSON configuration fields (`PropertySetConfig`, `Definition`, `InputObjectName`/`OutputObjectName`). Extracting dependencies requires parsing these JSON structures.

---

## Dependency Direction Summary

```text
OmniScript ──→ Integration Procedure (via IP Action element)
OmniScript ──→ Data Mapper (via DataRaptor Action element)
OmniScript ──→ OmniScript (via embedded OmniScript element)
OmniScript ──→ Apex Class (via Remote Action element)
OmniScript ──→ LWC (via Custom Lightning Web Component element)
OmniScript ──→ HTTP Endpoint (via HTTP Action element)

Integration Procedure ──→ Data Mapper (via DataRaptor Action element)
Integration Procedure ──→ Apex Class (via Remote Action element)
Integration Procedure ──→ HTTP Endpoint (via HTTP Action element)
Integration Procedure ──→ Integration Procedure (via nested IP Action element)
Integration Procedure ──→ OmniScript (via OmniScript Action element — uncommon)

FlexCard ──→ Integration Procedure (via data source configuration)
FlexCard ──→ Apex Class (via Apex data source)
FlexCard ──→ FlexCard (via child card reference)
FlexCard ──→ OmniScript (via action configuration — launches OS)

Data Mapper ──→ Salesforce Object (via InputObjectName — read)
Data Mapper ──→ Salesforce Object (via OutputObjectName — write)
```

---

## OmniScript Dependencies

### Element Types and Their Dependency Targets

OmniScript elements are stored as `OmniProcessElement` records (Core) or `Element__c` records (Vlocity). Each element has a `PropertySetConfig` / `PropertySet__c` JSON field containing the configuration.

#### DataRaptor Transform Action

Calls a Data Mapper to extract, transform, or load data.

**PropertySetConfig structure**:
```json
{
  "Type": "DataRaptor Transform Action",
  "PropertySet": {
    "bundle": "AccountExtract",
    "bundleName": "AccountExtract",
    "dataRaptorType": "Extract"
  }
}
```

**Extraction rule**: `PropertySet.bundle` or `PropertySet.bundleName` → resolves to an `OmniDataTransform` record by `Name`.

#### DataRaptor Turbo Action

High-performance variant of DataRaptor Transform Action. Same JSON structure, same extraction rule.

**PropertySetConfig structure**:
```json
{
  "Type": "DataRaptor Turbo Action",
  "PropertySet": {
    "bundle": "AccountTurboExtract",
    "bundleName": "AccountTurboExtract"
  }
}
```

#### Integration Procedure Action

Calls an Integration Procedure.

**PropertySetConfig structure**:
```json
{
  "Type": "Integration Procedure Action",
  "PropertySet": {
    "integrationProcedureKey": "TypeName_SubTypeName",
    "ipMethod": "TypeName",
    "ipType": "SubTypeName",
    "integrationProcedureVersion": 1
  }
}
```

**Extraction rule**: `PropertySet.integrationProcedureKey` → resolves to an `OmniProcess` record where `Type_SubType` matches and `TypeCategory = 'IntegrationProcedure'`.

#### OmniScript Action (Embedded OmniScript)

Embeds or launches another OmniScript.

**PropertySetConfig structure**:
```json
{
  "Type": "OmniScript",
  "PropertySet": {
    "Type": "ChildScriptType",
    "Sub Type": "ChildScriptSubType",
    "Language": "English"
  }
}
```

**Extraction rule**: `PropertySet.Type` + `PropertySet["Sub Type"]` + `PropertySet.Language` → resolves to an `OmniProcess` where `TypeCategory = 'OmniScript'` and fields match.

#### Remote Action

Calls an Apex class method.

**PropertySetConfig structure**:
```json
{
  "Type": "Remote Action",
  "PropertySet": {
    "remoteClass": "MyApexClassName",
    "remoteMethod": "myMethodName",
    "remoteTimeout": 30000
  }
}
```

**Extraction rule**: `PropertySet.remoteClass` → Apex class name. `PropertySet.remoteMethod` → method name. Dependency is `remoteClass.remoteMethod`.

#### HTTP Action

Calls an external HTTP endpoint.

**PropertySetConfig structure**:
```json
{
  "Type": "HTTP Action",
  "PropertySet": {
    "httpUrl": "{externalEndpointUrl}",
    "httpMethod": "POST",
    "namedCredential": "MyNamedCredential"
  }
}
```

**Extraction rule**: `PropertySet.httpUrl` or `PropertySet.namedCredential` → external dependency. If `namedCredential` is present, it references a Named Credential record.

#### Custom Lightning Web Component

Embeds an LWC inside the OmniScript.

**PropertySetConfig structure**:
```json
{
  "Type": "Custom Lightning Web Component",
  "PropertySet": {
    "lwcName": "myCustomComponent",
    "lwcComponentName": "c-my-custom-component"
  }
}
```

**Extraction rule**: `PropertySet.lwcName` or `PropertySet.lwcComponentName` → LWC component reference.

#### DocuSign Envelope Action

Triggers a DocuSign envelope.

**PropertySetConfig structure**:
```json
{
  "Type": "DocuSign Envelope Action",
  "PropertySet": {
    "docuSignTemplateId": "template-uuid"
  }
}
```

**Extraction rule**: `PropertySet.docuSignTemplateId` → DocuSign template (external dependency).

---

## Integration Procedure Dependencies

Integration Procedures use the same element types as OmniScripts but are filtered by `TypeCategory = 'IntegrationProcedure'` (Core) or `IsIntegrationProcedure__c = true` (Vlocity).

### Element Types Available in IPs

| Element Type | Available in IP | Dependency Target |
|-------------|----------------|-------------------|
| DataRaptor Transform Action | Yes | Data Mapper |
| DataRaptor Turbo Action | Yes | Data Mapper |
| Remote Action | Yes | Apex Class |
| HTTP Action | Yes | External endpoint |
| Integration Procedure Action | Yes (nested) | Another IP |
| Matrix Action | Yes | Calculation Matrix |
| Set Values | Yes | None (internal) |
| Conditional Block | Yes | None (internal) |
| Loop Block | Yes | None (internal) |
| Response Action | Yes | None (internal) |
| List Action | Yes | None (internal) |

### Nested IP Pattern

An Integration Procedure can call another Integration Procedure, creating a chain:

```text
IP: OrderValidation
  └── IP Action → IP: CustomerLookup
       └── DR Action → DM: CustomerExtract
  └── IP Action → IP: InventoryCheck
       └── HTTP Action → External inventory API
  └── DR Action → DM: OrderTransform
```

---

## FlexCard Dependencies

FlexCards store their entire configuration in the `Definition` JSON field on `OmniUiCard` (Core) or `VlocityUITemplate__c` (Vlocity).

### Data Source Parsing

The `Definition` JSON contains a `dataSources` array:

```json
{
  "dataSources": [
    {
      "name": "AccountData",
      "type": "IntegrationProcedure",
      "value": {
        "key": "fetchAccountData",
        "inputMap": { "AccountId": "{recordId}" }
      }
    },
    {
      "name": "DirectApex",
      "type": "Apex",
      "value": {
        "className": "AccountSummaryController",
        "methodName": "getSummary"
      }
    },
    {
      "name": "SObjectData",
      "type": "SObject",
      "value": {
        "sObjectType": "Account",
        "fields": ["Name", "Industry", "Phone"]
      }
    }
  ]
}
```

**Extraction rules by data source type**:

| Data Source Type | JSON Path | Dependency Target |
|-----------------|-----------|-------------------|
| `IntegrationProcedure` | `value.key` | Integration Procedure (Type_SubType key) |
| `Apex` | `value.className` | Apex Class |
| `SObject` | `value.sObjectType` | Salesforce Object (direct SOQL) |
| `DataRaptor` | `value.bundle` | Data Mapper |

### Child Card References

FlexCards can embed other FlexCards:

```json
{
  "children": [
    {
      "cardName": "ContactListCard",
      "cardType": "childCard"
    }
  ]
}
```

**Extraction rule**: `children[].cardName` → resolves to another `OmniUiCard` by Name.

### Action References

FlexCard actions can launch OmniScripts:

```json
{
  "actions": [
    {
      "actionType": "OmniScript",
      "actionValue": {
        "type": "editAccount",
        "subType": "step1",
        "language": "English"
      }
    }
  ]
}
```

**Extraction rule**: `actions[].actionValue.type` + `subType` + `language` → resolves to an OmniScript.

---

## Data Mapper Dependencies

Data Mappers (DataRaptors) reference Salesforce objects through their items.

### Object References via Items

Each `OmniDataTransformItem` (Core) or `DRMapItem__c` (Vlocity) record contains:

| Field | Purpose | Dependency Type |
|-------|---------|----------------|
| `InputObjectName` / `InterfaceObject__c` | Source sObject for reads | sObject (read access) |
| `OutputObjectName` / `TargetFieldObjectType__c` | Target sObject for writes | sObject (write access) |
| `InputFieldName` / `InterfaceFieldAPIName__c` | Source field | Field-level dependency |
| `OutputFieldName` / `TargetFieldAPIName__c` | Target field | Field-level dependency |

### Extract Type Data Mapper Example

```text
DM: AccountExtract (Type: Extract)
├── Item 1: InputObjectName = "Account"
│   InputFieldName = "Name"
│   OutputFieldName = "AccountName"
├── Item 2: InputObjectName = "Account"
│   InputFieldName = "Industry"
│   OutputFieldName = "AccountIndustry"
└── Item 3: InputObjectName = "Contact"
    InputFieldName = "Email"
    OutputFieldName = "PrimaryEmail"

Dependencies: Account (read), Contact (read)
```

### Load Type Data Mapper Example

```text
DM: OrderCreate (Type: Load)
├── Item 1: OutputObjectName = "Order"
│   InputFieldName = "OrderData.accountId"
│   OutputFieldName = "AccountId"
└── Item 2: OutputObjectName = "OrderItem"
    InputFieldName = "OrderData.lineItems[].productId"
    OutputFieldName = "Product2Id"

Dependencies: Order (write), OrderItem (write)
```

### Transform Type Data Mapper

Transform type Data Mappers do not reference Salesforce objects directly — they map between data structures. They have no sObject dependencies but may participate in a chain:

```text
OmniScript → DR Extract (reads Account) → DR Transform (reshapes data) → DR Load (writes CustomObj__c)
```

---

## Circular Dependency Detection

### Why Circular Dependencies Occur

Circular references happen when component A depends on component B, which directly or transitively depends back on component A. Common scenarios:

1. **OmniScript ↔ IP**: OmniScript calls IP via IP Action, IP calls back to OmniScript via OmniScript Action
2. **IP ↔ IP**: IP A calls IP B via nested IP Action, IP B calls IP A
3. **FlexCard → IP → OmniScript → FlexCard**: FlexCard sources data from IP, IP triggers OmniScript, OmniScript launches FlexCard

### Detection Algorithm

```javascript
function detectCircularDependencies(graph):
    cycles = []
    for each node N in graph:
        visited = empty set
        path = empty list
        dfs(N, visited, path, graph, cycles)
    return cycles

function dfs(node, visited, path, graph, cycles):
    if node is in path:
        // Circular reference found
        cycleStart = index of node in path
        cycle = path[cycleStart:] + [node]
        cycles.append(cycle)
        return
    if node is in visited:
        return
    visited.add(node)
    path.append(node)
    for each neighbor of node in graph:
        dfs(neighbor, visited, path, graph, cycles)
    path.removeLast()
```

### Reporting Circular References

When a cycle is detected, report it clearly:

```text
CIRCULAR DEPENDENCY DETECTED:
  OS:editAccount → IP:validateAccount → OS:editAccount

Components in cycle:
  1. OmniScript "editAccount" (IP Action → validateAccount)
  2. Integration Procedure "validateAccount" (OmniScript Action → editAccount)

Risk: Runtime infinite loop if not guarded by conditional logic.
Recommendation: Review whether the back-reference is intentional and has
a termination condition.
```

---

## Dependency Graph Construction

### Step-by-Step Process

```text
1. DETECT namespace (see namespace-guide.md)

2. QUERY all container objects:
   - OmniProcess (OmniScripts + IPs)
   - OmniUiCard (FlexCards)
   - OmniDataTransform (Data Mappers)

3. QUERY all element objects:
   - OmniProcessElement (for each OmniProcess)
   - OmniDataTransformItem (for each OmniDataTransform)

4. PARSE each element's PropertySetConfig:
   - Identify element Type
   - Extract dependency reference per extraction rules above
   - Resolve reference to a known component record

5. PARSE each FlexCard's Definition:
   - Extract dataSources array
   - Extract children array
   - Extract actions array
   - Resolve references to known components

6. PARSE each Data Mapper's items:
   - Extract InputObjectName / OutputObjectName
   - Resolve to sObject names

7. BUILD directed graph:
   - Nodes = all components + referenced sObjects + external endpoints
   - Edges = dependency references with type labels

8. DETECT circular references:
   - Run DFS cycle detection
   - Record all cycles found

9. COMPUTE impact analysis:
   - For each node, compute transitive closure of inbound edges
   - "If X changes, these components are affected"
```

### Impact Analysis: Reverse Dependency Lookup

To answer "what breaks if I change Data Mapper X?", reverse the dependency direction:

```text
Given: DM:AccountExtract

Direct dependents (components that reference this DM):
  → IP:fetchAccountData (DataRaptor Action)

Transitive dependents (components that reference the direct dependents):
  → OS:updateAccount (IP Action → fetchAccountData)
  → FC:AccountSummaryCard (Data Source → fetchAccountData)

Full impact set: [IP:fetchAccountData, OS:updateAccount, FC:AccountSummaryCard]
```

---

## Property Set Config Parsing Tips

### Handling Large JSON

`PropertySetConfig` can exceed 100KB for complex elements. When querying via SOQL:
- SOQL `SELECT` returns the full field value
- For very large configs, the Tooling API may be necessary
- Parse incrementally if memory is a concern

### Nested Property Sets

Some elements have nested structures. Always check for:
- `PropertySet.bundle` (top-level reference)
- `PropertySet.elementProperties` (per-field configs)
- `PropertySet.conditionalProperties` (conditional logic)
- `PropertySet.remoteOptions` (additional remote action config)

### Common Pitfalls

| Pitfall | Handling |
|---------|---------|
| `bundleName` vs `bundle` | Both may exist; prefer `bundle` as the canonical reference |
| `integrationProcedureKey` format | Always `Type_SubType` with underscore separator |
| Version-specific references | Some elements reference a specific version; default is latest active |
| Null PropertySetConfig | Skip elements with null/empty config — they have no dependencies |
| JSON parsing errors | Malformed JSON in PropertySetConfig can occur on manually edited records; catch and log |

<!-- Parent: omnistudio-dependencies-analyze/SKILL.md -->

# OmniStudio Namespace Reference Guide

## Overview

Salesforce OmniStudio exists under three distinct namespaces depending on the org's industry package and migration status. Every OmniStudio operation must target the correct namespace — queries, metadata retrieval, and deployment all use namespace-specific object and field API names.

| Namespace | Package Context | Typical Orgs |
|-----------|----------------|--------------|
| **Core** (no prefix) | Industries / OmniStudio managed package migrated to Core | Orgs on API 234.0+ (Spring '22+) that have completed the Core migration |
| **vlocity_cmt** | Vlocity Communications, Media & Energy | Telco, media, energy & utilities industry orgs |
| **vlocity_ins** | Vlocity Insurance & Health | Insurance, health, and life sciences industry orgs |

---

## Detection Algorithm

### Step-by-Step Probing

Run SOQL queries against each namespace's primary object. The first query that succeeds determines the namespace.

```text
1. Probe Core:
   SELECT COUNT() FROM OmniProcess
   → Success? Namespace = Core. Stop.
   → Failure (INVALID_TYPE)? Continue.

2. Probe vlocity_cmt:
   SELECT COUNT() FROM vlocity_cmt__OmniScript__c
   → Success? Namespace = vlocity_cmt. Stop.
   → Failure (INVALID_TYPE)? Continue.

3. Probe vlocity_ins:
   SELECT COUNT() FROM vlocity_ins__OmniScript__c
   → Success? Namespace = vlocity_ins. Stop.
   → Failure (INVALID_TYPE)? OmniStudio not installed.
```

### CLI Implementation

```bash
# Core probe
sf data query --query "SELECT COUNT() FROM OmniProcess" --target-org myorg --json 2>/dev/null
# Check: result.totalSize >= 0 means Core namespace

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

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

### Interpreting Results

- **Exit code 0 + JSON with `totalSize`**: Namespace is present
- **Exit code non-zero or `INVALID_TYPE` error**: Namespace not installed
- **Exit code 0 + `totalSize: 0`**: Namespace exists but no components created yet (still valid)

---

## Object Mapping

### Primary Container Objects

These objects store OmniScript, Integration Procedure, FlexCard, and Data Mapper definitions.

| Concept | Core | vlocity_cmt | vlocity_ins |
|---------|------|-------------|-------------|
| OmniScript / Integration Procedure | `OmniProcess` | `vlocity_cmt__OmniScript__c` | `vlocity_ins__OmniScript__c` |
| OmniScript / IP Elements | `OmniProcessElement` | `vlocity_cmt__Element__c` | `vlocity_ins__Element__c` |
| FlexCard | `OmniUiCard` | `vlocity_cmt__VlocityUITemplate__c` | `vlocity_ins__VlocityUITemplate__c` |
| Data Mapper (DataRaptor) | `OmniDataTransform` | `vlocity_cmt__DRBundle__c` | `vlocity_ins__DRBundle__c` |
| Data Mapper Item | `OmniDataTransformItem` | `vlocity_cmt__DRMapItem__c` | `vlocity_ins__DRMapItem__c` |
| Calculation Matrix | `CalculationMatrix` | `vlocity_cmt__CalculationMatrix__c` | `vlocity_ins__CalculationMatrix__c` |
| Calculation Procedure | `CalculationProcedure` | `vlocity_cmt__CalculationProcedure__c` | `vlocity_ins__CalculationProcedure__c` |

### Relationship Fields (Element → Parent)

| Concept | Core | vlocity_cmt | vlocity_ins |
|---------|------|-------------|-------------|
| Element → Process lookup | `OmniProcessId` | `vlocity_cmt__OmniScriptId__c` | `vlocity_ins__OmniScriptId__c` |
| DM Item → DM lookup | `OmniDataTransformId` | `vlocity_cmt__DRBundleId__c` | `vlocity_ins__DRBundleId__c` |

---

## Field Mapping

### OmniProcess / OmniScript Fields

| Concept | Core (OmniProcess) | vlocity_cmt (OmniScript__c) | vlocity_ins (OmniScript__c) |
|---------|-------------------|---------------------------|---------------------------|
| Type | `Type` | `vlocity_cmt__Type__c` | `vlocity_ins__Type__c` |
| SubType | `SubType` | `vlocity_cmt__SubType__c` | `vlocity_ins__SubType__c` |
| Language | `Language` | `vlocity_cmt__Language__c` | `vlocity_ins__Language__c` |
| Is Active | `IsActive` | `vlocity_cmt__IsActive__c` | `vlocity_ins__IsActive__c` |
| Version | `VersionNumber` | `vlocity_cmt__Version__c` | `vlocity_ins__Version__c` |
| Type Category | `TypeCategory` | N/A (use `vlocity_cmt__IsIntegrationProcedure__c`) | N/A (use `vlocity_ins__IsIntegrationProcedure__c`) |
| Custom HTML | `CustomHtmlTemplates` | `vlocity_cmt__CustomHtmlTemplates__c` | `vlocity_ins__CustomHtmlTemplates__c` |
| Is Reusable | `IsReusable` | `vlocity_cmt__IsReusable__c` | `vlocity_ins__IsReusable__c` |
| Procedure Key | N/A | `vlocity_cmt__ProcedureKey__c` | `vlocity_ins__ProcedureKey__c` |

**Note on TypeCategory vs IsIntegrationProcedure**: In Core namespace, `TypeCategory` distinguishes OmniScripts from Integration Procedures (`'OmniScript'` vs `'IntegrationProcedure'`). In Vlocity namespaces, use the boolean field `IsIntegrationProcedure__c` instead.

### Element Fields

| Concept | Core (OmniProcessElement) | vlocity_cmt (Element__c) | vlocity_ins (Element__c) |
|---------|--------------------------|-------------------------|-------------------------|
| Name | `Name` | `Name` | `Name` |
| Type | `Type` | `vlocity_cmt__Type__c` | `vlocity_ins__Type__c` |
| Property Set Config | `PropertySetConfig` | `vlocity_cmt__PropertySet__c` | `vlocity_ins__PropertySet__c` |
| Order | `SequenceNumber` | `vlocity_cmt__Order__c` | `vlocity_ins__Order__c` |
| Is Active | `IsActive` | `vlocity_cmt__Active__c` | `vlocity_ins__Active__c` |
| Parent Element | `ParentElementId` | `vlocity_cmt__ParentElementId__c` | `vlocity_ins__ParentElementId__c` |
| Level | `Level` | `vlocity_cmt__Level__c` | `vlocity_ins__Level__c` |

### FlexCard / UI Template Fields

| Concept | Core (OmniUiCard) | vlocity_cmt (VlocityUITemplate__c) | vlocity_ins (VlocityUITemplate__c) |
|---------|-------------------|-----------------------------------|-----------------------------------|
| Name | `Name` | `Name` | `Name` |
| Is Active | `IsActive` | `vlocity_cmt__IsActive__c` | `vlocity_ins__IsActive__c` |
| Definition | `Definition` | `vlocity_cmt__Definition__c` | `vlocity_ins__Definition__c` |
| Author Name | `AuthorName` | `vlocity_cmt__Author__c` | `vlocity_ins__Author__c` |
| Version | `VersionNumber` | `vlocity_cmt__Version__c` | `vlocity_ins__Version__c` |
| Template Type | N/A | `vlocity_cmt__TemplateType__c` | `vlocity_ins__TemplateType__c` |

### Data Mapper / DataRaptor Fields

| Concept | Core (OmniDataTransform) | vlocity_cmt (DRBundle__c) | vlocity_ins (DRBundle__c) |
|---------|-------------------------|--------------------------|--------------------------|
| Name | `Name` | `Name` | `Name` |
| Type | `Type` | `vlocity_cmt__Type__c` | `vlocity_ins__Type__c` |
| Is Active | `IsActive` | `vlocity_cmt__IsActive__c` | `vlocity_ins__IsActive__c` |
| Input Type | `InputType` | `vlocity_cmt__InputType__c` | `vlocity_ins__InputType__c` |
| Output Type | `OutputType` | `vlocity_cmt__OutputType__c` | `vlocity_ins__OutputType__c` |

### Data Mapper Item Fields

| Concept | Core (OmniDataTransformItem) | vlocity_cmt (DRMapItem__c) | vlocity_ins (DRMapItem__c) |
|---------|------------------------------|---------------------------|---------------------------|
| Input Object | `InputObjectName` | `vlocity_cmt__InterfaceObject__c` | `vlocity_ins__InterfaceObject__c` |
| Output Object | `OutputObjectName` | `vlocity_cmt__TargetFieldObjectType__c` | `vlocity_ins__TargetFieldObjectType__c` |
| Input Field | `InputFieldName` | `vlocity_cmt__InterfaceFieldAPIName__c` | `vlocity_ins__InterfaceFieldAPIName__c` |
| Output Field | `OutputFieldName` | `vlocity_cmt__TargetFieldAPIName__c` | `vlocity_ins__TargetFieldAPIName__c` |
| Filter Data Type | `FilterDataType` | `vlocity_cmt__FilterDataType__c` | `vlocity_ins__FilterDataType__c` |
| Query Sequence | `InputObjectQuerySequence` | `vlocity_cmt__InterfaceObjectLookupOrder__c` | `vlocity_ins__InterfaceObjectLookupOrder__c` |

---

## Metadata Type Names for Deployment

When using `sf project retrieve start` or `sf project deploy start`, reference the correct metadata type:

| Component | Core Metadata Type | Vlocity Metadata Type |
|-----------|-------------------|----------------------|
| OmniScript | `OmniScript` | N/A (use Vlocity Build Tool) |
| Integration Procedure | `OmniIntegrationProcedure` | N/A (use Vlocity Build Tool) |
| FlexCard | `OmniUiCard` | N/A (use Vlocity Build Tool) |
| Data Mapper | `OmniDataTransform` | N/A (use Vlocity Build Tool) |
| Data Mapper Item | `OmniDataTransformItem` | N/A (use Vlocity Build Tool) |

**Note**: Only Core namespace components support standard Salesforce metadata API deployment. Vlocity namespace components require the Vlocity Build Tool (`vlocity_build`) for migration between orgs.

### Retrieve Example (Core)
```bash
sf project retrieve start --metadata OmniScript --target-org myorg
sf project retrieve start --metadata OmniDataTransform --target-org myorg
```

---

## Mixed Namespace Scenarios

### During Core Migration

Organizations migrating from a Vlocity namespace to Core may temporarily have components under both namespaces. During this transition:

1. **Probe both namespaces** — if both return results, the org is mid-migration
2. **Core components take precedence** — runtime uses Core namespace objects when both exist
3. **Report the state** — alert the user that migration is in progress and both namespaces contain data
4. **Do not modify Vlocity-namespace components** — they are frozen during migration

### Detection of Mixed State

```bash
# Check if Core has components
sf data query --query "SELECT COUNT() FROM OmniProcess" --target-org myorg --json 2>/dev/null

# Also check if Vlocity still has components
sf data query --query "SELECT COUNT() FROM vlocity_cmt__OmniScript__c" --target-org myorg --json 2>/dev/null
```

If both return `totalSize > 0`, the org is in a mixed namespace state.

### Recommended Actions During Mixed State

- Inventory components under both namespaces
- Compare counts to assess migration progress
- Flag components that exist only in the old namespace (not yet migrated)
- Do not create components under the old namespace

---

## Data Mapper Type Values

The `Type` field on OmniDataTransform / DRBundle indicates the mapper's purpose:

| Type Value | Description |
|-----------|-------------|
| `Extract` | Reads data from Salesforce objects |
| `Transform` | Maps and transforms data between structures |
| `Load` | Writes data to Salesforce objects |
| `Turbo Extract` | High-performance read (bypasses sharing rules) |

---

## SOQL Query Templates

### Core Namespace — Full Inventory

```soql
-- All OmniScripts
SELECT Id, Type, SubType, Language, IsActive, VersionNumber, LastModifiedDate
FROM OmniProcess
WHERE TypeCategory = 'OmniScript'
ORDER BY Type, SubType, Language, VersionNumber DESC

-- All Integration Procedures
SELECT Id, Type, SubType, Language, IsActive, VersionNumber, LastModifiedDate
FROM OmniProcess
WHERE TypeCategory = 'IntegrationProcedure'
ORDER BY Type, SubType, Language, VersionNumber DESC

-- All FlexCards
SELECT Id, Name, IsActive, AuthorName, VersionNumber, LastModifiedDate
FROM OmniUiCard
ORDER BY Name, VersionNumber DESC

-- All Data Mappers
SELECT Id, Name, Type, IsActive, InputType, OutputType, LastModifiedDate
FROM OmniDataTransform
ORDER BY Name
```

### vlocity_cmt Namespace — Full Inventory

```soql
-- All OmniScripts
SELECT Id, vlocity_cmt__Type__c, vlocity_cmt__SubType__c,
       vlocity_cmt__Language__c, vlocity_cmt__IsActive__c, vlocity_cmt__Version__c
FROM vlocity_cmt__OmniScript__c
WHERE vlocity_cmt__IsIntegrationProcedure__c = false
ORDER BY vlocity_cmt__Type__c, vlocity_cmt__SubType__c

-- All Integration Procedures
SELECT Id, vlocity_cmt__Type__c, vlocity_cmt__SubType__c,
       vlocity_cmt__Language__c, vlocity_cmt__IsActive__c, vlocity_cmt__Version__c
FROM vlocity_cmt__OmniScript__c
WHERE vlocity_cmt__IsIntegrationProcedure__c = true
ORDER BY vlocity_cmt__Type__c, vlocity_cmt__SubType__c

-- All FlexCards / UI Templates
SELECT Id, Name, vlocity_cmt__IsActive__c, vlocity_cmt__Version__c
FROM vlocity_cmt__VlocityUITemplate__c
ORDER BY Name

-- All Data Mappers (DataRaptors)
SELECT Id, Name, vlocity_cmt__Type__c, vlocity_cmt__IsActive__c
FROM vlocity_cmt__DRBundle__c
ORDER BY Name
```

### vlocity_ins Namespace — Full Inventory

```soql
-- All OmniScripts
SELECT Id, vlocity_ins__Type__c, vlocity_ins__SubType__c,
       vlocity_ins__Language__c, vlocity_ins__IsActive__c, vlocity_ins__Version__c
FROM vlocity_ins__OmniScript__c
WHERE vlocity_ins__IsIntegrationProcedure__c = false
ORDER BY vlocity_ins__Type__c, vlocity_ins__SubType__c

-- All Integration Procedures
SELECT Id, vlocity_ins__Type__c, vlocity_ins__SubType__c,
       vlocity_ins__Language__c, vlocity_ins__IsActive__c, vlocity_ins__Version__c
FROM vlocity_ins__OmniScript__c
WHERE vlocity_ins__IsIntegrationProcedure__c = true
ORDER BY vlocity_ins__Type__c, vlocity_ins__SubType__c

-- All FlexCards / UI Templates
SELECT Id, Name, vlocity_ins__IsActive__c, vlocity_ins__Version__c
FROM vlocity_ins__VlocityUITemplate__c
ORDER BY Name

-- All Data Mappers (DataRaptors)
SELECT Id, Name, vlocity_ins__Type__c, vlocity_ins__IsActive__c
FROM vlocity_ins__DRBundle__c
ORDER BY Name
```

---
name: omnistudio-dependencies-analyze
description: "Cross-cutting OmniStudio analysis skill for namespace detection, dependency visualization, and impact analysis across OmniScripts, FlexCards, Integration Procedures, and Data Mappers. TRIGGER when: user asks about OmniStudio dependencies, wants namespace detection (Core vs vlocity_cmt vs vlocity_ins), needs impact analysis, requests dependency graphs or Mermaid diagrams, or asks which components are affected by a change. DO NOT TRIGGER when: authoring OmniScripts (use omnistudio-omniscript-generate), building FlexCards (use omnistudio-flexcard-generate), creating Integration Procedures (use omnistudio-integration-procedure-generate), or configuring Data Mappers (use omnistudio-datamapper-generate)."
metadata:
  cliTools:
    - tool: ["sf"]
      semver: ">=2.0.0"
  relatedSkills:
    - "external-diagram-mermaid-generate"
    - "omnistudio-datamapper-generate"
    - "omnistudio-flexcard-generate"
    - "omnistudio-integration-procedure-generate"
    - "omnistudio-omniscript-generate"
    - "platform-custom-field-generate"
    - "platform-custom-object-generate"
    - "platform-metadata-deploy"
  version: "1.0"
  domains: ["OmniStudio"]
---

# omnistudio-dependencies-analyze: OmniStudio Cross-Component Analysis

Expert OmniStudio analyst specializing in namespace detection, dependency mapping, and impact analysis across the full OmniStudio component suite. Performs org-wide inventory of OmniScripts, FlexCards, Integration Procedures, and Data Mappers with automated dependency graph construction and Mermaid visualization.

---

## Scope

- **In scope**: Namespace detection (Core / vlocity_cmt / vlocity_ins), org-wide component inventory, dependency graph construction, impact analysis, Mermaid diagram generation
- **Out of scope**: Authoring or modifying OmniScripts (use `omnistudio-omniscript-generate`), building FlexCards (use `omnistudio-flexcard-generate`), creating Integration Procedures (use `omnistudio-integration-procedure-generate`), configuring Data Mappers (use `omnistudio-datamapper-generate`)

---

## Required Inputs

Ask for or infer before starting:

| Input | Default if not provided |
|-------|------------------------|
| Target org alias | Ask the user |
| Analysis scope | Full org (all OmniStudio component types) |
| Specific component to impact-analyze | None (produce full inventory first) |
| Output format preference | All three: Mermaid diagram + JSON summary + human-readable report |

---

## Output Expectations

Each analysis run produces one or more of:

1. **Namespace detection result** — which namespace is active (Core / vlocity_cmt / vlocity_ins / not installed)
2. **Component inventory** — counts of OmniScripts, Integration Procedures, FlexCards, Data Mappers (active vs draft)
3. **Dependency graph** — directed edges between all OmniStudio components with edge type labels
4. **Mermaid diagram** — copy-pasteable Mermaid `graph LR` block for documentation
5. **JSON summary** — machine-readable namespace + components + dependencies + impact analysis
6. **Human-readable report** — plain-text summary with component counts, edge count, circular references, and most-depended components
7. **Circular reference warnings** — cycle path and risk statement for each detected cycle

---

## Core Responsibilities

1. **Namespace Detection**: Identify whether an org uses Core (Industries), vlocity_cmt (Communications, Media & Energy), or vlocity_ins (Insurance & Health) namespace
2. **Dependency Analysis**: Build directed graphs of cross-component dependencies using BFS traversal with circular reference detection
3. **Impact Analysis**: Determine which components are affected when a given OmniScript, IP, FlexCard, or Data Mapper changes
4. **Mermaid Visualization**: Generate dependency diagrams in Mermaid syntax for documentation and review
5. **Org-Wide Inventory**: Catalog all OmniStudio components by type, status, language, and version

---

> **CRITICAL: Orchestration Order**
>
> When multiple OmniStudio skills are involved, follow this dependency chain:
>
> `omnistudio-dependencies-analyze` → `omnistudio-datamapper-generate` → `omnistudio-integration-procedure-generate` → `omnistudio-omniscript-generate` → `omnistudio-flexcard-generate`
>
> This skill runs first to establish namespace context and dependency maps that downstream skills consume.

---

## Key Insights

| Insight | Detail |
|---------|--------|
| Three namespaces coexist | Core (OmniProcess), vlocity_cmt (vlocity_cmt__OmniScript__c), vlocity_ins (vlocity_ins__OmniScript__c) |
| Dependencies are stored in JSON | PropertySetConfig (elements), Definition (FlexCards), InputObjectName/OutputObjectName (Data Mappers) |
| Circular references are possible | OmniScript A → IP B → OmniScript A via embedded call |
| FlexCard data sources are typed | `dataSource.type === 'IntegrationProcedures'` (plural) in DataSourceConfig JSON |
| Active vs Draft matters | Only active components participate in runtime dependency chains |

---

## Workflow (4-Phase Pattern)

### Phase 1: Namespace Detection

**Purpose**: Determine which OmniStudio namespace the org uses before querying any component metadata.

**Detection Algorithm** — Probe objects in order until a successful COUNT() returns:

1. **Core (Industries namespace)**:
   ```soql
   SELECT COUNT() FROM OmniProcess
   ```
   If this succeeds, the org uses the Core namespace (API 234.0+ / Spring '22+).

2. **vlocity_cmt (Communications, Media & Energy)**:
   ```soql
   SELECT COUNT() FROM vlocity_cmt__OmniScript__c
   ```

3. **vlocity_ins (Insurance & Health)**:
   ```soql
   SELECT COUNT() FROM vlocity_ins__OmniScript__c
   ```

If none succeed, OmniStudio is not installed in the org.

**CLI Commands for namespace detection**:
```bash
# 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
```

**Evaluate results**: A successful query (exit code 0 with `totalSize` in JSON) confirms the namespace. A query failure (`INVALID_TYPE` or `sObject type not found`) means that namespace is not present.

**See**: [references/namespace-guide.md](references/namespace-guide.md) for complete object/field mapping across all three namespaces.

---

### Phase 2: Component Discovery

**Purpose**: Build an inventory of all OmniStudio components in the org.

Using the detected namespace, query each component type:

**OmniScripts** (Core example — paginate with LIMIT/OFFSET for large orgs):
```soql
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 example):
```soql
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 example):
```soql
SELECT Id, Name, IsActive, DataSourceConfig, PropertySetConfig,
       AuthorName, LastModifiedDate
FROM OmniUiCard
ORDER BY Name
LIMIT 200
```

> **IMPORTANT**: The `OmniUiCard` object does NOT have a `Definition` field. Use `DataSourceConfig` for data source bindings and `PropertySetConfig` for card layout/states configuration.

**Data Mappers** (Core example):
```soql
SELECT Id, Name, IsActive, Type, LastModifiedDate
FROM OmniDataTransform
ORDER BY Name
LIMIT 200
```

**Data Mapper Items** (for object dependency extraction):
```soql
SELECT Id, OmniDataTransformationId, InputObjectName, OutputObjectName,
       InputObjectQuerySequence
FROM OmniDataTransformItem
WHERE OmniDataTransformationId IN ({datamapper_ids})
```

> **IMPORTANT**: The foreign key field is `OmniDataTransformationId` (full word "Transformation"), NOT `OmniDataTransformId`.

**CLI Command pattern**:
```bash
sf data query --query "SELECT Id, Type, SubType, Language, IsActive FROM OmniProcess WHERE IsIntegrationProcedure = false" \
  --target-org myorg --json
```

---

### Phase 3: Dependency Analysis

**Purpose**: Parse component metadata to build a directed dependency graph.

#### Algorithm: BFS with Circular Detection

```text
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
```

#### Element Type → Dependency Extraction

OmniScript and IP elements store references in the `PropertySetConfig` JSON field. Parse each element to extract dependencies:

| Element Type | JSON Path in PropertySetConfig | Dependency Target |
|-------------|-------------------------------|-------------------|
| DataRaptor Transform Action | `bundle`, `bundleName` | Data Mapper (by name) |
| DataRaptor Turbo Action | `bundle`, `bundleName` | Data Mapper (by name) |
| Remote Action | `remoteClass`, `remoteMethod` | Apex Class.Method |
| Integration Procedure Action | `integrationProcedureKey` | IP (Type_SubType) |
| OmniScript Action | `omniScriptKey` or `Type/SubType` | OmniScript (Type_SubType) |
| HTTP Action | `httpUrl`, `httpMethod` | External endpoint (URL) |
| DocuSign Envelope Action | `docuSignTemplateId` | DocuSign template |
| Apex Remote Action | `remoteClass` | Apex Class |

**Parsing PropertySetConfig**:
```text
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 Data Source Parsing

FlexCards store their data source configuration in the `DataSourceConfig` JSON field (NOT `Definition` — that field does not exist on `OmniUiCard`):

```text
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**: The data source type for IPs is `IntegrationProcedures` (plural with capital P), not `IntegrationProcedure`.

#### Data Mapper Object Dependencies

Data Mappers reference Salesforce objects via their items:

```text
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)
```

**See**: [references/dependency-patterns.md](references/dependency-patterns.md) for complete dependency extraction rules and examples.

---

### Phase 4: Visualization & Reporting

**Purpose**: Generate human-readable output from the dependency graph.

#### Output Format 1: Mermaid Dependency Diagram

```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
```

**Color scheme**:

| Component Type | Fill | Stroke |
|---------------|------|--------|
| 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) |

#### Output Format 2: JSON Summary

```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"]
    }
  }
}
```

#### Output Format 3: Human-Readable Report

```text
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 Object/Field Mapping

For the complete object name, field name, and metadata type mapping across all three namespaces (Core, vlocity_cmt, vlocity_ins), read:

**[references/namespace-guide.md](references/namespace-guide.md)**

Key discriminators to keep in mind:
- Core uses `OmniProcess` / `OmniUiCard` / `OmniDataTransform`
- vlocity_cmt uses `vlocity_cmt__OmniScript__c` / `vlocity_cmt__VlocityUITemplate__c` / `vlocity_cmt__DRBundle__c`
- vlocity_ins uses `vlocity_ins__OmniScript__c` / `vlocity_ins__VlocityUITemplate__c` / `vlocity_ins__DRBundle__c`
- The `IsIntegrationProcedure` boolean and `DataSourceConfig` (not `Definition`) field names are Core-only

---

## CLI Commands Reference

### Namespace Detection
```bash
# 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"
```

### Component Inventory (Core Namespace)
```bash
# 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
```

### Dependency Data Extraction (Core Namespace)
```bash
# 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
```

---

## Cross-Skill Integration

| Skill | Relationship | How This Skill Helps |
|-------|-------------|---------------------|
| omnistudio-datamapper-generate | Provides namespace and object dependency data | Data Mapper authoring uses detected namespace for correct API names |
| omnistudio-integration-procedure-generate | Provides namespace and IP dependency map | IP authoring uses dependency graph to avoid circular references |
| omnistudio-omniscript-generate | Provides namespace and element dependency data | OmniScript authoring uses namespace-correct field names |
| omnistudio-flexcard-generate | Provides namespace and data source dependency map | FlexCard authoring uses detected IP references for validation |
| external-diagram-mermaid-generate | Consumes dependency graph for visualization | This skill generates Mermaid output compatible with external-diagram-mermaid-generate styling |
| platform-custom-object-generate / platform-custom-field-generate | Provides sObject metadata for Data Mapper analysis | Object field validation during dependency extraction |
| platform-metadata-deploy | Deployment uses namespace-correct metadata types | This skill provides the correct metadata type names per namespace |

---

## Gotchas

| Scenario | Handling |
|----------|---------|
| Mixed namespace org (migration in progress) | Probe all three namespaces; report if multiple return results. Components may exist under both old and migrated namespaces. |
| Inactive components with dependencies | Include in dependency graph but mark as inactive. Warn if active component depends on inactive one. |
| Large orgs (1000+ components) | Use SOQL pagination (LIMIT/OFFSET or queryMore). Process in batches of 200. |
| PropertySetConfig exceeds SOQL field length | Use Tooling API or REST API to fetch full JSON body for elements with truncated config. |
| Circular dependency detected | Log the cycle path (A → B → C → A), mark all participating edges, continue traversal for remaining branches. |
| Components referencing deleted items | Record as "broken reference" in output. Flag for cleanup. |
| Version conflicts (multiple active versions) | Only the highest active version number participates in runtime. Warn if lower versions have unique dependencies. |

---

## Notes

- **Dependencies**: Requires `sf` CLI with org authentication. Optional: external-diagram-mermaid-generate for styled visualization.
- **Namespace must be detected first**: All downstream queries depend on knowing the correct object and field API names.
- **PropertySetConfig is the key**: Nearly all dependency information lives in this JSON field on OmniProcessElement records.
- **DataSourceConfig for FlexCards**: Data sources are in `DataSourceConfig`, NOT a `Definition` field (which does not exist on `OmniUiCard`). Card layout/states are in `PropertySetConfig`.
- **Data Mapper items contain object references**: InputObjectName and OutputObjectName on OmniDataTransformItem records reveal which sObjects a Data Mapper reads from and writes to. The foreign key to the parent is `OmniDataTransformationId` (full "Transformation").
- **IsIntegrationProcedure is the discriminator**: `OmniProcess` uses a boolean `IsIntegrationProcedure` field, not a `TypeCategory` field (which does not exist). The `OmniProcessType` picklist is computed from this boolean and is useful for filtering reads but cannot be set directly on create.
- **sf data create record limitations**: The `--values` flag cannot handle JSON strings in textarea fields (e.g., PropertySetConfig). Use `sf api request rest --method POST --body @file.json` instead for records with JSON configuration.
- **Related skills**: `omnistudio-datamapper-generate`, `omnistudio-integration-procedure-generate`, `omnistudio-omniscript-generate`, `omnistudio-flexcard-generate` — install these to enable the full OmniStudio authoring suite

---

## Pre-Delivery Checklist

- [ ] Namespace detected before any downstream queries
- [ ] Orchestration order followed (this skill runs first in the chain)

---

## Reference File Index

| File | When to read |
|------|-------------|
| `references/namespace-guide.md` | Phase 1 — complete object/field mapping across all three namespaces (Core, vlocity_cmt, vlocity_ins), metadata type names for deployment, mixed-namespace migration scenarios |
| `references/dependency-patterns.md` | Phase 3 — complete dependency extraction rules per element type, FlexCard data source parsing, Data Mapper item parsing, circular reference detection algorithm, impact analysis patterns |