omniscript-versioning

name	omniscript-versioning
description	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).
category	omnistudio
salesforce-version	Spring '25+
well-architected-pillars	["Operational Excellence","Reliability"]
triggers	["how do I activate a new version of an OmniScript in production","how do I roll back to the previous OmniScript version after a bad activation","I accidentally activated the wrong OmniScript version and users are seeing errors","what happens to the old OmniScript version when I activate a new one","how do I test an OmniScript version before activating it in production"]
tags	["omniscript","versioning","activation","rollback","omnistudio"]
inputs	["OmniScript Type, Subtype, and Language (the identity triplet)","Current active version number and the new version number to activate","Test results for the new version in a sandbox"]
outputs	["Activation checklist for the target version","Rollback procedure if the new version needs to be reverted","Version comparison guidance"]
dependencies	[]
runtime_orphan	true
version	1.0.0
author	Pranav Nagrecha
updated	"2026-04-04T00:00:00.000Z"

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:

• Confirm the OmniScript's identity triplet: Type (e.g., CreateCase), Subtype (e.g., Default), and Language (e.g., English). Every operation targets this specific triplet. Changing any part of the triplet creates a distinct OmniScript.
• Know the current active version number. You can find this in OmniStudio > OmniScripts by filtering on the triplet and looking for the row with Status = Active.
• Confirm that the new version has been tested in the target org or a matching sandbox before activation. There is no staged promotion mechanism — activation is immediate.

---

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:

• If you need to test a change in isolation without affecting production users, you must test in a separate org/sandbox — there is no draft/staging state within a single org.
• If you change the Type or Subtype, you create a completely new OmniScript, not a new version of the existing one.

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:

• Metadata API: The OmniProcess metadata type includes an IsActive field. Deploying a version with IsActive = true activates it.
• DataPacks: When importing a DataPack containing an OmniScript, the activate option controls whether the imported version becomes active immediately.

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

Situation	Recommended Approach	Reason
Testing new version without affecting active users	Test in sandbox, not same production org	Only one active version per triplet — you cannot run a draft alongside the live version
CI/CD pipeline importing DataPack with OmniScript	Set activate: false on import in UAT, activate: true only in scheduled production deployment	Prevents accidental activation in wrong environment
Defect in newly activated version	Activate the prior version number immediately	Fastest recovery; no deployment needed
Version accidentally deleted before rollback	Retrieve from DataPack backup, re-import with activate flag	Always export DataPacks before making version changes in production
Comparing two versions side by side	Export both versions as JSON, diff the files	No native compare UI; JSON export enables text diff

---

Recommended Workflow

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

• OmniScript Type, Subtype, and Language triplet confirmed
• New version tested in a matching sandbox before production activation
• DataPack backup of the current active version exported and stored
• Activation completed and confirmed (new version Active, old version Inactive)
• Post-activation smoke test executed and passed
• Version change documented in release notes with activation timestamp

---

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

Artifact	Description
Activation checklist	Ordered pre/during/post activation steps for the specific triplet being promoted
DataPack backup	Exported DataPack of the currently active version before any version change
Rollback procedure	Named steps to reactivate the prior version and verify the rollback succeeded

---

Related Skills

• omnistudio/omnistudio-deployment-datapacks — DataPack export, import, and CI/CD for OmniStudio components
• omnistudio/omniscript-design-patterns — OmniScript design and step configuration
• omnistudio/omnistudio-debugging — debugging OmniScript runtime errors