ProcessFlowMigration Metadata in SFDX

Architectural Overview#

With Salesforce’s retirement of legacy automation tools (Workflow Rules and Process Builder), enterprise organizations must modernize their declarative automation architectures. Record-Triggered Flows provide significantly higher execution speed, lower CPU utilization, and fine-grained trigger ordering via Flow Trigger Explorer.

The ProcessFlowMigration metadata type manages and records the conversion parameters when utilizing Salesforce’s automated migration tooling. It maps legacy source definitions to target Flow components, logging translation decisions, criteria evaluations, and migration statuses.

For technical architects overseeing multi-year technical debt reduction programs, version-controlling migration artifacts provides a clear audit trail of legacy automation transitions across sandbox environments.

Directory and File Conventions#

In SFDX source format, ProcessFlowMigration metadata files reside in the processFlowMigrations/ directory:

Key Metadata Fields#

The XML schema of ProcessFlowMigration captures the mapping and lifecycle state:

Declarative XML and Package Manifest Examples#

Below is a declarative XML definition tracking the migration of an Opportunity qualification rule:

<?xml version="1.0" encoding="UTF-8"?>
<ProcessFlowMigration xmlns="http://soap.sforce.com/2006/04/metadata">
    <migrationNotes>Converted immediate field updates and Chatter notification; scheduled action relocated to asynchronous path.</migrationNotes>
    <migrationStatus>Migrated</migrationStatus>
    <sourceProcessName>Opportunity_Qualification_Process</sourceProcessName>
    <targetFlowName>Opportunity_After_Save_Qualification</targetFlowName>
</ProcessFlowMigration>

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Manage ProcessFlowMigration metadata using the Salesforce CLI:

# Retrieve all migration records
sf project retrieve start --metadata ProcessFlowMigration

# Deploy migration record alongside the generated flow
sf project deploy start --metadata "ProcessFlowMigration:Opportunity_Qual_Migration" --metadata "Flow:Opportunity_After_Save_Qualification"

# Validate deployment into sandbox
sf project deploy validate --metadata ProcessFlowMigration

Architect Best Practices and Gotchas#

• Prevent Duplicate Execution: Always deactivate the legacy Workflow Rule or Process Builder in the same deployment package that activates the new Flow. Running both simultaneously will trigger duplicate field updates, notifications, and validation errors.
• Trigger Order Consolidation: Do not leave migrated flows scattered haphazardly. Use triggerOrder attributes in Flow or adopt a one-flow-per-object design pattern to orchestrate subflows cleanly.
• Bulk Testing and Apex Regression: Migrated flows execute earlier or later in the Save Order of Execution compared to Workflow Rules. Run full regression test suites to verify that ApexClass triggers and validation rules behave as expected.

Frequently asked questions

What is the primary function of ProcessFlowMigration?

It tracks and manages the automated conversion of legacy Workflow Rules and Process Builder processes into modern record-triggered Flows.

Where are ProcessFlowMigration metadata files stored in SFDX?

Files are stored in force-app/main/default/processFlowMigrations/ with the suffix .processFlowMigration-meta.xml.

Does migrating a process automatically deactivate the source workflow rule?

No, architects must explicitly deactivate legacy rules and activate the migrated flow to prevent duplicate trigger execution.

Why is migrating to Flow recommended by Salesforce Architects?

Record-triggered Flows offer superior runtime performance, explicit trigger ordering, advanced error handling, and unified automation governance.