Home / flow / flow-collection-processing

flow-collection-processing

Use when building or reviewing Flow logic that processes lists of records using Loop, Assignment, Collection Filter, Collection Sort, or Transform elements.

• v2.1.0
• Salesforce Spring '25+
• Updated 2026-09-05
• Performance
• Scalability
• Reliability

• flow-collections
• loop-element
• collection-filter
• collection-sort
• transform-element
• bulk-dml

Open the skill folder on GitHub

Flow Collection Processing

This skill answers one question: given a collection and a task, which element does the task? Flow has five documented answers — Collection Filter, Collection Sort, the Map processor, Transform, and the FlowAssignmentOperator set — plus the Loop, which does anything but costs body_elements × iterations to do it.

Loop mechanics (refactoring DML and SOQL out of a body, noMoreValuesConnector, iteration variables) belong to flow/flow-loop-element-patterns; transaction budgets belong to flow/flow-bulkification. This skill owns the selection, the configuration, and the shape of the XML that results.

Before Starting

• What is the collection variable's declared dataType and isCollection? Record, Text/Number and

  Apex-defined collections are accepted by different elements with different required fields.

• What is the flow's <apiVersion>, and what is the highest version floor among the elements you

  intend to use? Sort is API 50.0, Filter and Map are 53.0, sortOptions and processor limit are 51.0, Transform is 59.0, Transform's scalar output types are 62.0, InnerJoin and Get Records limit are 63.0.

• Where does the collection come from, and how large is it at p99? A collection from a Get Records

  spends the transaction's SOQL row budget; one assembled in memory spends heap.

• What consumes the result — a DML, a screen table, a subflow, an invocable action? The consumer

  decides the required type, and a generic-sObject consumer needs a separate typing mechanism.

• Is any part of the operation per-record conditional? That is the one thing no processor does.

Questions to Ask Before Configuring

What a proper configuration adds over just doing it: an element chosen from what the operation is rather than from what it reads like, an <apiVersion> that clears every floor it depends on, and a count that a FlowTest can fail on — so the flow's silence when it processes zero records becomes a test failure instead of a support ticket.

Element Selection

The decision this skill exists to make. Read the middle column, not the left one.

Enum values, version floors and field semantics: api_meta.txt L69926–L70002 (processors), L72685–L72814 (Transform), L69767–L69865 (assignment operators).

Collection Typing

Three collection shapes, and what each element accepts:

isCollection is documented from API 30.0, and "in API version 32.0 and later, a collection variable can be of any data type" (api_meta.txt L72880–L72884). A collection with no objectType is not a "broken" record collection — it is a differently-typed variable, and the elements will tell you so at deploy time rather than at run time.

Common Patterns

Pattern 1: Declarative pipeline — Filter → Sort+limit → Map → DML

The default shape. Each stage names the previous stage as its collectionReference; nothing is mutated in place; the DML at the end consumes the last processor by name. Fully worked, with the <start> block and the fault routing, in references/metadata-examples.md §1.

Pattern 2: Uniform field stamp without a Loop

outputSObjectType equal to the input type, mapItems carrying Id plus the one changed field, then Update Records with inputReference naming the processor. One element replaces Loop + Assignment + Assignment. Only valid when the new value is the same for every record.

Pattern 3: Aggregate to a scalar

A FlowTransform with dataType Number, isCollection false, and a transformValueActions whose transformType is Sum or Count. The source collection goes in the aggregationValues input key; for Sum, the field goes in aggregationField. The result is addressed by the transform's element name — no output-variable field exists (references/gotchas.md Gotcha 7).

Pattern 4: Set algebra instead of a nested loop

One Assignment element: Add to seed a working collection, then RemoveAll for difference or RemoveUncommon for intersection. Replaces n×m element executions with two assignment items. Declare in the flow's <description> that the seeding Add is Metadata-API-only.

Pattern 5: Terminate every chain with a count

An AssignCount into a non-collection Number variable at the end of the processor chain. It is the only artefact of the intermediate collections that survives to the Finish test point, and it converts a silent zero-record run into an assertable value. A Decision that only needs "is there anything?" uses the IsEmpty comparison operator instead (API 61.0 and later, api_meta.txt L70097–L70098) — there is no .size accessor.

Review Checklist

• [ ] Every collectionProcessorType is one of SortCollectionProcessor,

  FilterCollectionProcessor, RecommendationMapCollectionProcessor — checker E1.

• [ ] Every Sort carrying limit also carries sortOptions, or the cap has been pushed onto the

  upstream Get Records instead — checker E2.

• [ ] Every Map processor names both assignNextValueToReference and outputSObjectType, and every

  mapItems entry carries all three required fields — checker E3.

• [ ] Every transformType is one of the documented values, and GetItemByIndex / InvocableAction

  are not treated as live capabilities — checker E4.

• [ ] Every AssignCount target is a non-collection Number variable — checker E5.
• [ ] No AddItem targets anything but a Multipicklist variable — checker E6.
• [ ] No processor carries both formula and conditions — checker W1.
• [ ] No Loop body consists only of Assignments and Decisions — checker W2.
• [ ] Every collectionReference and aggregation input resolves to a declared variable or element —

  checker W3.

• [ ] The fault path hangs off the Get Records and the DML, not off any processor.
• [ ] The flow's <apiVersion> clears the highest floor among the elements used.
• [ ] A FlowTest asserts on at least one count produced by the chain.

Recommended Workflow

1. Classify the operation. Read the Element Selection table above and name the element before

   writing any XML. If the answer is Loop, stop here and switch to flow/flow-loop-element-patterns.

2. Read the collection's typing. Confirm dataType, isCollection and objectType against the

   Collection Typing table, then set the flow's <apiVersion> to the highest floor the chosen elements need (the floors are listed per element in references/metadata-examples.md §1).

3. Write the XML from references/metadata-examples.md §1, adapting the object names.

   Round-trip it: sf project retrieve start --metadata Flow:<name> and diff, because the guide ships no sample XML for FlowCollectionProcessor and every shape marked UNVERIFIED in that file has to come from the org.

4. Terminate the chain with an AssignCount into a Number variable, and write the FlowTest

   from §3 asserting on it. If the collection comes from related records, decide now whether flowTestDataSources (API 66.0, Apex-backed) is available or the test can only cover the triggering record.

5. Run the checker —

   python3 skills/flow/flow-collection-processing/scripts/check_flow_collection_processing.py --manifest-dir <source tree> --strict — and clear every ERROR. Rules map one-to-one onto the Review Checklist above.

6. Deploy in the order in §4 of references/metadata-examples.md (objects → Apex → Flow →

   FlowTest), then verify with the two SOQL queries and the FLOW_BULK_ELEMENT_DETAIL debug-log read in §5.

7. Record anything the guide could not settle in the flow's <description> — the

   Metadata-API-only Add, any UNVERIFIED shape you confirmed against your own org — using templates/flow-collection-processing-template.md.

Salesforce-Specific Gotchas

Full statements with grounding in references/gotchas.md; the one-line index:

1. The Sort processor accepts three collection shapes and each wants a different sortOptions.
2. AddItem is a multi-select-picklist operator; Add is the collection append.
3. Transform mappings do take formula expressions — formulaExpression and formulaDataType,

   API 59.0.

4. A processor emits a generated collection; it does not filter or sort in place.
5. Processors and Transforms have no faultConnector; their neighbours own the failure.
6. collectionFilterCriteria is a root Flow field named after the Collection Filter and reserved

   for future use.

7. Seven Transform fields and two transformType values are documented but inert — including both

   candidates for naming an output variable.

8. Three unrelated things in Flow metadata are called Count.
9. outputSObjectType types a processor's output; a generic sObject is typed by

   FlowDataTypeMapping with a mandatory T__ / U__ prefix.

10. Nothing in the developer guides caps collection size — and the flow interview's own limit-usage

    log event is the corroborating negative.

11. The loop iteration variable is a flow resource; the Add is what carries an edit out.
12. An empty collection is silent at every stage of a processor chain.

Proactive Triggers

Surface these WITHOUT being asked:

• A Loop body of only Assignments and Decisions → Critical. It is a Filter, Sort or Map written

  the long way; name the replacement element.

• limit on a Sort with no sortOptions → Critical. Reads as top N, behaves as arbitrary N.
• AddItem against a collection variable → Critical. Wrong operator; use Add.
• A Transform or processor with a faultConnector → High. Not a field of those types; the

  deploy will fail.

• A Map processor missing assignNextValueToReference → High. The mapItems have no source

  item to read.

• A processor chain with no terminal count → High. Nothing in it is assertable at the Finish

  test point.

• A seasonal release name attached to a collection element's availability → Medium. State the

  API version; this corpus has no release-name mapping.

• assignToReference or storeOutputAutomatically written on a Transform → Medium. Both are

  reserved; the output is addressed by element name.

• A collection-size ceiling quoted as a governor limit → Medium. None is documented; size

  against heap, CPU and the SOQL row budget.

Output Artifacts

Reference Files

Related Skills

• flow/flow-loop-element-patterns — when the answer is a Loop, or a Loop has to be refactored

  out; owns iteration semantics, noMoreValuesConnector, and the retired element-count limit.

• flow/flow-bulkification — when transaction budgets, data-load volume, or the escalate-to-Apex

  threshold is the question.

• flow/flow-formula-and-expression-patterns — when the formula on a Filter or the

  formulaExpression on a Transform has to be correct, not just placed.

• flow/flow-testing — when the FlowTest strategy, coverage or sf flow run test wiring is the

  question rather than what to assert on.

• flow/flow-record-save-order-interaction — when a collection DML re-enters the save order and

  the interaction with triggers, validation rules or roll-ups matters.

• flow/fault-handling — when the fault routing around the Get and the DML needs designing.
• flow/subflows-and-reusability — when a collection crosses a subflow boundary and the input

  contract has to be typed.

Package files

• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/metadata-examples.md
• references/well-architected.md
• templates/flow-collection-processing-template.md
• scripts/check_flow_collection_processing.py