Omnistudio Datapack Migration

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:

• Confirm both source and target orgs are running the same OmniStudio runtime (Package Runtime / Standard Runtime). Cross-runtime DataPack migrations are not supported — use the OmniStudio Migration Assistant (OMA) for managed-package-to-standard-runtime migration, which is a different tool entirely.
• Confirm OmniStudio version (VBT version for Package Runtime). Version mismatches between source and target can cause import failures.
• The most common wrong assumption: packExport captures all versions by default. It does not — packExport only exports the active version of each component. Draft versions are silently omitted. Spring '25+ adds an option to export all versions explicitly.
• Version-number collision is a critical gotcha: if the same component version already exists in the target org, the import skips it silently (ALREADY_EXISTS status) without overwriting or warning. The practitioner sees a successful import with no indication that the component was not updated.

Core Concepts

DataPack Export Modes

DataPack exports have two modes:

• Active-only export (default) — packExport exports only the currently active version of each component. Draft versions, newer inactive versions, and previous versions are not included. This is the default behavior in all versions prior to Spring '25.
• All-versions export (Spring '25+) — Spring '25 introduces the ability to export all versions of a component. This must be explicitly enabled in the export configuration; the default remains active-only.

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:

• If a component with the same Type, Sub Type, and Version Number already exists in the target org (regardless of whether it is active), the import skips it silently with an ALREADY_EXISTS status
• The import summary reports success; there is no error or warning
• The previously active version continues serving traffic — the "migrated" version has not been applied

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:

• matchingKey controls how the import identifies whether a component already exists
• A custom matchingKey in the DataPack JSON that differs from the target org's settings causes the import to create a duplicate component instead of updating the existing one
• This produces orphaned components in the target org that must be manually cleaned up

OmniStudio Migration Assistant vs DataPack Migration

These are distinct tools for different scenarios:

• DataPack migration — org-to-org component migration between two orgs running the same runtime (Package-to-Package or Standard-to-Standard)
• OmniStudio Migration Assistant (OMA) — SF CLI plugin for migrating from managed-package runtime to Standard Runtime (OmniStudio on Core). OMA converts managed-package components to standard-runtime format — it is NOT used for org-to-org migration

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

Recommended Workflow

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:

• Source and target orgs confirmed as same runtime type
• Version numbers from source documented before export
• Pre-import collision check performed in target org
• Export mode (active-only vs all-versions) explicitly chosen and confirmed
• packDeploy run with --activate flag
• Post-import active version verified in target org
• Environment-specific references remapped if applicable
• No orphaned duplicate components left from matchingKey conflicts

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

Related Skills

• omnistudio/omnistudio-ci-cd-patterns — use for pipeline automation of DataPack deployments
• omnistudio/omnistudio-deployment-datapacks — use for DataPack deployment configuration and CLI plugin setup
• devops/deployment-monitoring — use to monitor deployment success and set up post-deploy verification