Org Skills

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

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

RawSource

Target: Spring '26 (API 66.0). Sources: Flow Builder help, Execution Governors and Limits.

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.