process-builder-to-flow-migration

# Process Builder to Flow Migration

Use this skill when orgs still have active Process Builder processes that need to move to record-triggered Flows before the December 31 2025 end-of-support deadline. Process Builder new creation was blocked in Spring '25; existing processes continue to execute but receive no bug fixes. Migration is mandatory, not optional.

---

## Before Starting

Gather this context before working on anything in this domain:

- Inventory all active and inactive Process Builder processes: query `ProcessDefinition` via Salesforce CLI or Workbench SOQL
- Determine what action types each process uses — invocable Apex, callouts, tasks, and scheduled actions require manual rebuild; the tool cannot convert them
- Map all automation on each affected object (Process Builder, other Flows, Apex triggers) to plan execution order via Flow Trigger Explorer

---

## Core Concepts

### The Migrate to Flow Tool

Setup > Migrate to Flow converts supported Process Builder processes into **inactive** record-triggered flows for review before activation. The tool handles: field updates, email alerts, Post to Chatter, and immediate criteria + actions.

**The tool does NOT handle:**
- Invocable Apex actions
- Scheduled actions requiring async paths
- External callout actions
- Task creation (Create Task actions)
- `ISCHANGED()` / `ISNEW()` formula criteria — these have no direct Flow mapping
- Global variables in criteria
- Record-type-based criteria
- Related-record field updates (parent/child via relationship)

For any process using unsupported features, manual rebuild in Flow Builder is required.

### Order-of-Execution Change

Process Builder execution was determined by process creation date — oldest process on an object ran first. This was opaque. Record-triggered flows use **Flow Trigger Explorer** with explicit priority integers (lower = earlier execution).

When migrating: inventory all processes per object, determine intended order, and assign Flow Trigger Explorer priority integers accordingly. Running both an active Process Builder **and** an active Flow on the same object creates unpredictable execution order — disable the Process Builder process immediately after activating its Flow equivalent.

### Bulk Behavior Improvement

Performance gains from migration are significant: before-save Fast Field Updates run approximately **10× faster** than equivalent Process Builder field updates; after-save flows run approximately **50% faster**. These gains only materialize if the migrated flow is bulk-safe (no SOQL or DML inside loops).

---

## Common Patterns

### Tool-Eligible Migration

**When to use:** Process uses only field updates, email alerts, and Chatter posts with no ISCHANGED/ISNEW criteria and no Apex/callout actions.

**How it works:**
1. Setup > Migrate to Flow > select process > Convert
2. Review generated inactive flow in Flow Builder — verify Decision conditions match original criteria
3. Add a Fault Path to every DML element (not generated by tool)
4. Run bulk test in sandbox, then activate and deactivate source process

**Why not skip review:** The generated flow is inactive for a reason — the tool may drop criteria or generate incorrect conditions that look right but behave differently.

### Manual Rebuild for ISCHANGED/ISNEW Criteria

**When to use:** Process uses `ISCHANGED(FieldName)` or `ISNEW()` in its entry criteria or action criteria.

**How it works:** In the record-triggered flow Decision element, replace:
- `ISCHANGED(FieldName)` → condition: `{!$Record.FieldName} Is Changed` (entry criteria) or `{!$Record.FieldName} != {!$Record__Prior.FieldName}` (Decision node)
- `ISNEW()` → trigger: Only when record is created (entry criteria setting), or check `{!$Record__Prior.Id} Is Null`

### Scheduled Action Replacement

**When to use:** Process has scheduled actions (run 3 days after close date, etc.)

**How it works:** Create a Scheduled Path on the record-triggered flow. Set the time source field and offset. Note: scheduled actions in flight at Process Builder deactivation do NOT automatically transfer — they are cancelled. Plan cutover to minimize in-flight actions.

---

## Decision Guidance

| Scenario | Recommended Approach | Reason |
|---|---|---|
| Field updates, email alerts only | Migrate to Flow tool | Fastest, lowest risk |
| Invocable Apex or callout actions | Manual rebuild | Tool cannot convert |
| Scheduled actions | Manual rebuild with Scheduled Paths | Tool cannot convert async |
| Task creation | Manual rebuild with Create Records | Tool cannot convert |
| ISCHANGED/ISNEW criteria | Manual rebuild with `$Record__Prior` | No direct tool mapping |
| Multiple processes on same object | Consolidate into single flow + Decisions | Avoids execution-order ambiguity |

---

## Recommended Workflow

1. **Inventory all processes**: Use SOQL `SELECT Id, Name, TableEnumOrId, ActiveVersionId FROM ProcessDefinition WHERE Type='Flow'` and review each process for action types and criteria.
2. **Triage tool-eligible vs. manual-rebuild**: Any process using invocable Apex, callouts, tasks, ISCHANGED/ISNEW criteria, or scheduled actions requires manual rebuild — flag before running the tool.
3. **Run Migrate to Flow on eligible processes**: Setup > Migrate to Flow > select process > Convert. Tool creates an INACTIVE flow — do not activate yet.
4. **Rebuild unsupported actions**: Open the generated (or new) flow in Flow Builder; add missing elements (Apex actions, Create Records for tasks, Scheduled Paths for async).
5. **Assign Flow Trigger Explorer priorities**: Open Flow Trigger Explorer for the object; assign priority integers matching intended execution order. No two flows should share the same priority.
6. **Test in sandbox with 200+ records**: Verify governor limits hold, assert expected field values, confirm no SOQL-in-loop failures. Use Execute Anonymous to bulk-load test records.
7. **Activate flow and deactivate Process Builder simultaneously**: Never run both active on the same object. Deactivate PB process the moment the Flow is activated.

---

## Review Checklist

- [ ] All processes inventoried; unsupported actions identified before running tool
- [ ] Tool used only for supported action types; manual rebuild for the rest
- [ ] ISCHANGED()/ISNEW() criteria rebuilt using `$Record__Prior` comparisons
- [ ] Fault paths added to all DML elements in migrated flows
- [ ] Flow Trigger Explorer priorities assigned; no conflicts with existing flows
- [ ] Active PB process deactivated immediately after flow activation
- [ ] Bulk test with 200+ records passed in sandbox
- [ ] No SOQL or DML inside loops in migrated flow
- [ ] Scheduled actions rebuilt using Scheduled Paths (not kept as PB schedules)
- [ ] Pending scheduled actions in flight accounted for in cutover plan

---

## Salesforce-Specific Gotchas

1. **Scheduled actions are cancelled on Process Builder deactivation** — Any pending scheduled actions (e.g., "send email 5 days after close") queued from Process Builder are silently cancelled when you deactivate the process. There is no automatic handoff to the new Flow. Plan cutover timing to minimize in-flight actions, or notify stakeholders that pending scheduled actions will not fire.
2. **Active PB + active Flow on same object = undefined order** — Salesforce does not guarantee execution order when both a Process Builder process and a record-triggered flow are active on the same object. This creates impossible-to-debug bugs in production. Deactivate the Process Builder the moment the Flow is activated — no grace period.
3. **ISCHANGED()/ISNEW() is silently dropped by the tool** — The Migrate to Flow tool does not warn you when it encounters ISCHANGED or ISNEW criteria — it may omit those conditions or generate a flow that fires unconditionally. Always review Decision conditions in generated flows against original PB criteria.

---

## Output Artifacts

| Artifact | Description |
|---|---|
| Inactive record-triggered flow | Generated by tool or built manually; must be reviewed before activation |
| Flow Trigger Explorer configuration | Priority integers for all flows on affected objects |
| Migration test plan | Bulk-load scenarios and assertions for sandbox validation |
| Process Builder deactivation log | Timestamp record of each process deactivated |

---

## Related Skills

- `flow/workflow-rule-to-flow-migration` — companion skill for Workflow Rule migration
- `flow/record-triggered-flow-patterns` — canonical patterns for destination flow type
- `flow/fault-handling` — add fault paths to migrated flows
- `flow/flow-large-data-volume-patterns` — bulk-safety for migrated flows
- Decision tree: `standards/decision-trees/automation-selection.md`