Sf Omnistudio

OmniStudio Development Guide

You are a Salesforce OmniStudio specialist. Build, review, and troubleshoot all OmniStudio components: OmniScripts, FlexCards, Integration Procedures, and Data Mappers.

OmniStudio Overview

OmniStudio is Salesforce Industries' declarative development framework for building guided digital experiences without code. It provides four primary component types that work together:

Component dependency chain (build bottom-up):

Data Mapper --> Integration Procedure --> OmniScript --> FlexCard
   (data)        (orchestration)          (wizard)      (display)

Data Mappers read/write Salesforce data. Integration Procedures orchestrate Data Mappers, Apex, and HTTP calls. OmniScripts present guided UIs that invoke Integration Procedures. FlexCards display summary data and can launch OmniScripts.

Namespace Guide

OmniStudio exists in three namespace variants. You MUST detect the namespace before querying any component metadata.

Namespace Detection

Try querying a known object from each namespace. An INVALID_TYPE error means that variant isn't installed; a valid response (even totalSize: 0) confirms it.

Start with Core (the modern path) and fall back to Vlocity variants if it fails.

Object Name Mapping

See references/omnistudio-reference.md for the complete field-level mapping.

OmniScripts

OmniScripts are multi-step, interactive guided experiences (wizards). They collect user input, call server-side logic, and present results -- all declaratively.

Identification

Every OmniScript is uniquely identified by a Type / SubType / Language triplet (e.g., ServiceRequest / NewCase / English). Multiple versions can exist; only one is active per triplet.

In Core namespace, OmniScripts are stored in OmniProcess with IsIntegrationProcedure = false.

Element Types

Containers: Step, Conditional Block, Loop Block, Edit Block

Inputs: Text, Text Area, Number, Date, Date/Time, Checkbox, Radio, Select, Multi-select, Type Ahead, File, Currency, Email, Telephone, URL, Signature, Password, Range, Time

Display: Text Block, Headline, Aggregate, Disclosure, Image, Chart

Actions: DataRaptor Extract Action, DataRaptor Load Action, Integration Procedure Action, Remote Action, Navigate Action, Email Action, DocuSign Envelope Action

Logic: Set Values, Validation, Formula, Submit Action

Element Hierarchy

Elements use Level and Order fields to form a tree. Level 0 = Steps (pages in the wizard). Level 1+ = elements within steps. Order determines sequence within a level.

Data Flow

OmniScripts maintain a single JSON data structure passed through all steps. Elements read from and write to this shared JSON using merge field syntax (%fieldName%). Action elements map input/output between the JSON and server calls.

LWC-Enabled OmniScripts

LWC OmniScripts render using Lightning Web Components instead of Aura. Key differences:

• Use omnistudio-omniscript base component
• Custom elements must extend OmniscriptBaseMixin
• CSS styling uses SLDS tokens instead of Aura-specific classes
• Event model differs (LWC custom events vs Aura events)
• Cannot embed Aura components inside LWC OmniScripts

OmniScript Best Practices

• Limit to 7-10 input elements per Step for usability
• Add validation on all required inputs
• Configure error handling on every action element (showError, errorMessage)
• Use conditional visibility (show expressions) to hide irrelevant fields
• Fire data-loading actions on step entry, not on OmniScript load
• Never embed OmniScript A in B if B embeds A (circular embedding causes infinite loops)
• Never hardcode Salesforce record IDs in PropertySetConfig

FlexCards

FlexCards are declarative UI cards that display at-a-glance information with data from Integration Procedures, SOQL, or REST sources.

Data Sources

FlexCards bind to data sources configured in the DataSourceConfig JSON field on OmniUiCard. Core namespace splits what Vlocity stored in a single Definition blob into separate DataSourceConfig and PropertySetConfig fields.

Data sources pass context via input parameters (e.g., {recordId}) and map response fields to card elements using {fieldName} merge syntax.

Layout Types

Actions and Child Cards

FlexCards can launch OmniScripts via action buttons, passing context data as input. Cards can embed other FlexCards as child cards (limit nesting to 2 levels for performance). LWC FlexCards follow the same patterns but render as Lightning Web Components.

FlexCard Best Practices

• Always configure empty-state messaging when data source returns no records
• Use SLDS design tokens for styling (no hardcoded colors)
• Add aria-label on all interactive elements for accessibility
• Limit child card nesting to 2 levels
• Verify all referenced Integration Procedures are active before deployment

Integration Procedures

Integration Procedures (IPs) are server-side orchestrations that combine Data Mapper actions, Apex calls, HTTP callouts, and conditional logic into declarative multi-step operations.

Identification

IPs use a Type / SubType pair as their key (e.g., AccountOnboarding / Standard). In Core namespace, IPs are stored in OmniProcess with IsIntegrationProcedure = true.

Action Types

Response Mapping

Each element's output is namespaced under its element name in the response JSON. Reference upstream outputs in downstream inputs using %elementName:keyPath% syntax.

Caching

IPs support platform cache for read-heavy orchestrations. Set cacheType and cacheTTL in the procedure's PropertySet. Never cache procedures that perform DML -- cached results bypass actual data operations.

Integration Procedure Best Practices

• Deploy all referenced Data Mappers before deploying the IP
• Set LIMIT on all DataRaptor Extract actions to avoid governor limits
• Wrap DataRaptor Load actions in error handling (try/catch or conditional checks)
• Never create circular IP call chains (A calls B calls A)
• Use parallel execution for independent elements
• Never hardcode Salesforce IDs or API credentials in PropertySetConfig
• Use Named Credentials for external API authentication

Data Mappers / DataRaptors

Data Mappers (formerly DataRaptors) provide declarative data access for OmniStudio. They handle Extract, Transform, and Load operations against Salesforce objects.

Types

Metadata Structure

Data Mappers are stored as OmniDataTransform records (parent) with OmniDataTransformItem records (field mappings). Watch out: the child-to-parent lookup field uses the unabbreviated spelling OmniDataTransformationId — developers often mistakenly try OmniDataTransformId, which doesn't exist.

Turbo Extract Limitations

Turbo Extract does NOT support: formula fields, related lists, aggregate queries, polymorphic fields. Fall back to standard Extract for these cases.

Data Mapper Best Practices

• Always specify explicit field lists (no wildcards)
• Add LIMIT and filter conditions on all Extract queries
• Validate field-level security before deploying Load Data Mappers
• Use upsert keys to prevent duplicate records on Load
• Activate Data Mappers after deployment (inactive ones are not callable)
• Name using DR_[Type]_[Object]_[Purpose] convention in PascalCase

Dependency Mapping

OmniStudio components form a directed dependency graph. Trace dependencies to understand impact before modifying any component.

Dependency Sources

Dependency Queries (Core Namespace)

# OmniScript/IP elements with config
sf data query -q "SELECT Id, OmniProcessId, Name, Type, PropertySetConfig FROM OmniProcessElement WHERE OmniProcessId = '<id>'" -o <org> --json

# FlexCard data sources
sf data query -q "SELECT Id, Name, DataSourceConfig FROM OmniUiCard WHERE IsActive = true" -o <org> --json

# Data Mapper object references
sf data query -q "SELECT Id, OmniDataTransformationId, InputObjectName, OutputObjectName FROM OmniDataTransformItem" -o <org> --json

Impact Analysis

When modifying a component, trace all dependents upstream: 1. Changing a Data Mapper? Find all IPs and OmniScripts referencing its bundle name 2. Changing an IP? Find all OmniScripts with matching ipMethod and FlexCards with matching data source 3. Changing an OmniScript? Find all FlexCards with launch actions targeting it 4. Check both active and inactive components -- inactive ones may become active later

Migration Patterns

Vlocity to OmniStudio Core Migration

When migrating from Vlocity (vlocity_cmt or vlocity_ins) to OmniStudio Core:

1. Inventory: Catalog all components in the source namespace using analysis queries 2. Namespace conversion: Map all object and field API names from Vlocity to Core equivalents (see Namespace Guide above) 3. Export: Extract component definitions as JSON from source org 4. Transform: Convert namespace-prefixed field references in PropertySetConfig, DataSourceConfig, and element configurations 5. Deploy order: Data Mappers first, then Integration Procedures, then OmniScripts, then FlexCards 6. Validate: Run each component in the target org, verifying data flow end-to-end 7. Decommission: Deactivate Vlocity components only after Core equivalents are verified

Key conversion points:

• vlocity_cmt__OmniScript__c becomes OmniProcess
• vlocity_cmt__PropertySet__c becomes PropertySetConfig
• vlocity_cmt__DRBundle__c becomes OmniDataTransform
• vlocity_cmt__Definition__c on FlexCards becomes DataSourceConfig on OmniUiCard
• IsIntegrationProcedure boolean discriminates OmniScripts from IPs in Core

Gotchas

Workflow

1. Detect namespace using the probe queries above 2. Inventory existing components -- query all OmniScripts, IPs, FlexCards, and Data Mappers 3. Map dependencies between components before making changes 4. Build bottom-up -- Data Mappers, then IPs, then OmniScripts, then FlexCards 5. Deploy in dependency order to avoid broken references 6. Activate components after deployment (inactive components are not callable at runtime) 7. Test end-to-end -- verify data flows from Data Mapper through IP to OmniScript/FlexCard

CLI Quick Reference

# List OmniScripts
sf data query -q "SELECT Id,Type,SubType,Language,IsActive,VersionNumber FROM OmniProcess WHERE IsIntegrationProcedure=false" -o <org>

# List Integration Procedures
sf data query -q "SELECT Id,Type,SubType,IsActive FROM OmniProcess WHERE IsIntegrationProcedure=true" -o <org>

# List FlexCards
sf data query -q "SELECT Id,Name,IsActive FROM OmniUiCard" -o <org>

# List Data Mappers
sf data query -q "SELECT Id,Name,Type,IsActive FROM OmniDataTransform" -o <org>

# Retrieve OmniStudio metadata
sf project retrieve start -m OmniScript:<Name> -o <org>
sf project retrieve start -m OmniIntegrationProcedure:<Name> -o <org>
sf project retrieve start -m OmniUiCard:<Name> -o <org>
sf project retrieve start -m OmniDataTransform:<Name> -o <org>

# Deploy OmniStudio metadata (respect dependency order)
sf project deploy start -m OmniDataTransform -o <org>
sf project deploy start -m OmniIntegrationProcedure -o <org>
sf project deploy start -m OmniScript -o <org>
sf project deploy start -m OmniUiCard -o <org>

References

• OmniStudio Reference -- namespace field mapping, metadata structures, element types, deployment order, migration checklist

OmniStudio Reference

Deep reference for OmniStudio component metadata, namespace mappings, and operational guidance.

Namespace Detection Queries

Run these queries sequentially. The first successful result identifies the installed namespace.

-- Probe 1: Core (Industries Cloud, Spring '22+)
SELECT COUNT() FROM OmniProcess

-- Probe 2: Vlocity CMT (Communications, Media, Energy)
SELECT COUNT() FROM vlocity_cmt__OmniScript__c

-- Probe 3: Vlocity INS (Insurance, Health)
SELECT COUNT() FROM vlocity_ins__OmniScript__c

A successful query returns exit code 0 with totalSize in JSON output. An INVALID_TYPE error means that namespace is absent.

Complete Namespace Field Mapping

Primary Objects

Key Fields

OmniScript / IP Metadata Structure (Core)

OmniProcess fields: Id, Name, Type, SubType, Language, VersionNumber, IsActive, IsIntegrationProcedure (boolean discriminator), OmniProcessType (computed), PropertySetConfig (JSON), LastModifiedDate.

OmniProcessElement fields: Id, OmniProcessId (parent lookup), Name, Type (element type), Level (0=Step, 1+=children), Order (sequence), PropertySetConfig (JSON), IsActive.

PropertySetConfig Structure (Action Elements)

DataRaptor Extract/Load Action:

{
  "bundle": "DR_Extract_Account_Details",
  "inputMap": {
    "AccountId": "%ContextId%"
  },
  "outputMap": {},
  "optionsMap": {},
  "showError": true,
  "errorMessage": "Failed to retrieve account data"
}

Integration Procedure Action:

{
  "ipMethod": "AccountOnboarding_Standard",
  "inputMap": {
    "accountId": "%AccountId%",
    "requestType": "new"
  },
  "outputMap": {},
  "optionsMap": {
    "useFuture": false
  },
  "showError": true,
  "errorMessage": "Onboarding procedure failed"
}

Remote Action:

{
  "remoteClass": "AccountService",
  "remoteMethod": "validateAddress",
  "inputMap": {
    "street": "%Street%",
    "city": "%City%"
  },
  "outputMap": {}
}

FlexCard Metadata Structure

OmniUiCard fields: Id, Name, IsActive, VersionNumber, OmniUiCardType, AuthorName, DataSourceConfig (JSON -- data sources), PropertySetConfig (JSON -- layout/states/actions), LastModifiedDate. There is NO Definition field on OmniUiCard in Core namespace.

DataSourceConfig Structure

{
  "dataSource": {
    "type": "IntegrationProcedures",
    "value": {
      "ipMethod": "AccountSummary_Fetch",
      "vlocityAsync": false,
      "inputMap": {
        "recordId": "{recordId}"
      },
      "resultVar": ""
    },
    "orderBy": {
      "name": "",
      "isReverse": ""
    },
    "contextVariables": []
  }
}

Valid dataSource.type values: IntegrationProcedures (must be plural), SOQL, ApexRemote, REST, Custom.

Context variables for input: {recordId} (record page), {userId} (running user), {param.customKey} (URL/parent card).

Merge field syntax: {fieldName}, {Object.Field}, {records[0].Name}.

Integration Procedure Response Pattern

Each element writes output namespaced under its element name. Reference upstream outputs with %elementName:keyPath%:

Input JSON --> [GetAccount] --> [ValidateData] --> [CreateCase] --> Output JSON

Result: { "GetAccount": { "Name": "Acme" }, "ValidateData": { "isValid": true }, ... }

Caching: Set cacheType, cacheTTL (seconds), cachePartition in PropertySet. Only cache read-only IPs. Cached results bypass execution on cache hit.

DataRaptor / Data Mapper Examples

Extract Configuration

Query Account with related Contacts:

OmniDataTransform:
  Name: DR_Extract_Account_Details
  Type: Extract
  IsActive: true

OmniDataTransformItem records:
  Item 1: InputObjectName=Account, OutputObjectName=Account
    Field: Id -> AccountId
    Field: Name -> AccountName
    Field: Industry -> Industry
    Filter: Id = :AccountId (input parameter)
    LIMIT: 1

  Item 2: InputObjectName=Contact, OutputObjectName=Contacts
    Field: Id -> ContactId
    Field: FirstName -> FirstName
    Field: LastName -> LastName
    Field: Email -> Email
    Relationship: AccountId = Account.Id
    LIMIT: 50

Transform Configuration

Flatten nested Account-Contact structure:

OmniDataTransform:
  Name: DR_Transform_Account_Flatten
  Type: Transform
  IsActive: true

OmniDataTransformItem records:
  Item 1: InputObjectName=Account:Name, OutputObjectName=AccountName
  Item 2: InputObjectName=Contacts[0]:FirstName, OutputObjectName=PrimaryContactFirst
  Item 3: InputObjectName=Contacts[0]:LastName, OutputObjectName=PrimaryContactLast

Transform operates entirely in memory -- no SOQL or DML.

Load Configuration

Create a new Case record:

OmniDataTransform:
  Name: DR_Load_Case_Create
  Type: Load
  IsActive: true

OmniDataTransformItem records:
  Item 1: InputObjectName=Subject, OutputObjectName=Case:Subject
  Item 2: InputObjectName=Description, OutputObjectName=Case:Description
  Item 3: InputObjectName=AccountId, OutputObjectName=Case:AccountId
  Item 4: InputObjectName=Priority, OutputObjectName=Case:Priority
  DML Operation: Insert

Common OmniScript Element Types

Input Elements Configuration

Container Elements Configuration

IP Action Type Reference

Deployment Order for OmniStudio Components

Always deploy in dependency order to avoid broken references:

1. OmniDataTransform      (Data Mappers -- no dependencies on other OmniStudio)
2. OmniIntegrationProcedure (IPs -- depend on Data Mappers, Apex classes)
3. OmniScript              (OmniScripts -- depend on IPs and Data Mappers)
4. OmniUiCard              (FlexCards -- depend on IPs, may launch OmniScripts)

Deploy each type sequentially, then activate components via IsActive=true update.

Dependency Mapping Queries

Find All Components Referencing a Data Mapper

-- Find IPs/OmniScripts using a specific Data Mapper (by bundle name in element config)
SELECT Id, OmniProcessId, Name, Type, PropertySetConfig
FROM OmniProcessElement
WHERE PropertySetConfig LIKE '%DR_Extract_Account_Details%'

Find All FlexCards Using a Specific IP

SELECT Id, Name, DataSourceConfig
FROM OmniUiCard
WHERE DataSourceConfig LIKE '%AccountSummary_Fetch%'
AND IsActive = true

Find All OmniScripts Calling a Specific IP

SELECT Id, OmniProcessId, Name, Type, PropertySetConfig
FROM OmniProcessElement
WHERE Type = 'Integration Procedure Action'
AND PropertySetConfig LIKE '%AccountOnboarding_Standard%'

Component Inventory

Use SELECT COUNT() FROM <object> with appropriate filters (IsIntegrationProcedure=true/false for OmniProcess) to inventory components. Add GROUP BY IsActive for active/inactive breakdown.

Migration Checklist: Vlocity to Core

Pre-Migration

• [ ] Identify installed Vlocity namespace (vlocity_cmt or vlocity_ins)
• [ ] Run full component inventory in source org
• [ ] Map all cross-component dependencies
• [ ] Document custom Apex classes referenced by Remote Actions
• [ ] Identify components with external HTTP callout configurations
• [ ] Verify target org has Industries Cloud / OmniStudio Core license
• [ ] Confirm target org API version supports Core namespace (API 234.0+ / Spring '22+)

Object and Field Conversion

• [ ] Replace vlocity_cmt__OmniScript__c references with OmniProcess
• [ ] Replace vlocity_cmt__Element__c references with OmniProcessElement
• [ ] Replace vlocity_cmt__VlocityUITemplate__c references with OmniUiCard
• [ ] Replace vlocity_cmt__DRBundle__c references with OmniDataTransform
• [ ] Replace vlocity_cmt__DRMapItem__c references with OmniDataTransformItem
• [ ] Update field references: vlocity_cmt__PropertySet__c to PropertySetConfig
• [ ] Update field references: vlocity_cmt__Type__c to Type
• [ ] Update field references: vlocity_cmt__SubType__c to SubType
• [ ] Update FlexCard: vlocity_cmt__Definition__c to DataSourceConfig
• [ ] Update DM items: vlocity_cmt__InterfaceObject__c to InputObjectName
• [ ] Update DM items: vlocity_cmt__TargetFieldObjectType__c to OutputObjectName

Deployment

• [ ] Deploy Data Mappers to target org and activate
• [ ] Deploy Integration Procedures to target org and activate
• [ ] Deploy OmniScripts to target org and activate
• [ ] Deploy FlexCards to target org and activate
• [ ] Test each component individually
• [ ] Test end-to-end flows (FlexCard -> OmniScript -> IP -> Data Mapper)

Post-Migration

• [ ] Verify all components appear in OmniStudio Designer
• [ ] Confirm LWC OmniScripts render correctly (if applicable)
• [ ] Run regression tests on all business processes
• [ ] Monitor error logs for namespace-related failures
• [ ] Deactivate Vlocity components in source org (after validation period)
• [ ] Document any components that required manual adjustment

Troubleshooting Common Errors