# Object automation strategy — the coexistence rule, ADR template, migration

Target: Spring '26 (API 66.0). Source: [Record-Triggered Automation decision guide](https://architect.salesforce.com/docs/architect/decision-guides/guide/record-triggered), [Migrate to Flow](https://help.salesforce.com/s/articleView?id=platform.flow_migrate.htm&type=5).

This is the canonical statement of the Flow/Apex rule for the whole Salesforce area. `apex-development`, `salesforce-code-review` and `apex.instructions.md` link here instead of restating it.

## 1. The rule (one wording, everywhere)

> **One entry-point mechanism per object.** An object is driven either by record-triggered flows *or* by a single Apex trigger — not both. Multiple focused record-triggered flows on one object are fine and recommended; what is not fine is a second *kind* of entry point appearing without a decision.

Consequences:

- Several small record-triggered flows with tight entry conditions beat one mega-flow. Set **Trigger Order** on every one of them and read the result in **Flow Trigger Explorer**.
- Apex wins the object when the logic needs cross-object aggregation, callouts with retry, recursion control, complex collection work, or the object has high automation density and CPU time matters.
- Flow wins the object when admins own the logic, the work is field defaults, related-record creation, notifications and approvals, and Apex is only needed for one step — which becomes an `@InvocableMethod` called from the flow.
- **Legacy exception.** Many orgs already have both. That is allowed, but only as a documented exception: write the ADR below, name which mechanism owns which fields, and add nothing to the losing side.
- Workflow Rules and Process Builder can no longer be created. If any are still active on the object, the strategy must include their migration date.

## 2. Trigger Order — how the platform actually orders flows

Values are 1–2,000 on the flow's **Trigger Order** field (`triggerOrder` in `.flow-meta.xml`). For the same object and the same save phase (before-save or after-save):

1. Flows with a value of 1–1,000 run first, ascending.
2. Flows with **no** value run next, in order of their created date.
3. Flows with a value of 1,001–2,000 run last, ascending.
4. Equal values are broken by the flows' API names, alphabetically.

Practice: number in tens (10, 20, 30) so a flow can be slotted in later, and never leave a production flow without a value — its position then depends on a creation date nobody can see in the repo.

## 3. The strategy file

Keep one Markdown file per automated object next to the source (`docs/automation/<Object>.md`) and update it in the same pull request as the flow.

```markdown
# Automation — Order__c
Entry point: record-triggered Flow.  No Apex trigger on this object.
Owner: Order team.  Last reviewed: 2026-09.

| Order | Flow / class | Phase | Entry condition | Fields & records it writes |
|---|---|---|---|---|
| 10 | Order_Before_Upsert | before save (create, update) | always | Status__c, Region__c, Custom Error on Due_Date__c |
| 20 | Order_After_Update | after save (update), plus its async path | Status__c → 'Approved' | creates Shipment__c, publishes Order_Event__e; email + Slack on the async path |
| — | OrderPricingAction (invocable Apex) | called from 20 | — | Order_Line__c.Price__c |

Scheduled path: Due_Date__c + 3 days → escalation, on flow 20.
Bypass: `User.Ignore_Validation_Rules__c` checked in the flow entry conditions and in OrderPricingAction; Apex handlers carry their own per-handler bypass through `TriggerTemplateV2`.
Open risks: none.
```

Rules the table enforces: no field appears in two "writes" cells; every after-save flow that updates `$Record` is a bug (move it to before-save); every row has an owner.

## 4. ADR template — when Flow and Apex must coexist

```markdown
# ADR 014 — Case automation keeps both a flow set and an Apex trigger
Status: accepted (2026-09) · Supersedes: none · Review: 2027-03

## Context
Case has 4 record-triggered flows owned by Service Ops and CaseTrigger (entitlement
maths, 8 000 cases/day) owned by the platform team. Splitting either side costs more
than the risk it removes.

## Decision
Both remain. Ownership by field:
- Flow set owns Status, Priority, Owner assignment, notifications.
- CaseTrigger owns Entitlement__c, SLA_Target__c, Milestone roll-ups, ERP sync.
No new entry point is added to this object; new logic joins the side that owns the field.
Order: before-save flows → CaseTrigger before → after triggers → after-save flows
(full sequence: ../../../apex/apex-development/references/order-of-execution.md).

## Consequences
+ No migration cost, both teams keep their tooling.
− Two places to look when debugging; the runbook must mention both.
− CPU budget is shared: the flow set has a 4 s budget, the trigger 4 s, measured monthly.

## Alternatives rejected
Move entitlement maths into flows (collection maths too slow for 200-record chunks);
move all flows into Apex (Service Ops cannot maintain Apex).
```

## 5. Migrating Workflow Rules and Process Builder

1. **Inventory.** Setup → Workflow Rules and Process Builder lists, plus `Workflow` and `Flow` metadata in the repo. Record object, trigger conditions, actions, time-based queue entries.
2. **Drain time-based actions.** Pending time-dependent workflow actions survive deactivation — check *Time-Based Workflow* in Setup and let the queue empty (or delete entries deliberately) before deactivation, or the actions fire with no rule behind them.
3. **Convert.** *Migrate to Flow* (Setup) converts most Workflow Rules and Process Builder processes into record-triggered flows; it leaves out what it cannot express (outbound messages, some cross-object updates) — those are rebuilt by hand or replaced by a Platform Event.
4. **Re-home the logic.** A converted flow is a starting point, not the design: same-record field updates belong in a before-save flow, cross-object work in after-save, and the whole set gets Trigger Order values from section 2.
5. **Run both, compare, then cut over.** Activate the flow with entry conditions narrowed to a pilot record type or queue; compare outcomes; deactivate the workflow rule/process in the same release and delete it in the next.
6. **Outbound Messages** attached to workflow rules keep working, but a rule that only exists to send one is better replaced by a Platform Event plus a Pub/Sub subscriber (see `salesforce-integration`).
7. Record the migration date in the object's strategy file and close the loop: no object is "done" while an active Workflow Rule or Process Builder remains on it.
