Flow Deployment And Packaging

Flow Deployment And Packaging

Activate when a Flow needs to move between orgs (sandbox → UAT → prod, scratch org → packaging org, ISV release) and the question is which deployment shape, what must travel with it, and how to roll it back without breaking the active version chain.

Before Starting

Gather this context before working on anything in this domain:

• Target org API version. The sourceApiVersion in sfdx-project.json and the <apiVersion> inside the .flow-meta.xml must be ≤ the target org's release. A flow saved at API 62.0 will not deploy to a Spring '25 org running API 63.0+ if the org is on a lower release.
• Deploying user's profile and permission sets. The user must hold "Modify Metadata Through Metadata API Functions" or "Customize Application", AND "Manage Flow" for activating. If the user lacks Manage Flow, an <status>Active</status> deploy fails with INSUFFICIENT_ACCESS.
• Dependent metadata already in the target org. A flow referencing Account.Custom_Field__c, an invocable Apex class MyInvocable, a subflow Sub_Validate_Lead, or a picklist value Stage = "Closed Lost" must have those dependencies present before or alongside the flow deploy. Missing dependencies either fail the deploy (subflow, Apex, custom field) or — silently — pass deploy and fail at runtime (picklist values, formula references, RecordType DeveloperName lookups).
• Existing active version in target. Run sf data query --query "SELECT Id, VersionNumber, Status FROM Flow WHERE DeveloperName = '<FlowName>'" --use-tooling-api to see what's already there. Knowing the current active version is a precondition for a safe rollback plan.
• Most common wrong assumption: "Deploy = activate." Deploying a flow with <status>Draft</status> puts it in the org but does NOT make it run. Practitioners forget this and wonder why their automation didn't fire after a successful deploy.

Core Concepts

Concept 1 — Flow source XML and the <status> field

In source format, a flow lives at force-app/main/default/flows/<FlowName>.flow-meta.xml. The metadata API name keeps the .flow extension; SFDX source format adds -meta.xml. A single file represents one definition; the org tracks versions of that definition separately in Flow and FlowDefinition Tooling API objects.

The <status> element is the activation control:

The <processType> element is mandatory and not inferred. Common values: AutoLaunchedFlow, Flow (screen), RecordBeforeSave, RecordAfterSave, InvocableProcess (legacy Process Builder), CustomEvent (platform event triggered). Missing <processType> causes a deploy error: Required field is missing: processType.

Concept 2 — Versioning on deploy: every Active deploy creates a new Flow Version

Salesforce never overwrites a Flow version in place. Every <status>Active</status> deploy creates a brand-new version row, increments VersionNumber, and deactivates the prior active version (which stays in the org as Status = Obsolete). Over a year of weekly deploys, a single flow can accumulate 50+ obsolete versions. There is no automatic cleanup — you must delete obsolete versions explicitly via the UI or a Tooling API call.

Implications:

• Storage / clutter, not breakage. Old versions don't run; they just sit in the FlowDefinition history. But the Flow Builder version dropdown becomes unwieldy.
• Rollback is "activate prior version", not "delete current". You cannot un-deploy a version. You activate an older one to supersede it (which itself creates… another version row, or just flips the active pointer if you do it via UI / Tooling API).
• Re-deploying the same XML twice creates two identical versions. If your CI runs the same SFDX deploy twice (e.g. a re-run after a flake), you get two identical version rows.

Concept 3 — Deploy vs Activate (they are NOT the same step)

Two distinct operations:

1. Deploy — Move the source XML into the target org. After this, the flow definition exists, but its activation state depends on the <status> field in the XML you deployed.
2. Activate — Flip the active-version pointer in FlowDefinition to point at a specific Flow version. Done automatically by <status>Active</status> in source XML, OR manually via the UI ("Activate" button on the version row), OR programmatically via Tooling API PATCH /tooling/sobjects/FlowDefinition/<Id> with ActiveVersionNumber.

The "deploy with Draft, activate later via UI" pattern is common when ops wants a controlled cutover window separate from the deploy window. Useful for high-stakes changes where the deploy can run during business hours but the activation must happen during a maintenance window.

Concept 4 — --test-level and Flow deploys

sf project deploy start --test-level flag controls Apex test execution. It does NOT run Flow Tests (Flow Tests are a separate Flow Builder–internal framework). Behavior:

Flow has no coverage requirement of its own. The 75% rule applies only to Apex.

Common Patterns

Pattern 1 — Validate-Then-Quick-Deploy (the canonical CI/CD shape)

When to use: every production deploy. Splits the slow part (compile + tests) from the fast part (apply changes), so the cutover window is minutes, not hours.

How it works:

# Step 1 — Validate (runs all tests, takes 30–90 min in a real org).
sf project deploy validate \
  --source-dir force-app \
  --target-org prod \
  --test-level RunLocalTests \
  --wait 90

# Capture the validation Id from the output, e.g. 0Af5g00000xxxxxxx.

# Step 2 — Quick deploy (within 10 days of the validation; reuses test results).
sf project deploy quick \
  --job-id 0Af5g00000xxxxxxx \
  --target-org prod \
  --wait 30

Why not the alternative: running sf project deploy start --test-level RunLocalTests directly during the cutover means tests run during the maintenance window. A 60-minute test run plus a failure means another 60 minutes after the fix. Validate-then-quick-deploy keeps the actual production change to under 5 minutes for most flow-only deploys.

Pattern 2 — Bundle Flow + Subflow + Apex Together

When to use: the flow being deployed references a subflow, an invocable Apex class, or a custom field that is not yet in the target org.

How it works: include all dependencies in a single SFDX deploy package or single Change Set:

sf project deploy start \
  --source-dir force-app/main/default/flows/Lead_Routing.flow-meta.xml \
  --source-dir force-app/main/default/flows/Sub_Score_Lead.flow-meta.xml \
  --source-dir force-app/main/default/classes/LeadRouter.cls \
  --source-dir force-app/main/default/classes/LeadRouter.cls-meta.xml \
  --source-dir force-app/main/default/objects/Lead/fields/Routing_Score__c.field-meta.xml \
  --target-org prod

Or use a package.xml manifest. Salesforce computes the dependency graph and deploys in the correct order — subflows before parents, fields before flows that reference them, Apex classes before flows that call them.

Why not the alternative: deploying the parent flow alone gives Subflow Sub_Score_Lead does not exist. Deploying the subflow first as a separate transaction works but doubles the deploy windows and makes rollback harder (which deploy do you reverse?).

Pattern 3 — Deactivate-Activate Sequence for Cutover

When to use: swapping a complex flow during a maintenance window where you need to verify the new version with smoke tests before it starts handling live traffic.

How it works:

1. Deploy new flow with <status>Draft</status>. The new version exists in the org but isn't active.
2. (Optional) Deploy the prior active flow with <status>Obsolete</status>. This deactivates the current active version. The flow stops running — useful if you want a "frozen" window during cutover.
3. In the maintenance window, navigate to Setup → Flows → click the new draft version → Activate.
4. Smoke-test by triggering a known input.
5. If smoke fails, click Activate on the prior version to revert.

Why not the alternative: deploying directly with <status>Active</status> means the new version starts handling live traffic the moment the deploy finishes — no smoke-test window, no controlled flip.

Decision Guidance

Rule of thumb: default to SFDX source. Only graduate to Unlocked Package when the same flow / subflow library needs to ship to multiple orgs. Only graduate to Managed when you're an ISV.

Recommended Workflow

1. Inventory the flow + its dependencies. Run sf project retrieve start --metadata Flow:<FlowName> to pull current state. Open the .flow-meta.xml and grep for: <flowName> (subflow refs), <actionName> with <actionType>apex</actionType> (Apex refs), <object> and <field> (custom field refs), <value> inside picklist filters (picklist value refs).
2. Verify dependencies in the target org. For each dependency, run a tooling-API query or use sf project retrieve start --metadata <Type>:<Name> --target-org prod. If anything is missing, add it to the deploy bundle.
3. Validate the deploy. sf project deploy validate --source-dir <bundle> --target-org prod --test-level RunLocalTests --wait 90. Capture the validation Id. Treat any test failure as a hard stop.
4. Plan activation strategy. If high-risk, deploy with <status>Draft</status> and activate manually in the maintenance window. If low-risk, deploy with <status>Active</status> directly via quick-deploy.
5. Quick-deploy in the cutover window. sf project deploy quick --job-id <validationId> --target-org prod --wait 30. Confirm the new active version number with a Tooling API query.
6. Verify FlowAccessPermission and RunFlow system permission. Profiles / permission sets controlling who can run the flow must be deployed separately if changed. Spot-check by impersonating a typical end-user.
7. Document rollback steps. Record the prior active VersionNumber in the deployment ticket so an oncall engineer can re-activate it without spelunking through Flow Builder history.

Review Checklist

• All dependent metadata (subflows, invocable Apex, custom fields, RecordTypes, picklist values) is included in the deploy bundle OR confirmed already present in target.
• <processType> is set in the .flow-meta.xml. (Missing → deploy fails.)
• <status> is set deliberately — Active for direct cutover, Draft for staged activation.
• Validation ran with --test-level RunLocalTests (or RunAllTestsInOrg if managed-package interaction expected) and passed within the 10-day quick-deploy window.
• Rollback plan documents the prior VersionNumber and the activation command (UI click or Tooling API PATCH).
• FlowAccessPermission and RunFlow system permission delivered to required profiles / permission sets.
• Obsolete-version cleanup considered if the org has > 30 historical versions of this flow.
• Post-deploy smoke test plan (record a known-good input, verify flow ran via Flow Interview log).

Salesforce-Specific Gotchas

1. <status>Active</status> deploy auto-deactivates the prior active version — there is no warning, no confirmation step, no "are you sure". The moment the deploy succeeds, live traffic flips to the new version. If you wanted a staged cutover, you needed to deploy as Draft first.
2. FlowAccessPermission does NOT auto-deploy with the flow. A flow that requires explicit access via FlowAccessPermission on a profile or permission set needs that permission deployed separately. Symptom: end-users hit "Flow execution failed: Insufficient privileges" after an apparently-successful deploy.
3. Change Sets carry only the active version of a flow. If your sandbox has versions 1–7 with version 5 active, the Change Set ships only version 5. Versions 1–4, 6, and 7 stay behind. No way to migrate a non-active version via Change Set — must use SFDX or recreate manually.
4. Obsolete versions accumulate forever. Every Active deploy adds a row. After 50–100 deploys, the FlowDefinition version dropdown becomes hard to navigate. There's no built-in archival; you must delete obsolete versions via UI (Setup → Flows → version row → Delete) or via Tooling API DML on the Flow sObject.
5. Flow referencing a not-yet-deployed custom field deploys successfully but fails at runtime. Picklist values especially: if your flow's Decision element checks Stage = "Closed Lost - Competitor" but the target org's picklist has only Stage = "Closed Lost", the deploy passes (the flow XML is syntactically valid) and the flow runs — but the Decision branch never matches, silently routing every record to the default path.
6. "Flow Version Conflict" on deploy. Happens when the active version in the target org has been edited via Flow Builder after the source you're deploying was extracted. Salesforce refuses to deploy because applying your version would silently overwrite an admin's in-org changes. Resolution: re-retrieve the target's current active version, manually merge into source, re-deploy.
7. --ignore-errors on a flow deploy is dangerous. It allows partial deploys where some flows succeed and others fail. You can end up with a parent flow active in the org while its dependent subflow failed to deploy — a runtime error waiting to happen. Use only for non-flow components and never for prod.
8. Re-running the same deploy creates redundant version rows. If your CI flakes and you re-trigger, you'll get two identical Flow versions. Not breaking, but pollutes the version history. Prefer re-running sf project deploy quick against the original validation Id rather than re-running validate.

Output Artifacts

Related Skills

• devops/salesforce-dx-project-structure — how the force-app/main/default/flows/ directory and sfdx-project.json integrate with broader source control. Use first if the org is migrating off Change Sets.
• devops/source-tracking-and-conflict-resolution — handling source-tracking conflicts that surface as Flow Version Conflict errors during scratch-org and sandbox deploys.
• devops/unlocked-package-development — when a Flow + subflow library needs to ship to multiple internal orgs, graduate from SFDX source deploy to 2GP.
• flow/flow-versioning-strategy — naming conventions, version hygiene, and obsolete-version cleanup policy.
• flow/flow-rollback-patterns — detailed rollback playbooks beyond the basic "activate prior version" mechanic.
• flow/flow-deployment-activation-ordering — multi-flow deploys where activation order matters (e.g., a parent flow that depends on a newly-activated subflow).
• devops/change-set-deployment — when you must use Change Sets despite their limitations.

Official Sources Used

• Salesforce DX Developer Guide — Deploy and Retrieve: https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_deploy_and_retrieve.htm
• Salesforce DX Developer Guide — Second-Generation Managed and Unlocked Packages: https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_dev2gp.htm
• Metadata API Developer Guide — Flow type: https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_flow.htm
• Metadata API Developer Guide — FlowDefinition type: https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_flowdefinition.htm
• Salesforce Help — Activate or Deactivate a Flow Version: https://help.salesforce.com/s/articleView?id=sf.flow_distribute_activate.htm
• Salesforce Help — Deploy Flows in Change Sets: https://help.salesforce.com/s/articleView?id=sf.flow_distribute_change_set.htm
• Salesforce CLI Command Reference — sf project deploy validate / quick: https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_project_commands_unified.htm
• Salesforce Architects — Application Lifecycle Management: https://architect.salesforce.com/decision-guides/alm/