# Bulk-safe record-triggered flows — element trace, metadata keys, limits

Target: Spring '26 (API 66.0). Sources: [Flow Builder help](https://help.salesforce.com/s/articleView?id=platform.flow_concepts_trigger_record.htm&type=5), [Execution Governors and Limits](https://developer.salesforce.com/docs/atlas.en-us.salesforce_app_limits_cheatsheet.meta/salesforce_app_limits_cheatsheet/salesforce_app_limits_platform_apexgov.htm).

## 1. How bulkification actually works

A record-triggered flow runs **one interview per record**, but the platform groups the same element across the interviews of one 200-record chunk into a single query or a single DML statement — *only* when that element sits outside a loop and is reached with the same configuration. An element inside a loop cannot be grouped: 200 records × 10 lines is 2,000 executions and 2,000 rows of DML in 10 separate statements per interview.

So the whole art is: **collect inside the loop, act after it.**

## 2. Target shape of an after-save flow

```
Start
  Object: Order__c · After save · Created and updated
  Entry: Status__c Equals 'Approved'
  ✔ "Only when a record is updated to meet the condition requirements"   ← recursion guard
  Trigger Order: 20 · Run asynchronously: no

Get Records   Shipment_Config__mdt   (all configs, once — outside every loop)
Decision      Config found?  → No → Custom Error "Shipment configuration missing"
Assignment    varLines = {!$Record.Order_Lines__r}            (child records from Start, no Get)
Loop          over varLines  →  Assignment: build one Shipment_Line__c record
                              →  Assignment: add it to colNewLines
Create Records  colNewLines   (once, AFTER the loop, "multiple records from a collection")
  └ Fault → Subflow Log_Flow_Fault (invocable logger) → Custom Error with a support reference
Action        Publish Order_Event__e        (Create Records on the event object)
```

Cost per 200-record chunk: 1 SOQL (the `__mdt` Get), 1 DML (the Create), 0 extra queries for the children because `$Record.Order_Lines__r` is resolved by the platform.

## 3. Element rules

| Element | Rule |
|---|---|
| Get Records | Never inside a Loop. Filter on indexed fields, set *Number of records* to "Only the first" when one is expected, and store only the fields used. |
| Create / Update / Delete Records | One per flow path, after the loop, using a record collection variable. |
| Loop | Only Assignment, Decision and formula work inside. |
| Collection Filter / Collection Sort / Transform | Replace loops that only filter, sort or map. Cheaper and readable. |
| Assignment on `$Record` | Before-save only. It writes the field with no DML and no recursion. |
| Update Records on `$Record` in an after-save flow | Always a bug — a second DML and a re-entrant save. Move to before-save. |
| Custom Error | The way a before-save flow blocks a save with a field-level or record-level message. Replaces "fault → email" validation. |
| Action (HTTP Callout, External Services, invocable Apex with callouts) | Async path or screen flow only. A callout after DML in the same transaction throws "You have uncommitted work pending". |
| Subflow | The shared fault handler and any logic used by more than one flow. |
| Scheduled path | Runs in its own transaction as the flow owner; make it idempotent and re-check the entry condition, because the record may have changed. |

## 4. `.flow-meta.xml` keys to check in review

| Key | What to look for |
|---|---|
| `<status>` | `Active` in the deployed version; `Draft`/`Obsolete` versions should not be in the package |
| `<triggerType>` | `RecordBeforeSave`, `RecordAfterSave`, `RecordBeforeDelete`, `Scheduled`, `PlatformEvent` — matches the design |
| `<recordTriggerType>` | `Create`, `Update`, `CreateAndUpdate`, `Delete` — narrower is better |
| `<triggerOrder>` | Present on every record-triggered flow, in tens |
| `<runInMode>` | `DefaultMode` unless there is a written reason for `SystemModeWithSharing` / `SystemModeWithoutSharing` |
| `<filterLogic>` / `<filters>` on `<start>` | Entry conditions exist and are narrow |
| `<doesRequireRecordChangedToMeetCriteria>` | `true` on update flows that must not re-fire |
| `<apiVersion>` | Current release; flows below API 57.0 still carry the retired 2,000-element limit |
| `<recordLookups>` / `<recordCreates>` inside `<loops>` connectors | Trace the connector chain: a DML element reachable only from inside a loop is the bulk bug |

## 5. Limits that still bite

| Limit | Value | Note |
|---|---|---|
| SOQL queries per transaction | 100 (sync) / 200 (async) | **Shared with Apex and every other flow in the same transaction** |
| DML statements | 150 | Shared likewise |
| DML rows | 10 000 | A flow creating 60 children per order hits this at ~167 orders |
| CPU time | 10 s (sync) / 60 s (async) | The usual failure mode for flow-heavy objects |
| Records per schedule-triggered flow run | 250 000 per 24 h, or licences × 200 if greater | Batch Apex or Apex Cursors above that |
| Flow interviews per transaction | Bound by the above, not by an element count | The old **2,000 executed elements** cap was removed for flows on API 57.0+ |
| Screen-flow element count | No per-interview element cap | Still keep screens short; each screen is a round trip |

## 6. Proving it is bulk-safe

- Load 200 records in a scratch org with `sf data import tree` (or a quick anonymous Apex insert) and watch the debug log: `LIMIT_USAGE_FOR_NS` at the end of the transaction shows SOQL/DML actually used.
- Flow Tests cover the logic per record; they do not prove bulk safety. The 200-record proof is an Apex test that inserts/updates 200 records and asserts `Limits.getQueries()` and `Limits.getDmlStatements()` (see `apex-testing`).
- `sf code-analyzer run --workspace force-app --rule-selector flow` catches the structural findings (DML in loop, missing fault path, hard-coded Id) before review.
