Flow Deployment & Activation Ordering
Purpose
Flow deployments are deceptively tricky. Unlike Apex, Flow preserves
previous versions in the org; the "active" version is a pointer. A deploy
can inadvertently deactivate the currently-running flow, leave two flows
active in sequence, or break paused interviews that refer to the old
version. The team hits production incidents: "the approval flow stopped
triggering," "paused interviews threw after deploy," "rollback just
deactivated everything." This skill codifies the sequence, guards, and
verification to make Flow deploys boring.
Recommended Workflow
- Inventory changes. Which flows changed? Which have paused
interviews or scheduled runs currently in progress?
- Check active versions in target org.
sf data query against
FlowDefinition and Flow to confirm what is active today.
- Pick activation mode. Deploy as active (default) vs deploy as
inactive then activate via
FlowDefinition update. Inactive-first is
safer for risky flows.
- Plan the order. If Flow A calls Subflow B, deploy B first (active
before A switches).
- Communicate pause windows. If paused interviews exist on the
changing flow, delay deploy or accept that paused interviews may fail
on resume.
- Deploy, verify, and plan rollback. Use
--test-level RunSpecifiedTests --tests <ClassName> [...] when Apex callers exist (Flow itself has no test framework parity). --tests is what names the classes to run — RunSpecifiedTests on its own specifies nothing — and this level changes the coverage rule: "Each class and trigger in the deployment package must be covered by the executed tests for a minimum of 75% code coverage." Re-query active versions post-deploy; run a smoke Flow interview; check for spikes in Flow error emails. Keep the prior active version id captured before deploy — rollback = flip the pointer on FlowDefinition, not redeploy.
The Asymmetry Everything Turns On
Deploying a flow always creates a new version. It never restores an old one.
Activation, by contrast, is a pointer into versions that already exist in the
org. Deploy and activate are different operations with different rollback
properties, and conflating them causes most incidents in this domain.
Active vs Draft Deploy
- Deploy a pending version with
<status>Draft</status>, verify it, then
activate as a separate step. Obsolete is what the platform assigns to a
superseded version — it is never the right thing to choose for a new one. The
status field has five valid values: Active, Draft, Obsolete,
InvalidDraft, and UnderReview. They do not map one-to-one onto the UI
labels — Draft and Obsolete both display as Inactive, InvalidDraft
displays as Draft, and UnderReview displays as Under Review — so never
infer the API value from what Setup shows you.
- Prefer
<status>Active</status> on the Flow for routine deploys.
- Keep
FlowDefinition out of routine packages. This recommendation is
routinely misremembered as "upgrade flows to API version 44.0". What Salesforce
actually says is: "In API version 44.0, we recommend upgrading your flows to
flow metadata file names without version numbers and discontinue using the
FlowDefinition object to activate or deactivate a flow." That is a
recommendation made in 44.0, about file naming and about dropping
FlowDefinition — not an instruction to move flows to API version 44.0. The
precedence rule is the trap: "the active version numbers in the flow definitions
override the status fields in the flows." A stale FlowDefinition silently wins
over every status in the package.
- One production-only constraint: the Deploy processes and flows as active
preference (Setup → Process Automation Settings) and its flow test coverage
percentage do not exist in developer or sandbox orgs. A green sandbox deploy is
not evidence the production deploy will pass. The coverage requirement applies
to processes and autolaunched flows and does not apply to flows that have
screens.
Paused Interview Risk
Paused interviews resume on the version they started on. The deploy is safe — the
old version stays in the org. The cleanup is what breaks them, usually weeks
later in an unrelated change, which is why nobody connects the failure back.
- Snapshot
FlowInterview before deploying. InterviewLabel embeds the flow's
API name and version number, which is how you check "does anything still
reference version 7?"
- Gate deletion on zero interview references, never on age.
- Since Spring '24 there is no platform cap on how many paused and waiting
interviews an org accumulates, so this population grows quietly and will not
self-limit.
- Screen flows with Pause elements are the most common victims.
Subflow / Activation-Order Rules
Subflow resolution is late: the parent runs whatever version of the child is
active at interview time, and the latest version if the child has none active.
- Deploy both as
Draft, verify the child, activate the child, then activate
the caller. Between those two activations the old caller runs against the
new child, which is the compatible direction.
- Ordering inside a single deploy changes nothing — the deploy is atomic. It is
the activation order that matters.
- Activation is not atomic across two flows. For a breaking child change no
ordering helps; that needs a new child flow with a caller repoint, which is
flow/flow-versioning-strategy's call.
- Deactivating a child does not stop callers. It drops them onto the latest
version, possibly an untested draft.
Rollback Pattern
- Capture the active version number per flow per environment before the
deploy. That capture is the entire rollback plan, and the repository does not
contain it — activation is org state.
- Roll back by activating the version that already exists: one click on the
flow's detail page, or a standalone
FlowDefinition deployment with
activeVersionNumber set to the version you want live. This is the one case
where FlowDefinition earns its place, because pointing at an existing version
number is the thing status cannot express. To take a flow off rather than
move the pointer, deactivate on the flow's detail page or deploy the version
with <status>Draft</status> — both are documented behaviours.
- Do not delete the bad version. It is the evidence and it preserves the
forward-fix path.
- Rollback stops future damage and repairs nothing past. Records already written
stay wrong, published platform events are gone and their subscribers already
acted, and enqueued scheduled paths are still queued. Write the data-remediation
plan alongside the deploy plan.
CI/CD
- Pre-deploy: capture
FlowDefinitionView (standard API — ActiveVersionId,
LatestVersionId, IsActive) plus a Tooling API query against Flow for
version numbers, plus a FlowInterview snapshot. Flow is a Tooling API
object; a standard-API query returns "sObject type 'Flow' is not supported" and
a careless script degrades to checking nothing.
- Post-deploy: re-query
FlowDefinitionView and diff. An unexplained row is a
finding — a managed package upgrade can move a flow's active version without
appearing in your release notes.
- Then the checks a script cannot make: run one real interview of each changed
flow through its actual entry point, watch flow error email volume for a step
change, and check Setup → Environments → Monitoring → Time-Based Workflow
for scheduled and async entries that should have drained.
Anti-Patterns (see references/llm-anti-patterns.md)
- Rolling back by redeploying prior source — creates a new version, does not
restore the old one.
<status>Obsolete</status> used to mean "inactive".
- Bundling
FlowDefinition with Flow "for certainty" — it silently overrides.
- Inventing
FlowDefinition.ActiveVersion; the field is activeVersionNumber.
- Querying
Flow without --use-tooling-api.
- Treating deactivation as a kill switch.
- Ending the runbook at "the deploy succeeded."
- Assuming rollback undoes the data.
Related
flow/flow-versioning-strategy — new version vs new flow, and the retention
rule this skill enforces at deploy time.
flow/flow-deployment-and-packaging — change sets vs SFDX vs packages.
devops/devops-center-advanced — promoting flows through a work-item pipeline.
devops/deployment-error-diagnosis — reading a failed deploy.
flow/flow-interview-debugging — why the version in an error email is usually
not the active one.
Official Sources Used
The full annotated list is in references/well-architected.md.
1---2name: flow-deployment-activation-ordering3description: "Deploying Flow metadata across environments when activation order matters: which flow version becomes active, how paused interviews survive deploys, avoiding the 'two active versions for a moment' race, SFDX / Metadata API deploy flags, 'Deploy as Active', rollback. NOT for Change Set vs SFDX vs package choice for a flow — use flow/flow-deployment-and-packaging. NOT for whether a change needs a new version or a new flow — use flow/flow-versioning-strategy."4category: devops5salesforce-version: "Spring '25+"6well-architected-pillars:7 - Reliability8 - Operational Excellence9 - Security10triggers:11 - "flow deployment activation order"12 - "sfdx deploy flow activate"13 - "paused interview after flow deploy"14 - "flow rollback after deploy"15 - "multiple flow versions active"16tags:17 - devops18 - flow19 - deployment20 - activation21 - release22inputs:23 - Target environment + branching strategy24 - Flows changing in this release25 - Paused interviews / scheduled interviews in flight26 - Rollback SLA27outputs:28 - Pre-deploy inspection (which flow versions, paused interviews)29 - Deploy procedure (activation order, guards)30 - Rollback plan31 - Post-deploy verification32dependencies: []33version: 1.0.134author: Pranav Nagrecha35updated: 2026-08-1436metadata:37 source: https://skillmd.com/skills/pranavnagrecha/flow-deployment-activation-ordering38---3940# Flow Deployment & Activation Ordering4142## Purpose4344Flow deployments are deceptively tricky. Unlike Apex, Flow preserves45previous versions in the org; the "active" version is a pointer. A deploy46can inadvertently deactivate the currently-running flow, leave two flows47active in sequence, or break paused interviews that refer to the old48version. The team hits production incidents: "the approval flow stopped49triggering," "paused interviews threw after deploy," "rollback just50deactivated everything." This skill codifies the sequence, guards, and51verification to make Flow deploys boring.5253## Recommended Workflow54551. **Inventory changes.** Which flows changed? Which have paused56 interviews or scheduled runs currently in progress?572. **Check active versions in target org.** `sf data query` against58 `FlowDefinition` and `Flow` to confirm what is active today.593. **Pick activation mode.** Deploy as active (default) vs deploy as60 inactive then activate via `FlowDefinition` update. Inactive-first is61 safer for risky flows.624. **Plan the order.** If Flow A calls Subflow B, deploy B first (active63 before A switches).645. **Communicate pause windows.** If paused interviews exist on the65 changing flow, delay deploy or accept that paused interviews may fail66 on resume.676. **Deploy, verify, and plan rollback.** Use `--test-level RunSpecifiedTests --tests <ClassName> [...]` when Apex callers exist (Flow itself has no test framework parity). `--tests` is what names the classes to run — `RunSpecifiedTests` on its own specifies nothing — and this level changes the coverage rule: "Each class and trigger in the deployment package must be covered by the executed tests for a minimum of 75% code coverage." Re-query active versions post-deploy; run a smoke Flow interview; check for spikes in Flow error emails. Keep the prior active version id captured before deploy — rollback = flip the pointer on `FlowDefinition`, not redeploy.6869## The Asymmetry Everything Turns On7071**Deploying a flow always creates a new version. It never restores an old one.**72Activation, by contrast, is a pointer into versions that already exist in the73org. Deploy and activate are different operations with different rollback74properties, and conflating them causes most incidents in this domain.7576## Active vs Draft Deploy7778- Deploy a pending version with `<status>Draft</status>`, verify it, then79 activate as a separate step. `Obsolete` is what the platform assigns to a80 superseded version — it is never the right thing to choose for a new one. The81 `status` field has **five** valid values: `Active`, `Draft`, `Obsolete`,82 `InvalidDraft`, and `UnderReview`. They do not map one-to-one onto the UI83 labels — `Draft` and `Obsolete` both display as *Inactive*, `InvalidDraft`84 displays as *Draft*, and `UnderReview` displays as *Under Review* — so never85 infer the API value from what Setup shows you.86- Prefer `<status>Active</status>` on the `Flow` for routine deploys.87- Keep `FlowDefinition` **out** of routine packages. This recommendation is88 routinely misremembered as "upgrade flows to API version 44.0". What Salesforce89 actually says is: "In API version 44.0, we recommend upgrading your flows to90 flow metadata file names without version numbers and discontinue using the91 FlowDefinition object to activate or deactivate a flow." That is a92 recommendation made *in* 44.0, about file naming and about dropping93 `FlowDefinition` — not an instruction to move flows *to* API version 44.0. The94 precedence rule is the trap: "the active version numbers in the flow definitions95 override the status fields in the flows." A stale `FlowDefinition` silently wins96 over every `status` in the package.97- One production-only constraint: the **Deploy processes and flows as active**98 preference (Setup → Process Automation Settings) and its flow test coverage99 percentage do not exist in developer or sandbox orgs. A green sandbox deploy is100 not evidence the production deploy will pass. The coverage requirement applies101 to processes and autolaunched flows and does **not** apply to flows that have102 screens.103104## Paused Interview Risk105106Paused interviews resume on the version they started on. The deploy is safe — the107old version stays in the org. The **cleanup** is what breaks them, usually weeks108later in an unrelated change, which is why nobody connects the failure back.109110- Snapshot `FlowInterview` before deploying. `InterviewLabel` embeds the flow's111 API name and version number, which is how you check "does anything still112 reference version 7?"113- Gate deletion on zero interview references, never on age.114- Since Spring '24 there is no platform cap on how many paused and waiting115 interviews an org accumulates, so this population grows quietly and will not116 self-limit.117- Screen flows with Pause elements are the most common victims.118119## Subflow / Activation-Order Rules120121Subflow resolution is late: the parent runs whatever version of the child is122active at interview time, and the *latest* version if the child has none active.123124- Deploy both as `Draft`, verify the child, activate the **child**, then activate125 the **caller**. Between those two activations the old caller runs against the126 new child, which is the compatible direction.127- Ordering inside a single deploy changes nothing — the deploy is atomic. It is128 the *activation* order that matters.129- Activation is not atomic across two flows. For a breaking child change no130 ordering helps; that needs a new child flow with a caller repoint, which is131 `flow/flow-versioning-strategy`'s call.132- Deactivating a child does **not** stop callers. It drops them onto the latest133 version, possibly an untested draft.134135## Rollback Pattern136137- Capture the active version number per flow per environment **before** the138 deploy. That capture is the entire rollback plan, and the repository does not139 contain it — activation is org state.140- Roll back by activating the version that already exists: one click on the141 flow's detail page, or a standalone `FlowDefinition` deployment with142 `activeVersionNumber` set to the version you want live. This is the one case143 where `FlowDefinition` earns its place, because pointing at an existing version144 number is the thing `status` cannot express. To take a flow *off* rather than145 move the pointer, deactivate on the flow's detail page or deploy the version146 with `<status>Draft</status>` — both are documented behaviours.147 <!-- UNVERIFIED: `activeVersionNumber` = 0 is widely reported to deactivate a148 flow, but meta_flowdefinition.htm documents the field only as "The version149 number of the active flow" and states no behaviour for 0. Nothing in this150 runbook depends on it; if you want to use it, confirm in a sandbox first. -->151- Do **not** delete the bad version. It is the evidence and it preserves the152 forward-fix path.153- Rollback stops future damage and repairs nothing past. Records already written154 stay wrong, published platform events are gone and their subscribers already155 acted, and enqueued scheduled paths are still queued. Write the data-remediation156 plan alongside the deploy plan.157158## CI/CD159160- **Pre-deploy:** capture `FlowDefinitionView` (standard API — `ActiveVersionId`,161 `LatestVersionId`, `IsActive`) plus a Tooling API query against `Flow` for162 version *numbers*, plus a `FlowInterview` snapshot. `Flow` is a Tooling API163 object; a standard-API query returns "sObject type 'Flow' is not supported" and164 a careless script degrades to checking nothing.165- **Post-deploy:** re-query `FlowDefinitionView` and diff. An unexplained row is a166 finding — a managed package upgrade can move a flow's active version without167 appearing in your release notes.168- **Then the checks a script cannot make:** run one real interview of each changed169 flow through its actual entry point, watch flow error email volume for a step170 change, and check Setup → Environments → Monitoring → **Time-Based Workflow**171 for scheduled and async entries that should have drained.172173## Anti-Patterns (see `references/llm-anti-patterns.md`)174175- Rolling back by redeploying prior source — creates a new version, does not176 restore the old one.177- `<status>Obsolete</status>` used to mean "inactive".178- Bundling `FlowDefinition` with `Flow` "for certainty" — it silently overrides.179- Inventing `FlowDefinition.ActiveVersion`; the field is `activeVersionNumber`.180- Querying `Flow` without `--use-tooling-api`.181- Treating deactivation as a kill switch.182- Ending the runbook at "the deploy succeeded."183- Assuming rollback undoes the data.184185## Related186187- `flow/flow-versioning-strategy` — new version vs new flow, and the retention188 rule this skill enforces at deploy time.189- `flow/flow-deployment-and-packaging` — change sets vs SFDX vs packages.190- `devops/devops-center-advanced` — promoting flows through a work-item pipeline.191- `devops/deployment-error-diagnosis` — reading a failed deploy.192- `flow/flow-interview-debugging` — why the version in an error email is usually193 not the active one.194195## Official Sources Used196197- FlowDefinition (Metadata API) — https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_flowdefinition.htm198- Flow (Metadata API) — https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_visual_workflow.htm199- Flow (Tooling API) — https://developer.salesforce.com/docs/atlas.en-us.api_tooling.meta/api_tooling/tooling_api_objects_flow.htm200- FlowDefinitionView (Object Reference) — https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_flowdefinitionview.htm201- Deploy Processes and Flows as Active — https://help.salesforce.com/s/articleView?id=platform.flow_distribute_deploy_active.htm&type=5202- Salesforce CLI Command Reference, `sf project deploy` — https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_project_commands_unified.htm203204The full annotated list is in `references/well-architected.md`.