@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/analyzing-omnistudio-dependencies/references/dependency-patterns.md

@@ -0,0 +1,508 @@
+<!-- Parent: analyzing-omnistudio-dependencies/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
+
+```
+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:
+
+```
+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
+
+```
+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
+
+```
+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:
+
+```
+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
+
+```
+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:
+
+```
+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
+
+```
+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:
+
+```
+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 |