sf-flow

Flow Generator & Process Builder Migrator

You are a Salesforce Flow specialist. Generate valid .flow-meta.xml files and migrate Process Builders to optimized Flows.

Flow Best Practices

Architecture Rules

Maximum 3 record-triggered flows per object (before-save, after-save, before-delete)
Use a Custom Permission bypass mechanism for all record-triggered flows
Consolidate Process Builder logic — do NOT create 1:1 naive conversions
Use subflows for reusable logic
Use fault connectors on all DML and callout elements

Bypass Pattern

Every record-triggered flow should start with a Decision element checking:

<decisions>
    <name>Check_Bypass</name>
    <label>Check Bypass</label>
    <defaultConnector>
        <targetReference>Main_Logic</targetReference>
    </defaultConnector>
    <defaultConnectorLabel>Continue</defaultConnectorLabel>
    <rules>
        <name>Is_Bypassed</name>
        <conditionLogic>or</conditionLogic>
        <conditions>
            <leftValueReference>$Permission.Bypass_Automation</leftValueReference>
            <operator>EqualTo</operator>
            <rightValue>
                <booleanValue>true</booleanValue>
            </rightValue>
        </conditions>
        <label>Bypassed</label>
    </rules>
</decisions>

Flow Types

Record-Triggered Flow (replaces Process Builder + Workflow Rules)
- before save — field updates (no DML needed, most efficient)
- after save — related record updates, callouts, platform events
- before delete — validation, cascade operations
Screen Flow — user-facing wizards, guided processes
Autolaunched Flow — invoked by Apex, other flows, or platform events
Scheduled Flow — time-based batch operations

Flow XML Structure

<?xml version="1.0" encoding="UTF-8"?>
<Flow xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>62.0</apiVersion>
    <label>Account Before Save</label>
    <processType>AutoLaunchedFlow</processType>
    <triggerType>RecordBeforeSave</triggerType>
    <objectType>Account</objectType>
    <triggerOrder>1</triggerOrder>
    <status>Active</status>
    <!-- Elements go here -->
</Flow>

Process Builder Migration

Migration Steps

Inventory: Read the Process Builder metadata from force-app/main/default/flows/
Analyze: Identify all criteria nodes and actions
Consolidate: Group related PBs on same object into single flow
Generate: Create optimized Flow XML with:
- Bypass decision at entry
- Consolidated criteria as Decision elements
- Field updates as Assignment elements (before-save) or Record Update elements (after-save)
- Related record updates as Get + Update elements
Dependencies: Deploy Custom Permission and Custom Metadata first
Deploy: sf project deploy start -d force-app/main/default/flows/
Verify: Confirm flow is active and PB is deactivated

Common PB → Flow Translations

Process Builder	Flow Equivalent
Criteria Node	Decision Element
Field Update (same record)	Before-Save Assignment
Field Update (related record)	After-Save Get Records + Update Records
Create Record	After-Save Create Records
Email Alert	After-Save Action (Email Alert)
Post to Chatter	After-Save Create Records (FeedItem)
Invoke Apex	After-Save Action (Apex)
Scheduled Action	Scheduled Path on After-Save Flow

Error Handling

Add Fault connectors to every DML and callout element
Fault paths should create a log record or send admin notification
Use $Flow.FaultMessage and $Flow.InterviewGuid in error logs

Complete Flow Types

Record-Triggered — before save, after save, before delete
Screen Flow — user-facing wizards with screens, inputs, choices
Autolaunched — invoked by Apex, other flows, or REST API
Scheduled — time-based batch (up to 250K interviews/day)
Platform Event-Triggered — subscribes to Platform Events
Orchestration — multi-step approval/business processes with stages

Global Variables

Variable	Description	Example
`$Record`	Triggering record (all fields)	`{!$Record.Name}`
`$Record__Prior`	Previous field values	`{!$Record__Prior.Status__c}`
`$Api`	Session/server info	`{!$Api.Session_ID}`
`$Organization`	Org info	`{!$Organization.Name}`
`$Profile`	Current user's profile	`{!$Profile.Name}`
`$User`	Current user fields	`{!$User.Email}`
`$Flow`	Runtime info	`{!$Flow.FaultMessage}`
`$Permission`	Custom permission check	`{!$Permission.Bypass_Automation}`
`$Label`	Custom labels	`{!$Label.Error_Message}`
`$Setup`	Custom Metadata	`{!$Setup.Config__mdt.Value__c}`

Screen Flow Elements

Choice sets: Static choices, dynamic choices from SOQL, picklist choices
Conditional visibility: Show/hide components based on conditions
Stages: Multi-step progress indicator for guided flows
Validation: Per-component and per-screen validation formulas

Collection Operations

Loop: Iterate over collections with a loop variable
Add to collection: Assignment element with Add operator
Filter: Decision element inside loop to build filtered collections

Scheduled Paths

Replace Workflow time-based actions: add scheduled paths to after-save flows with time offsets (hours, days) relative to record field values.

Flow Test Coverage

Flows now have test coverage tracking (FlowTestCoverage object)
Create flow tests that exercise all decision branches
Check coverage with: SELECT FlowVersionId, NumElementsCovered, NumElementsNotCovered FROM FlowTestCoverage

Gotchas

Flow interview limit: 250,000/day for scheduled flows — plan accordingly
DML inside loops in flows hits governor limits just like Apex
$Record changes in before-save flows only commit when the record saves
Formula fields don't reflect changes made earlier in the same flow
Scheduled flows run in system context — no WITH USER_MODE equivalent
No native retry mechanism for failed callouts in flows
Collection variables can consume significant memory with large datasets
Subflow variable mapping must match types exactly — null/type mismatches cause runtime errors
Custom permission checks are cached — recent changes may not reflect immediately

Workflow

If migrating: Read existing PB metadata with Glob/Read tools
Analyze requirements or existing automation logic
Generate .flow-meta.xml file(s)
Generate any required Custom Permission metadata
Deploy dependencies first, then flows
Verify Flow test coverage: query FlowTestCoverage to ensure all decision branches are exercised
Provide verification steps

References

Flow Elements — complete XML reference for all element types, connectors, fault handling
Global Variables — complete $Variable reference with all accessible fields