List - Map
Type identifier:
list:mapCategory: List Operations
Description
Iterates over each item in a list and runs the nodes connected to the trigger output for each one. Creates a scoped context for each iteration where the current item is available. Collects results from all iterations into an output list. Supports both parallel and sequential modes.
Input Handles
Handle | Data Type | Required | Description |
|---|---|---|---|
|
| Yes | Initiates the map operation |
|
| Yes | The array to iterate over |
|
| No | Value to add to result list (per iteration) |
|
| No | Incoming error control route |
Input Handle Details
list
- Type:
array Notes:
- Must be an array
- Can contain at most 1,000 items
- Each item is processed in a scoped context
- Empty arrays result in empty output list
return
- Type: Varies
Notes:
- Receives the mapped value for each iteration
- Connected from the nodes in the iteration back to this node
- Each value is collected into the
listoutput at the original input position - Runs with expandable iteration history collect missing return values as
null
Output Handles
Handle | Data Type | Description |
|---|---|---|
|
| Triggered for each item iteration |
|
| Continues after successful control-triggered mapping |
|
| Handles invalid list input when connected |
|
| Current item (per iteration) |
|
| Current index (per iteration) |
|
| Collected results from all iterations |
Output Handle Details
item
- Type: Same as input array item type
- Notes: Available within the iteration context
index
- Type:
number - Notes: Zero-based index of current item
list
- Type:
array Notes:
- Contains all
returnvalues in order - Completion order does not change the result order
- An empty input produces an empty output
- Contains all
Configuration Options
Property | Type | Required | Default | Description |
|---|---|---|---|---|
|
| Yes |
| Display label for the node |
|
| No |
| Run iterations sequentially |
Configuration Details
sequential
- Type:
boolean - Default: New nodes have Sequential? selected. If the property is omitted from a saved definition, the node uses parallel mode.
Notes:
false: Iterations may overlap within the run's available concurrencytrue: Iterations run one at a time in order- Parallel mode does not guarantee simultaneous starts; available concurrency can allow only one item at a time
Behaviour
Value Traits in Flows v2
Each item receives the traits that apply to its input position. Returned values retain their own traits at their positions in the result list; one sensitive item does not mark unrelated items. A trait on the entire input list is inherited by its items and the result list.
Run inspection shows sensitive item paths using concrete indices. The entire containing payload remains unavailable if any item is sensitive. Flow Result may pass that list back to an inline child Flow's caller, but cannot return it as the top-level Flow run result.
Execution Flow
- Reads the
listinput - Validates input is an array
- Runs the nodes connected to the
triggeroutput for each item, with that item'sitemandindexavailable - Collects
returnvalues from all iterations - Outputs collected results as
list - Continues through
successafter successful control-triggered mapping
When the node is used only as a data source, it resolves the values needed for return without starting the iteration's control route or emitting success.
Parallel vs Sequential
Mode | Behaviour |
|---|---|
Parallel | Iterations may overlap within available run concurrency |
Sequential | Each iteration waits for previous to complete |
Context Scoping
Each iteration runs separately with its own:
item: Current array elementindex: Current position (0-based)- Results are isolated between iterations
returnvalues are collected intolist
Runs with expandable iteration history resolve data from outside the iteration once and share it with the items. Item results remain isolated. Nested maps have their own iterations rather than overwriting the parent item's values.
Run History
In run histories with recorded iteration details, List - Map appears as an expandable group with the node label, iteration count, mode, status, and duration. The map group starts expanded; individual iterations start collapsed.
Iteration labels start at Iteration 1 and follow input-list order, even when iterations run in parallel. Each iteration contains its own node events, nested maps, and child Flow runs. Expanding an iteration makes its events available for inspection.
Groups show running, succeeded, failed, abandoned, or incomplete as applicable. Duration is shown only when both start and end events are available. When a loaded map or iteration is incomplete, has missing iterations, or lacks duration details, the timeline automatically retrieves subsequent pages until those details are complete or no more history is available. A loading error stops automatic retrieval and is displayed in the timeline; Load more events remains available to retry. Filtered or unavailable history can still show incomplete and duration unavailable even after a run has finished. Events remain visible without grouping when the loaded history does not identify their iteration.
Expansion choices are retained while viewing the same run and reset when opening another run.
Trigger Handles
Incoming Trigger | Behaviour |
|---|---|
| Starts the mapping process |
| Propagates to |
| Collects value into |
| Currently ignored |
The incoming and outgoing error handles are distinct. Graphs using the incoming error route may use run histories without expandable iteration details. The outgoing route is not a catch-all handler for failures inside the iteration.
Error Handling
Scenario | Behaviour |
|---|---|
Input is not an array | Takes the connected |
Input contains more than 1,000 items | Takes the connected |
Unhandled iteration failure | Stops unfinished work in that iteration; other items can finish. The map does not recover through its |
Missing return value | Runs with expandable iteration history collect |
Empty array | Returns empty |
Examples
Transform Array Items
{
"type": "list:map",
"data": {
"label": "Process Orders",
"sequential": false
}
}Connect: list ← array source, item → processing nodes, processing result → return, list → downstream node.
Sequential Processing
{
"type": "list:map",
"data": {
"label": "Sequential API Calls",
"sequential": true
}
}Iterations run one at a time, so their operations do not overlap.
Extract Properties
{
"type": "list:map",
"data": {
"label": "Extract Names"
}
}Map over an array of objects, extract a property with Object - Pick, return extracted value.