Process Builder Migration

When to use

• The org still has active processes. Salesforce blocked creating processes in Summer '23 and ended support for Process Builder and Workflow Rules on 31 December 2025. Existing processes still execute, unsupported.
• A field is written by both a process and a flow, or two processes write it in step 13 of the save order, where no order is guaranteed.
• A story touches an object that a process automates: migrate that concern first, then build.
• /vf-check analyzer or an audit (sf-technical-debt-audit) reports active processes.

A process is not its own metadata type. It is a Flow whose processType is Workflow, stored in flows/ with a .flow-meta.xml suffix like every other flow. So a repository with "no Process Builder directory" can still be full of processes, and the retrieve command is Flow, not Process.

Decision table: which route for which process

The Setup tool and this plugin's converter answer different questions. The Setup tool is the fastest way to a working after-save flow. /vf-migrate-process is the way to a cheap before-save flow for the nodes that qualify, and an explicit list of what does not.

1. Inventory before touching anything

# Every process and flow the org runs, with its type and status
sf data query --use-tooling-api --target-org <alias> \
  --query "SELECT ApiName, Label, ProcessType, TriggerType, Status, VersionNumber FROM FlowDefinitionView WHERE ProcessType IN ('Workflow','InvocableProcess','CustomEvent')"

# Pull them into source; the metadata type is Flow
sf project retrieve start --metadata Flow:Case_triage --target-org <alias>

# What else automates the same object
sf data query --use-tooling-api --target-org <alias> \
  --query "SELECT Name, TableEnumOrId, Status FROM ApexTrigger WHERE TableEnumOrId = 'Case'"

Record the answer in .vibeforce/state/contract.md: object, process name, who else writes those fields. A migration that does not know the other writers is a rewrite with extra steps.

2. Read the process without reading the XML

A process file is large and almost entirely canvas coordinates and processMetadataValues. Reading it whole costs tens of thousands of tokens and tells you nothing the plan does not.

node "$CLAUDE_PLUGIN_ROOT/scripts/vf-process-to-flow.js" plan \
  force-app/main/default/flows/Case_triage.flow-meta.xml

The plan prints, per criteria node: the conditions as flow entry conditions would express them, the field writes that can become before-save assignments, the actions that must become after-save elements, the scheduled actions, and every reason the node cannot be converted mechanically. It quotes no XML. Exit 1 means the file does not convert - the wrong processType, an unreadable trigger, no reachable criteria node.

The command wrapper is /vf-migrate-process; the guard that denies whole-file reads of big metadata is described in sf-project-structure.

3. Target architecture, decided before any conversion

One process usually becomes more than one flow, because a process mixes work that belongs on different sides of the save.

flowchart TD
    P["Process, N criteria nodes"] --> C{"Per criteria node"}
    C --> F{"Actions only write<br/>the triggering record?"}
    F -- yes --> B["Before-save flow<br/>one Assignment on $Record"]
    F -- no --> A{"Time-based?"}
    A -- no --> S["After-save flow<br/>Update Records grouped per object"]
    A -- yes --> T["After-save flow<br/>+ scheduledPaths"]

Rules that decide the shape:

1. Field writes on the triggering record go before save. A before-save flow assigns to $Record. An Update Records element on the triggering record saves the record a second time, which is exactly the cost the migration is supposed to remove.
2. One Update Records element per target object, not per field. A process with four updates to the same Account is one element with four inputAssignments.
3. One flow per object per timing, not one flow per criteria node, once you are past the mechanical conversion. Entry conditions and a Decision inside the flow cost less than five flows racing in step 14.
4. Never both. The process is deactivated at the end of the migration, not kept "just in case".

4. Criteria nodes to entry conditions

Operators are where a conversion quietly breaks. FlowRecordFilter (entry conditions) accepts only EqualTo, NotEqualTo, GreaterThan, LessThan, GreaterThanOrEqualTo, LessThanOrEqualTo, StartsWith, EndsWith, Contains, IsNull. A process condition may use any FlowComparisonOperator, including IsChanged, WasSet and In, which have no entry-condition form: rebuild them as a Decision, or as an entry formula comparing {!$Record.F} with {!$Record__Prior.F}.

5. Action groups to flow elements

sf-flow-automation owns the element-level detail of the flow you are building; sf-apex-development owns the invocable class behind an Apex action.

6. Scheduled actions to scheduled paths

A time-based process migrates one outcome per flow. Select several criteria in the Setup tool and no scheduled action is migrated at all. Monitor the queue in Setup before and after: pending items that silently disappear are the failure mode.

7. The two semantics a mechanical conversion gets wrong

Start-of-process values. When a process continues to the next criteria node - the EVALUATE THE NEXT CRITERIA option - the next node evaluates the values the record had at the beginning of the process. A flow does the opposite: a Decision after an Assignment sees the value the Assignment just wrote. Chained criteria therefore cannot be split into independent flows, or turned into a straight Decision chain, without deciding which value each branch should see. The converter blocks these nodes instead of emitting them.

Reevaluation. A process may be configured to evaluate the same record up to five additional times in a single save. Flows have no equivalent, and Salesforce documents that a migrated process with recursion is evaluated only once. If the process relied on reevaluating - ISNEW, PRIORVALUE or a field the process itself changes - the migrated flow is a different automation and needs a deliberate test, not a diff.

8. Cutover, in two deploys

# 1. plan, then convert what converts
node "$CLAUDE_PLUGIN_ROOT/scripts/vf-process-to-flow.js" plan <process file>
node "$CLAUDE_PLUGIN_ROOT/scripts/vf-process-to-flow.js" convert <process file> --criteria 'myRule_1'

# 2. build the after-save half by hand from the plan's after-save lines

# 3. shape and validate before an org sees it
node "$CLAUDE_PLUGIN_ROOT/scripts/checks/vf-check.mjs" local --files <flow file>
sf project deploy validate --source-dir <flow file> --target-org <alias>

# 4. deploy the flows, activate them, verify behaviour against real records
# 5. only then, in a second deploy, deactivate the process

The order is not negotiable. Deactivating first leaves a window with no automation. Doing both in one deploy leaves no way to roll back one half. Keeping both active writes the same field twice in one save, in an order the platform does not define.

Anti-patterns

One flow per criteria node, all after-save, Update Records on the triggering record

<!-- WRONG: the record is saved a second time on every trigger -->
<recordUpdates>
    <name>Stamp_the_case</name>
    <inputReference>$Record</inputReference>
    <inputAssignments>
        <field>Priority</field>
        <value><stringValue>High</stringValue></value>
    </inputAssignments>
</recordUpdates>

<!-- RIGHT: before save, one Assignment, no DML -->
<assignments>
    <name>Set_Fields</name>
    <assignmentItems>
        <assignToReference>$Record.Priority</assignToReference>
        <operator>Assign</operator>
        <value><stringValue>High</stringValue></value>
    </assignmentItems>
</assignments>

Deploying the generated flow under the process's own API name

A Flow deployed with the process's fullName becomes a new version of the process, not a new flow. The converter refuses the name collision; do not work around it with --flow-name set to the same value.

Turning a criteria chain into a Decision chain and calling it equivalent

The second outcome now sees fields the first outcome wrote. See section 7. Either keep the chain in one flow and decide each branch's inputs deliberately, or split it and re-derive each entry condition.

Copying a process formula into a flow formula

Process formulas reference [Object].Field or myVariable_current.Field; flow formulas need {!$Record.Field}. A cross-object reference in a process formula cannot be migrated at all - it needs a Get Records element and a new formula.

Migrating with the process left active "until we are sure"

Two automations writing one field in one save, ordered by nothing. If confidence is the problem, the answer is a sandbox and a scratch org, not a double write.

Reading the process file into the session to plan the migration

Tens of thousands of tokens for information plan prints in twenty lines.

Verification

# The process file is a process, and this is what it does
node "$CLAUDE_PLUGIN_ROOT/scripts/vf-process-to-flow.js" plan <process file>

# The generated flow: XML shape, api version, formatting, static analysis
node "$CLAUDE_PLUGIN_ROOT/scripts/checks/vf-check.mjs" local --files <flow file>
node "$CLAUDE_PLUGIN_ROOT/scripts/checks/vf-check.mjs" analyzer --files <flow file>

# The org accepts it, without deploying it
sf project deploy validate --source-dir <flow file> --target-org <alias>

# After deploy: the flow is the active version and the process is not
sf data query --use-tooling-api --target-org <alias> \
  --query "SELECT ApiName, ProcessType, Status, VersionNumber FROM FlowDefinitionView WHERE ApiName IN ('Case_triage','Case_New_and_mine_Before')"

# The behaviour, on a real record
sf data create record --sobject Case --values "Status=New Origin=Web" --target-org <alias>
sf data query --query "SELECT Id, Priority, Subject FROM Case ORDER BY CreatedDate DESC LIMIT 1" --target-org <alias>

# Which automation actually ran
sf apex get log --number 1 --target-org <alias> | grep -E "FLOW_|CODE_UNIT_STARTED"

sf-post-deploy-verification owns the probe-and-rollback decision; sf-debugging-logs owns the FLOW_* markers and the Workflow log category that records processes and flows.

References

• references/process-metadata-anatomy.md - a process file element by element, the reference and operator mapping tables, the converter's contract and exit codes
• references/migrate-to-flow-tool.md - the Setup tool's supported and unsupported lists, partial migration, scheduled actions, the manual conversion methods

Sibling skills: sf-flow-automation (the flow you are building, plus workflow rule migration), sf-apex-development (order of execution, invocable Apex), sf-technical-debt-audit (finding the processes still running), sf-minimal-change (how small the change should be), sf-project-structure (flows/ and the metadata token bill), sf-deployment-strategies (flow activation on deploy), sf-post-deploy-verification (proving the cutover worked).

Sources: Metadata API Developer Guide, Flow (FlowProcessType, FlowStart, FlowRecordFilter, FlowRecordFilterOperator, FlowScheduledPath); "Automate Your Business Processes" - Process Builder, Execute Actions for Multiple Criteria, Reevaluate Records in the Process Builder, Migrate to Flow Tool Considerations, Move Processes and Workflows to Flow Builder with the Migrate to Flow Tool; Salesforce Help, end of support for Workflow Rules and Process Builder. API version 67.0.