SfSkills Domains Docs GitHub

Home / data / omnistudio-datapack-migration

omnistudio-datapack-migration

Use this skill when migrating OmniStudio components (OmniScript, Integration Procedures, DataRaptors, FlexCards) between Salesforce orgs using the DataPack export/import mechanism — covering version management, environment-specific data resolution, conflict handling, and silent-skip gotchas.

Open the skill folder on GitHub

OmniStudio DataPack Migration

This skill activates when a practitioner needs to migrate OmniStudio components between Salesforce orgs using the DataPack export/import mechanism. It covers the full migration lifecycle: export configuration, version management, silent-skip conflict resolution, environment-specific data remapping, and post-import activation verification.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

DataPack Export Modes

DataPack exports have two modes:

Migration plans must specify which export mode is appropriate — active-only for production deployments, all-versions for version history preservation.

Version-Number Collision and Silent Skip

The most dangerous DataPack migration behavior:

To resolve: either increment the version number in the source before re-exporting, or use the --overwrite flag (available in VBT v15+) to force overwrite of existing versions.

Custom matchingKey Override (VBT v15+)

Post-VBT v15, custom matchingKey values in DataPacks override the package default matching strategy:

OmniStudio Migration Assistant vs DataPack Migration

These are distinct tools for different scenarios:

Common Patterns

Pattern: Safe DataPack Migration Workflow

When to use: Any org-to-org OmniStudio component migration using DataPacks.

How it works:

  1. Export from source: run packExport with explicit component list; confirm active-only or all-versions mode
  2. Inspect the exported JSON for version numbers — note the version of each component
  3. In the target org: query existing components to detect version-number collisions before import
  4. If collision exists: increment version in source or use --overwrite
  5. Import to target: run packDeploy with --activate flag
  6. Post-import: verify active version in target org matches the expected version number

Why not the alternative: Skipping the pre-import collision check leads to silent skips. Skipping --activate creates or updates the component record but leaves the previous version active — the most common DataPack migration mistake.

Pattern: Environment-Specific Data Remapping

When to use: When the DataPack references org-specific IDs, Named Credentials, custom labels, or Record Type IDs that differ between environments.

How it works:

  1. Before export, identify all environment-specific references in the OmniScript/IP/DataRaptor: Named Credential names, Record Type Developer Names, custom label API names, external system URLs
  2. Use DataPack Transform to substitute environment-specific values at import time (VBT/OmniStudio supports JSON transform mappings in the package configuration)
  3. Alternatively: document all environment-specific values and manually update after import

Decision Guidance

SituationRecommended ApproachReason
Migrating active components between two Package Runtime orgsStandard DataPack packExport/packDeploy with --activateDefault migration path for Package Runtime
Draft versions need to be migrated alongside activeSpring '25 all-versions exportDefault active-only export silently omits drafts
Same version exists in target and content has changedUse --overwrite or increment version numberSilent skip (ALREADY_EXISTS) will not update the existing component
Migrating from managed-package runtime to Standard RuntimeOmniStudio Migration Assistant (OMA) CLI pluginOMA handles format conversion; DataPack migration does not
High-frequency migrations in a CI/CD pipelineSee omnistudio/omnistudio-ci-cd-patterns skillPipeline automation patterns are distinct from single migration operations

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

  1. Confirm this is a DataPack migration at all, then inventory the source.
    • Confirm source and target orgs are running the same OmniStudio runtime type — if not, stop and use the OmniStudio Migration Assistant instead.
    • List all components to migrate and their current active version numbers from the source org.
  2. Detect version-number collisions before you export. Query the target org for existing components with the same Type, Sub Type, and Version Number. A collision found here is a version bump; the same collision found after import is a silent no-op you will not be told about.
  3. Export, then read the export.
    • Run packExport from the source org; if draft versions are required, use the Spring '25+ all-versions export option explicitly.
    • Inspect the exported DataPack JSON to confirm all expected components and versions are included — drafts are silently omitted in default export mode.
  4. Resolve collisions, then import with activation.
    • Resolve any version collisions: either increment the source version number or prepare to use the --overwrite flag on import.
    • Run packDeploy with the --activate flag on the target org; --activate is mandatory — importing without it creates/updates the record but leaves the previous version active.
  5. Verify the import actually took. Confirm each component in the target org shows the expected version number in Active status; spot-check one component in Preview mode to confirm it runs correctly.

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. packDeploy without --activate leaves the old version active — Running packDeploy without --activate creates or updates the component record but does not change the active version. The previously active version continues serving runtime traffic. This is the most common DataPack migration mistake — the import shows success but users still see the old version.
  2. ALREADY_EXISTS is silent success — not an update — When a component with the same version already exists in the target, the import returns ALREADY_EXISTS status and moves on. The import summary shows no errors. The content of the existing component is not changed. Practitioners interpret this as a successful update when it is actually a no-op.
  3. Custom matchingKey overrides create duplicate components — Post-VBT v15, a DataPack with a custom matchingKey that doesn't match the target org's matchingKey settings creates a duplicate component rather than updating the existing one. The duplicate is inactive and appears in the component list causing confusion.

Output Artifacts

ArtifactDescription
DataPack export packageJSON file containing OmniStudio components exported from source org
Version collision reportList of components with version conflicts in the target org before import
Post-import activation checklistVerified active version numbers per component after deployment

Package files