SfSkills Domains Docs GitHub

Home / flow / flow-versioning-strategy

flow-versioning-strategy

Manage Flow versions: activation policy, paused interview compatibility, cleanup cadence, and breaking-change detection. Trigger keywords: flow version management, activate flow version, paused interview, flow cleanup, flow breaking change, flow rollback. NOT for the deploy-time activation order of FlowDefinition metadata — use devops/flow-deployment-activation-ordering. NOT for moving a flow from sandbox to production — use flow/flow-deployment-and-packaging.

Open the skill folder on GitHub

Flow Versioning Strategy

The Model

Each flow has many versions; only one is active. Paused interviews (long-running) pin to the version that started them. Versioning is not just housekeeping — it is correctness.

Activation Policy

Paused Interview Compatibility

A paused interview resumes on the version it started on. Breaking changes that cannot survive a resume:

If any of these is needed, route NEW traffic to a new flow and let the old one drain.

Cleanup Cadence

Breaking-Change Detection

The test is mechanical: if anything outside the flow has to change at the same moment the flow changes, it is a new flow, not a new version. The contract surface binds by name at run time — Apex Flow.Interview.createInterview, lightning-flow with inputVariables, another flow's <subflows> input assignments, quick actions, Experience Cloud pages — and nothing compiles over it.

Before activating, diff against the current active version:

Querying the Right Object

Four objects answer four different questions, and picking the wrong one produces "sObject type 'Flow' is not supported."

QuestionObjectAPI
Versions, their status, their definitionFlowTooling API
Which version is active per definitionFlowDefinitionViewStandard
Version metadata, read-onlyFlowVersionViewStandard (46.0+)
Live and paused interviewsFlowInterviewStandard

Flow version Status has five values: Active, Draft, Obsolete, InvalidDraft, and UnderReview. None of them means "safe to delete," and the API values do not match the UI labels — Draft and Obsolete both display as Inactive, InvalidDraft displays as Draft, UnderReview as Under Review. Filter cleanup queries on Status != 'Active' rather than enumerating the inactive values, so a value you did not think of cannot fall out of the inventory.

Change Log

Keep a FLOWS_CHANGELOG.md or equivalent block in the flow's PR body:

Flow: CustomerOnboarding
From v12 → v13
- Added input variable `partnerAccountId` (optional, default null).
- Non-breaking. Paused interviews on v12 continue.
- Activate: after UAT sign-off.
- Retire v11: 2026-05-15.

Metrics To Watch

  1. Inventory the callers first, not last. Search the repository for the

    flow's API name and for every input/output variable name it exposes. This is the input to the decision, not a check afterwards.

  2. Apply the breaking-change test. Anything outside the flow that must change

    at the same moment makes it a new flow. Otherwise, a new version.

  3. Capture the currently active version number, per environment, before

    activating. It is the entire rollback plan.

  4. Activate, and write the changelog entry — breaking or not with the reason,

    the callers checked, the live paused-interview count, and the rollback version number.

  5. Roll back by activating the prior version, never by redeploying its

    source. Redeploying creates a new version whose content matches the old one; it does not restore the old one. Keep the bad version as evidence.

  6. Prune on the interview-reference condition, retaining at least three

    inactive versions.

  7. Treat every subflow activation as a multi-caller production change. Search

    the metadata for <flowName> references before activating; resolution is late, so the parent runs whatever version of the child is active at run time.

Official Sources Used

The full annotated list is in references/well-architected.md.

Dependencies

Package files