Loop loop

When to Use

• Process each order in a batch: Loop over an array of orders retrieved from a database query, applying fulfilment logic, sending notifications, and updating statuses for each one individually.
• Send individual emails to each recipient: Loop over a recipient list and dispatch personalised email content per person — each iteration has its own current_item with the recipient's name and preferences.
• Update each record from a database result: After a MongoDB or SQL query returns an array of documents, loop over them to apply field updates, enrich with external API data, or write back transformed versions.
• Transform each item in a collection: Apply a normalisation, enrichment, or format-conversion pipeline to every element in an array before writing the results to a downstream system.
• Validate each field in a form submission: Iterate over a dynamic array of form answers to apply per-field validation rules, collecting failures into an error list for a structured validation response.

Configuration

Output Ports

OutputData Fields

Fields available after the loop via $output.<nodeKey>:

Per-Iteration Variables (Injected into ExecutionMemory)

These variables are available inside the loop body on every iteration via $var:

Sample Configuration

Loop over a variable

{
  "Items": "recipients"
}

Loop over a node output (MongoDB documents)

{
  "Items": "{{ $output.findOrders.documents }}"
}

Loop over a JSON array field from the trigger

{
  "Items": "{{ $json.lineItems }}"
}

Sample Output

Per-Iteration Output (Success Port)

The loop fires the success port once per item. Each execution carries the current item's data plus loop metadata.

{
  "productId": "PRD-00451",
  "sku": "WGT-BLK-L",
  "name": "Widget Black Large",
  "stock": 142,
  "reorderPoint": 50,
  "supplierId": "sup_001",
  "_loop": {
    "currentIndex": 3,
    "totalItems": 47,
    "isFirst": false,
    "isLast": false
  }
}

Loop Completed Port

{
  "_loop": {
    "completed": true,
    "totalItems": 47,
    "processedCount": 47,
    "errorCount": 0,
    "durationMs": 2341
  }
}

Expression Reference

Validation Errors

Node Policies and GuardRails

• Items must resolve to an array: The expression in the Items field must evaluate to a JSON array. To loop over MongoDB documents, use {{ $output.findDocs.documents }} not the node output object itself.
• Do not mutate the loop array inside the body: The loop array is materialised once at the start. Modifying the source variable inside the loop body does not affect the current iteration sequence — but it can cause confusing state for downstream code. Use a separate accumulator variable instead.
• Large arrays — consider batching: For arrays exceeding 1000 items, consider splitting into batches using a Function node or a pre-processing step before the loop. Very large loops increase workflow execution time and memory pressure.
• Nested loops require separate Loop nodes: To loop inside a loop, add a second Loop node inside the body branch. Each Loop node maintains its own current_item and current_index scope, so nested loops do not interfere.
• Always wire the done port: Post-loop logic (aggregation, summary, continuation) must connect to the done port, not the body port. Connecting continuation logic to the body means it runs once per item, not once after all items.

Pattern Examples

Pattern 1 — Batch Email Dispatch

Load a recipient list from a database query, then loop to send a personalised email to each recipient. After all emails are sent, trigger a completion notification.

MongoDB  [key: "getRecipients"]
  (find all active subscribers)
  └─► Loop  [key: "sendEmails"]
        Items: {{ $output.getRecipients.documents }}
        ├─► body ──► EmailSmtp  [key: "sendOne"]
        │             To:      {{ $var.current_item.email }}
        │             Subject: "Your monthly report is ready"
        │             Body:    "Hi {{ $var.current_item.firstName }}, ..."
        └─► done ──► SlackNode  (notify team: sent {{ $output.sendEmails.collection_size }} emails)

Pattern 2 — Per-Item Validation with Early Exit

Validate each item in a cart. If any item fails stock check, Break exits immediately and routes to an error response. Otherwise the done port proceeds to checkout.

FormTrigger  (checkout submitted)
  └─► Loop  [key: "validateCart"]
        Items: {{ $json.cartItems }}
        ├─► body ──► HttpRequest  [key: "checkStock"]
        │             GET /inventory/{{ $var.current_item.productId }}
        │             └─► IfCondition
        │                   Condition: {{ $output.checkStock.quantity > 0 }}
        │                   ├─► true  ──► (continue to next iteration)
        │                   └─► false ──► Break  (exit loop immediately)
        └─► done ──► [proceed to payment processing]

Pattern 3 — Accumulating Results Across Iterations

Transform each item and accumulate results into a list variable, then use the full list after the loop completes.

VariableAssignment  [key: "initResults"]
  processedOrders = []
  └─► Loop  [key: "processOrders"]
        Items: {{ $json.orders }}
        ├─► body ──► Function  [key: "transformItem"]
        │             (compute enriched order object)
        │             └─► VariableAssignment
        │                   processedOrders = {{ $var.processedOrders }}
        │                                     .concat([$output.transformItem.result])
        └─► done ──► HttpRequest  (POST /api/orders/bulk)
                       Body: {{ $var.processedOrders }}