SfSkills Domains Docs GitHub

Home / omnistudio / omniscript-versioning

omniscript-versioning

Use when managing OmniScript versions: activating new versions, deactivating prior versions, testing a specific version before activation, rolling back to a previous version, or understanding version identity (Type/Subtype/Language triplet). NOT for OmniStudio deployment or DataPack migration (use omnistudio/omnistudio-deployment-datapacks).

Open the skill folder on GitHub

OmniScript Versioning

This skill activates when a practitioner needs to manage the version lifecycle of an OmniScript: activating a new version, deactivating a prior version, testing a specific version before promotion, or rolling back to a previously active version. OmniScript versioning is identity-based — the combination of Type, Subtype, and Language defines a unique OmniScript, and only one version per triplet can be active at a time.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

Version Identity: Type + Subtype + Language

An OmniScript is uniquely identified by its Type, Subtype, and Language triplet. Version numbers exist within that triplet. You can have version 1, 2, 3 of CreateCase / Default / English — they are all the same OmniScript at different points in time.

This means:

Only One Active Version Per Triplet

At any point in time, only one version of a given Type+Subtype+Language triplet can be Active. When you activate version 3, version 2 is implicitly deactivated. The platform does not prompt or warn you — the transition is immediate.

Practical implication: if version 2 is active in production and you need to test version 3 before fully replacing it, you cannot run both simultaneously in the same org. You must test in a sandbox that mirrors production, then activate version 3 in production when ready.

Rollback = Reactivate a Prior Version

There is no dedicated rollback command. Rolling back means reactivating an older version number. If version 3 has a defect after activation:

  1. Navigate to the version list for the triplet.
  2. Open version 2 (or whichever was previously active).
  3. Click Activate.
  4. Version 3 is immediately deactivated; version 2 is now active.

The prior version's definition is intact as long as it has not been deleted from the org. Versions are not deleted when deactivated — they persist until manually deleted.

Activation via Metadata API and DataPacks

OmniScripts can also be activated and deactivated programmatically:

This means CI/CD pipelines must be careful: deploying a DataPack with activate: true will immediately deactivate whatever version was previously active in the target org.

Common Patterns

Activating a New Version

When to use: A new version has been built and tested in a sandbox and is ready to replace the current active version in production.

How it works:

  1. Open OmniStudio > OmniScripts.
  2. Filter by Type and Subtype to find all versions of the triplet.
  3. Confirm the new version number exists and has Status = Inactive.
  4. Click the row menu > Activate on the new version.
  5. Confirm: the new version shows Active; the previously active version shows Inactive.
  6. Test the live OmniScript immediately post-activation (launch URL or embedded component).

Why not activate in production directly after editing: Editing an OmniScript in production does not create a new version automatically. You must explicitly save as a new version and then activate it. Editing the active version in place is not recommended — it changes the definition live without a rollback point.

Rolling Back to a Prior Version

When to use: The newly activated version has a defect and the prior version must be restored.

How it works:

  1. Open OmniStudio > OmniScripts.
  2. Filter by Type and Subtype.
  3. Identify the version that was active before the bad activation (e.g., version 2 if version 3 just broke things).
  4. Click Activate on version 2.
  5. Version 3 is deactivated immediately. Version 2 is now serving users.
  6. Document the rollback and create a work item to fix version 3 before re-promoting.

Decision Guidance

SituationRecommended ApproachReason
Testing new version without affecting active usersTest in sandbox, not same production orgOnly one active version per triplet — you cannot run a draft alongside the live version
CI/CD pipeline importing DataPack with OmniScriptSet activate: false on import in UAT, activate: true only in scheduled production deploymentPrevents accidental activation in wrong environment
Defect in newly activated versionActivate the prior version number immediatelyFastest recovery; no deployment needed
Version accidentally deleted before rollbackRetrieve from DataPack backup, re-import with activate flagAlways export DataPacks before making version changes in production
Comparing two versions side by sideExport both versions as JSON, diff the filesNo native compare UI; JSON export enables text diff
  1. Identify the OmniScript triplet (Type + Subtype + Language) and the target version number to activate.
  2. Confirm the version has been fully tested in a sandbox that reflects the production configuration.
  3. Export a DataPack of the currently active version to a backup location before making any changes. This is your rollback artifact.
  4. In the target org, navigate to OmniStudio > OmniScripts and activate the new version.
  5. Immediately test the live OmniScript by launching it directly and running through the key steps.
  6. If a defect is found, activate the prior version number within the same triplet to roll back.
  7. Document the version change in your release notes: old version number, new version number, change summary, and activation timestamp.

Review Checklist

Salesforce-Specific Gotchas

  1. Activating a new version immediately deactivates the prior one — there is no grace period, staged rollout, or warning. Users currently mid-session on the OmniScript may experience an interruption if a session was in progress during activation. Schedule activations during low-traffic windows.
  2. DataPack import with activate:true bypasses your approval process — if your CI/CD pipeline automatically imports DataPacks with activation enabled, a bad push to the deployment branch will activate an untested version in production. Always control the activate flag explicitly in CI pipelines.
  3. Deleted versions cannot be recovered from the UI — if you delete version 2 and then need to roll back from version 3, the only recovery path is re-importing from a DataPack backup. Export DataPacks before destructive operations.
  4. Activation does not validate OmniScript correctness — activating a version with a misconfigured step, broken Remote Action reference, or invalid LWC element succeeds silently. The error only surfaces when a user runs the script. Always test before activating.
  5. Version numbers are sequential integers, not semantic versions — OmniScript version numbers auto-increment (1, 2, 3...). You cannot set a custom version label. Document the business meaning of each version number in your release notes or a companion custom object.

Output Artifacts

ArtifactDescription
Activation checklistOrdered pre/during/post activation steps for the specific triplet being promoted
DataPack backupExported DataPack of the currently active version before any version change
Rollback procedureNamed steps to reactivate the prior version and verify the rollback succeeded

Package files