Org Skills

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

Supporting material for salesforce-automation. Agents load it on demand; it ships inside the skill folder.

RawSource

Target: Spring '26 (API 66.0). Source: Record-Triggered Automation decision guide, Migrate to Flow.

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.

# 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

# 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.