SfSkills Domains Docs GitHub

Home / data / omnistudio-metadata-management

omnistudio-metadata-management

Use this skill when tracking, auditing, or cleaning up OmniStudio component dependencies and cross-references — covering the four OmniStudio metadata API types (OmniProcess, OmniDataTransform, OmniUiCard, OmniInteractionConfig), dependency graph construction from embedded JSON bodies, impact analysis before deleting or modifying a component, and stale-component cleanup.

Open the skill folder on GitHub

OmniStudio Metadata Management

This skill activates when a practitioner needs to track, audit, or clean up OmniStudio component dependencies and cross-references. It covers how to build accurate dependency graphs from the four OmniStudio metadata API types, why the standard Tooling API MetadataComponentDependency object does not resolve embedded JSON references between OmniStudio components, and how to enable and enforce OmniStudio Metadata API Support uniformly across an org pipeline.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

The Four OmniStudio Metadata API Types

OmniStudio Metadata API Support introduces four metadata types that replace legacy Vlocity DataPack-based deployment for Standard Runtime orgs:

Metadata TypeCovers
OmniProcessOmniScripts and Integration Procedures
OmniDataTransformDataRaptors (Extract, Load, Transform)
OmniUiCardFlexCards
OmniInteractionConfigInteraction Launcher configurations

Each type exposes the component as a retrievable/deployable metadata file rather than a DataPack JSON blob. The component body is still a rich JSON structure containing the full definition — element tree, actions, remote calls, and embedded references to other components.

OmniStudio Metadata API Support must be enabled in every org that participates in a deployment pipeline. A pipeline that mixes orgs with the setting enabled and orgs without it will encounter metadata type mismatches and deployment failures because the component representation differs between modes.

Embedded JSON References Are Not Tooling API Dependency Edges

The Tooling API MetadataComponentDependency object is the standard platform mechanism for dependency tracking. For many metadata types it works correctly — for example, it resolves Apex class references, Flow references to custom objects, and LWC component composition graphs.

For OmniStudio components, MetadataComponentDependency does not resolve cross-component references. A FlexCard that invokes a DataRaptor stores that reference inside its propertySet JSON body as a string field (dataRaptorBundleName). A FlexCard that calls an Integration Procedure stores the reference inside actionList[].actionAttributes.remoteClass. An OmniScript that calls an Integration Procedure stores the reference inside childElements[].propertySet.remoteClass. None of these fields are exposed as tooling API dependency edges.

This means that querying MetadataComponentDependency for OmniStudio components returns only structural metadata relationships (such as a component belonging to a namespace), not the meaningful cross-component call graph. Practitioners who rely on this query to build impact-analysis lists will see an incomplete or empty graph and will incorrectly conclude that a component has no dependents.

Dependency Resolution Requires JSON Body Parsing

Because cross-component references live inside embedded JSON, the only reliable way to build an OmniStudio dependency graph is to:

  1. Retrieve all OmniStudio metadata files for the org using sf project retrieve start with the four metadata types.
  2. Parse each component's JSON body and extract the cross-reference fields for the relevant component type.
  3. Build an in-memory graph of caller → callee relationships.
  4. Run reachability or impact analysis over that graph.

Key JSON paths to extract for each component type:

References use the component's API name, not its Salesforce ID, so the graph can be constructed from retrieved metadata files without org connectivity after the initial retrieve.

OmniStudio Metadata API Support Enablement Requirements

Enabling OmniStudio Metadata API Support is a one-way toggle at the org level. Once enabled, OmniStudio components are exposed as the four metadata types and can no longer be deployed via DataPacks in that org. The setting must be consistent across every org in the pipeline — dev sandboxes, QA, UAT, staging, and production must all have the same setting.

If a pipeline mixes modes — one sandbox has Metadata API Support enabled while another does not — the deployed metadata representation will be incompatible. A retrieve from the Standard Runtime org produces OmniProcess XML; deploying that XML to a legacy org without the setting enabled fails because the metadata type is not recognized.

Common Patterns

Pattern: Full Org OmniStudio Dependency Graph

When to use: Before a major refactor, large deletion, or component rename that could break calling components in production.

How it works:

  1. Retrieve all four OmniStudio metadata types from the target org: sf project retrieve start --metadata OmniProcess OmniDataTransform OmniUiCard OmniInteractionConfig
  2. Parse each retrieved XML file. The component body is base64-encoded JSON inside the <content> element; decode it first.
  3. For each FlexCard, extract propertySet.dataRaptorBundleName and all actionList[*].actionAttributes.remoteClass entries.
  4. For each OmniScript and Integration Procedure (OmniProcess), extract all childElements[*].propertySet.remoteClass and childElements[*].propertySet.dataRaptorBundleName entries.
  5. Build a dictionary: {callee_api_name: [list of caller api names]}.
  6. To find all dependents of a target component, look up its API name in the dictionary.

Why not the alternative: Querying MetadataComponentDependency via Tooling API returns no cross-component edges for OmniStudio components. An impact analysis built on that query will miss all actual dependencies and give a false "safe to delete" signal.

Pattern: Stale Component Identification

When to use: Periodic org hygiene, pre-release cleanup, or license usage reduction.

How it works:

  1. Build the full dependency graph as above.
  2. Collect the set of all components that appear as a callee (are referenced by at least one other component).
  3. Collect the set of all components that appear as a caller.
  4. Components that appear in neither set — not called by anything and not calling anything — are leaf nodes with no inbound or outbound references. These are stale candidates.
  5. Cross-reference against recently-active usage logs (OmniProcess execution events in Event Monitoring if available) before deleting — a FlexCard may be launched directly from an App Page and have no JSON-body reference from another OmniStudio component.
  6. Archive stale components by setting them to Inactive status before deletion; maintain a list for audit.

Why not the alternative: Deleting without the dependency graph risks removing components that are called by others or that call shared DataRaptors — orphaning callers that fail silently at runtime.

Pattern: Pre-Deletion Impact Check

When to use: Any time a single OmniStudio component is being deleted, renamed, or substantially reworked.

How it works:

  1. Build the caller-callee graph (or use a previously generated snapshot if recent).
  2. Look up the target component's API name as a callee.
  3. Report all callers. Review each caller to determine whether the reference can be updated or whether the caller's behavior changes.
  4. If callers exist: update all calling components to reference the new API name or replacement component before removing the original.
  5. After updates: re-retrieve metadata, re-parse, and confirm the deleted component's API name no longer appears in any callee list.

Decision Guidance

SituationRecommended ApproachReason
Need to find all OmniStudio components that call a specific DataRaptorRetrieve + JSON body parse; do NOT use Tooling API MetadataComponentDependencyTooling API does not surface embedded JSON references
Need to determine whether it is safe to delete an OmniScriptBuild full caller-callee graph from retrieved metadata; check for inbound referencesRisk of orphaning callers that fail at runtime
Org pipeline mixes Metadata-API-enabled and DataPack-mode orgsBlock deployment until all orgs enable OmniStudio Metadata API Support uniformlyMixed-mode deployment causes metadata type mismatch failures
Need automated dependency graph generation in CI/CDImplement custom JSON parsing step in pipeline; do NOT rely on Tooling APINo native platform tooling currently resolves OmniStudio cross-component edges
Planning to use upcoming Salesforce automated dependency managementWait for mid-2026 GA release; do not architect around a roadmap featureRoadmap announced Feb 2026 but not yet shipped as of Spring '25
Auditing for stale / unused OmniStudio componentsBuild dependency graph + check against no-inbound-reference setComponents with no callers are candidates for archiving

Step-by-step instructions for an AI agent or practitioner working on this task:

  1. Confirm OmniStudio Metadata API Support is enabled in the org and that all orgs in the pipeline share the same setting — if any org in the pipeline has it disabled, stop and resolve the mixed-mode conflict first.
  2. Retrieve all four OmniStudio metadata types from the org: sf project retrieve start --metadata OmniProcess OmniDataTransform OmniUiCard OmniInteractionConfig --target-org <alias>.
  3. For each retrieved file, decode the base64 JSON body from inside the <content> XML element and save it as a parseable JSON object.
  4. Parse each component's JSON body using the type-specific reference field paths (see Core Concepts) to extract all cross-component references (DataRaptor names, Integration Procedure names, OmniScript names).
  5. Build the caller-callee dictionary from the extracted references; verify the graph by spot-checking a known FlexCard → DataRaptor relationship.
  6. For impact analysis: look up the target component's API name as a callee and list all callers; communicate these to the practitioner before any change is made.
  7. For stale-component identification: compare all component API names against the set of components that appear as callees; report components with zero inbound references for archival review.

Review Checklist

Run through these before marking work in this area complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. MetadataComponentDependency returns zero edges for OmniStudio cross-component calls — The Tooling API dependency object tracks explicit metadata relationships, not embedded JSON body references. Querying it for OmniUiCard or OmniProcess components will return results only for namespace-level structural relationships, not for the FlexCard → DataRaptor or OmniScript → Integration Procedure call chains that matter operationally. Practitioners who trust this query will delete a DataRaptor that is still in active use by multiple FlexCards.
  2. OmniStudio Metadata API Support is a one-way toggle with pipeline-wide impact — Enabling the setting in one org and not another creates a split-mode pipeline where component representations are incompatible. This is not detectable from within a single org — the failure only surfaces when a deployment from the Metadata-API-mode org is applied to a DataPack-mode org or vice versa.
  3. Component API names in JSON bodies are case-sensitive — When parsing embedded references to match against component inventory, exact case must be preserved. A DataRaptor named GetAccountData will not match a reference to getAccountData in the parsed graph, creating false negatives in the dependency check.
  4. FlexCards can reference other FlexCards as child cards — Nested FlexCard references (childCards) are stored in the childElements array of the parent FlexCard's JSON body. An impact analysis that only checks DataRaptor and Integration Procedure references will miss FlexCard-to-FlexCard dependency chains.
  5. Automated dependency management is not yet available — Salesforce announced automated OmniStudio dependency management and atomic deployment on their February 2026 roadmap post, targeting mid-2026. As of Spring '25, this feature has not shipped. Pipeline designs that assume it is available will fail in production orgs.

Output Artifacts

ArtifactDescription
OmniStudio dependency graphCaller-callee dictionary keyed by component API name, built from parsed JSON bodies
Impact listAll caller components for a specified target component, used before deletion or rename
Stale component reportComponents with no inbound references from other OmniStudio components, flagged for archival review
Metadata API enablement auditPer-org confirmation that OmniStudio Metadata API Support is enabled uniformly across the pipeline

Package files