FlowDefinition Metadata Type in SFDX

Architectural Overview#

FlowDefinition was historically the primary metadata mechanism used to govern the active version pointer and high-level description of a Salesforce Flow. Before Salesforce introduced versionless flow deployments in modern source format, every Flow definition generated an accompanying FlowDefinition metadata file to specify which numeric version (activeVersionNumber) was actively executing in the organization.

In modern Salesforce DX architectures running on API version 68.0, the platform natively tracks active status directly inside the Flow metadata file via the <status>Active</status> element. However, architects maintaining legacy managed packages, classic metadata deployments, or upgrading older codebases still encounter FlowDefinition files. Understanding how the Metadata API reconciles FlowDefinition with underlying versioned Flow records remains critical for automated CI/CD migrations.

Directory and File Conventions#

When working with legacy metadata format or specific package scenarios, FlowDefinition resides in the flowDefinitions/ folder.

Key Metadata Fields#

The XML schema for FlowDefinition exposes the following version pointer fields:

Declarative XML and Package Manifest Examples#

Below is a declarative FlowDefinition file pointing to version 2 of an order processing flow:

<?xml version="1.0" encoding="UTF-8"?>
<FlowDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
    <activeVersionNumber>2</activeVersionNumber>
    <description>Enterprise order validation and warehouse dispatch flow orchestration.</description>
    <masterLabel>Order Fulfillment Process</masterLabel>
</FlowDefinition>

Package Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Order_Fulfillment_Process</members>
        <name>FlowDefinition</name>
    </types>
    <version>68.0</version>
</Package>

CLI Retrieval and Deployment Commands#

You can retrieve and deploy FlowDefinition components using the Salesforce CLI:

# Retrieve a specific FlowDefinition from the target org
sf project retrieve start --metadata FlowDefinition:Order_Fulfillment_Process

# Deploy the FlowDefinition to toggle the active version
sf project deploy start --metadata FlowDefinition:Order_Fulfillment_Process

Architect Best Practices and Gotchas#

• Modern Architecture Recommendation: Avoid introducing new FlowDefinition files in modern SFDX projects. Manage activation status directly on the Flow metadata record and enable enableFlowDeployAsActive in FlowSettings.
• Target Org Version Desynchronization: If your FlowDefinition declares <activeVersionNumber>4</activeVersionNumber>, but the deployment target org only has versions 1 and 2 deployed, the entire deployment will fail.
• Source Tracking Conflicts: Having both FlowDefinition and <status>Active</status> in the Flow file can cause source conflict warnings during sf project deploy start. Remove flowDefinitions/ when upgrading legacy projects.

Frequently asked questions

Why did modern Salesforce releases deprecate FlowDefinition in source format?

Starting in API 44.0, Salesforce allowed activating flows directly on the Flow metadata status tag, eliminating the need to deploy a separate FlowDefinition file.

What error occurs when deploying an invalid activeVersionNumber in FlowDefinition?

Salesforce raises a deployment error if the activeVersionNumber refers to a version number that does not exist or has been deleted in the target environment.

How can teams activate flows during CI/CD without deploying FlowDefinition?

Teams can set the status tag to Active in the Flow XML file and enable the FlowSettings flag enableFlowDeployAsActive in scratch and sandbox environments.