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
- New feature → create a new version, activate after test.
- Non-breaking fix → new version, same name, activate, retire the
previous after paused-interview drain window.
- Breaking change → NEW flow, not a new version. Paused interviews
cannot migrate between versions that break the contract.
Paused Interview Compatibility
A paused interview resumes on the version it started on. Breaking
changes that cannot survive a resume:
- Added required input variable.
- Removed or renamed variable still referenced downstream.
- Changed element output shape (collection → single, etc.).
- Changed decision paths in a way that strands the paused node.
If any of these is needed, route NEW traffic to a new flow and let the
old one drain.
Cleanup Cadence
- Retain the last 3 inactive versions (rollback depth).
- Delete a version only when zero interviews reference it. Age is a cheap
pre-filter for that condition, never a substitute — a paused interview resumes
on the version it started on, and since Spring '24 the org has no cap on how
many paused interviews accumulate.
- Size the retention window per flow from the observed interview lifetime. A
screen flow with an overnight pause and a scheduled flow with a 90-day wait
need different windows; one org-wide number is wrong for both.
- Cap total versions per flow at 10 by policy, so pruning happens on a calm
cadence rather than in response to a failed save.
The platform ceiling is 50 versions per flow — stated in the Visual
Workflow Implementation Guide's limits table, and the number Salesforce returns
in the save error ("Maximum number of Versions per flow is 50").
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:
- Added required variables? → breaking.
- Renamed or removed variables still referenced by callers? → breaking.
- Changed element outputs on a path before a Pause? → breaking.
- Removed an element a paused interview could currently occupy? → breaking.
- Added a Pause at the top of a flow that previously completed inline? →
behaviour-changing; test callers.
- API version moved? → behaviour-changing. Flow behaviour is versioned, and
Flow Builder can bump the version on save. Crossing API 52.0 changes the
run-mode default; crossing 57.0 removes the executed-elements cap.
Querying the Right Object
Four objects answer four different questions, and picking the wrong one produces
"sObject type 'Flow' is not supported."
| Question |
Object |
API |
| Versions, their status, their definition |
Flow |
Tooling API |
| Which version is active per definition |
FlowDefinitionView |
Standard |
| Version metadata, read-only |
FlowVersionView |
Standard (46.0+) |
| Live and paused interviews |
FlowInterview |
Standard |
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
- Count of paused interviews per version.
- Age of oldest paused interview.
- Activations per week (high churn = unstable flow).
- Version count per flow.
Recommended Workflow
- 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.
- 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.
- Capture the currently active version number, per environment, before
activating. It is the entire rollback plan.
- 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.
- 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.
- Prune on the interview-reference condition, retaining at least three
inactive versions.
- 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.
1---2name: flow-versioning-strategy3description: "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."4category: flow5salesforce-version: "Spring '25+"6well-architected-pillars:7 - Reliability8 - Operational Excellence9triggers:10 - "flow version strategy"11 - "paused interview compatibility"12 - "clean up old flow versions"13 - "flow breaking change detection"14 - "activate flow version plan"15tags:16 - flow17 - versioning18 - governance19 - lifecycle20inputs:21 - Flow inventory with active/inactive version counts22 - Rate of paused interviews per flow23 - Change history of flow versions24outputs:25 - Flow versioning convention26 - Cleanup cadence rule27 - Breaking-change detection checklist28dependencies:29 - devops/flow-deployment-activation-ordering30version: 1.0.131author: Pranav Nagrecha32updated: 2026-08-1433metadata:34 source: https://skillmd.com/skills/pranavnagrecha/flow-versioning-strategy35---3637# Flow Versioning Strategy3839## The Model4041Each flow has many versions; only one is active. Paused interviews42(long-running) pin to the version that started them. Versioning is not43just housekeeping — it is correctness.4445## Activation Policy4647- **New feature** → create a new version, activate after test.48- **Non-breaking fix** → new version, same name, activate, retire the49 previous after paused-interview drain window.50- **Breaking change** → NEW flow, not a new version. Paused interviews51 cannot migrate between versions that break the contract.5253## Paused Interview Compatibility5455A paused interview resumes on the version it started on. Breaking56changes that cannot survive a resume:5758- Added required input variable.59- Removed or renamed variable still referenced downstream.60- Changed element output shape (collection → single, etc.).61- Changed decision paths in a way that strands the paused node.6263If any of these is needed, route NEW traffic to a new flow and let the64old one drain.6566## Cleanup Cadence6768- Retain the last 3 inactive versions (rollback depth).69- Delete a version only when **zero interviews reference it**. Age is a cheap70 pre-filter for that condition, never a substitute — a paused interview resumes71 on the version it started on, and since Spring '24 the org has no cap on how72 many paused interviews accumulate.73- Size the retention window per flow from the observed interview lifetime. A74 screen flow with an overnight pause and a scheduled flow with a 90-day wait75 need different windows; one org-wide number is wrong for both.76- Cap total versions per flow at 10 by policy, so pruning happens on a calm77 cadence rather than in response to a failed save.78 The platform ceiling is **50 versions per flow** — stated in the Visual79 Workflow Implementation Guide's limits table, and the number Salesforce returns80 in the save error ("Maximum number of Versions per flow is 50").81 <!-- PARTIALLY VERIFIED: 50 is corroborated by the Implementation Guide's table82 and by the runtime error text. What was not confirmed during authoring is83 whether the current General Flow Limits page restates it, because that page is84 a Lightning SPA that fetchers cannot read. Two other figures on the same legacy85 page (2,000 executed elements, 500 active flows) are known stale, so cite 5086 from the error message rather than from that page. -->8788## Breaking-Change Detection8990The test is mechanical: **if anything outside the flow has to change at the same91moment the flow changes, it is a new flow, not a new version.** The contract92surface binds by *name* at run time — Apex `Flow.Interview.createInterview`,93`lightning-flow` with `inputVariables`, another flow's `<subflows>` input94assignments, quick actions, Experience Cloud pages — and nothing compiles over95it.9697Before activating, diff against the current active version:9899- Added required variables? → breaking.100- Renamed or removed variables still referenced by callers? → breaking.101- Changed element outputs on a path before a Pause? → breaking.102- Removed an element a paused interview could currently occupy? → breaking.103- Added a Pause at the top of a flow that previously completed inline? →104 behaviour-changing; test callers.105- API version moved? → behaviour-changing. Flow behaviour is versioned, and106 Flow Builder can bump the version on save. Crossing API 52.0 changes the107 run-mode default; crossing 57.0 removes the executed-elements cap.108109## Querying the Right Object110111Four objects answer four different questions, and picking the wrong one produces112"sObject type 'Flow' is not supported."113114| Question | Object | API |115|---|---|---|116| Versions, their status, their definition | `Flow` | **Tooling API** |117| Which version is active per definition | `FlowDefinitionView` | Standard |118| Version metadata, read-only | `FlowVersionView` | Standard (46.0+) |119| Live and paused interviews | `FlowInterview` | Standard |120121Flow version `Status` has five values: `Active`, `Draft`, `Obsolete`,122`InvalidDraft`, and `UnderReview`. None of them means "safe to delete," and the123API values do not match the UI labels — `Draft` and `Obsolete` both display as124*Inactive*, `InvalidDraft` displays as *Draft*, `UnderReview` as *Under Review*.125Filter cleanup queries on `Status != 'Active'` rather than enumerating the126inactive values, so a value you did not think of cannot fall out of the inventory.127128## Change Log129130Keep a `FLOWS_CHANGELOG.md` or equivalent block in the flow's PR body:131132```text133Flow: CustomerOnboarding134From v12 → v13135- Added input variable `partnerAccountId` (optional, default null).136- Non-breaking. Paused interviews on v12 continue.137- Activate: after UAT sign-off.138- Retire v11: 2026-05-15.139```140141## Metrics To Watch142143- Count of paused interviews per version.144- Age of oldest paused interview.145- Activations per week (high churn = unstable flow).146- Version count per flow.147148## Recommended Workflow1491501. **Inventory the callers first**, not last. Search the repository for the151 flow's API name and for every input/output variable name it exposes. This is152 the input to the decision, not a check afterwards.1532. **Apply the breaking-change test.** Anything outside the flow that must change154 at the same moment makes it a new flow. Otherwise, a new version.1553. **Capture the currently active version number, per environment,** before156 activating. It is the entire rollback plan.1574. **Activate, and write the changelog entry** — breaking or not with the reason,158 the callers checked, the live paused-interview count, and the rollback version159 number.1605. **Roll back by activating the prior version**, never by redeploying its161 source. Redeploying creates a new version whose content matches the old one;162 it does not restore the old one. Keep the bad version as evidence.1636. **Prune on the interview-reference condition,** retaining at least three164 inactive versions.1657. **Treat every subflow activation as a multi-caller production change.** Search166 the metadata for `<flowName>` references before activating; resolution is late,167 so the parent runs whatever version of the child is active at run time.168169## Official Sources Used170171- FlowDefinition (Metadata API) — https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_flowdefinition.htm172- Flow (Metadata API) — https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_visual_workflow.htm173- Flow (Tooling API) — https://developer.salesforce.com/docs/atlas.en-us.api_tooling.meta/api_tooling/tooling_api_objects_flow.htm174- FlowVersionView (Object Reference) — https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_flowversionview.htm175- Have Unlimited Paused and Waiting Flows (Spring '24) — https://help.salesforce.com/s/articleView?id=release-notes.rn_automate_flow_mgmt_remove_paused_interview_limit.htm&release=248&type=5176- General Flow Limits — https://help.salesforce.com/s/articleView?id=platform.flow_considerations_limit.htm&type=5177178The full annotated list is in `references/well-architected.md`.