Skip to main content
Automation API

for_loop

Use this action to run a set of nested actions once for each item of a collection.

Tip

Read the live config shape of each action type from GET /v1/automation/meta/action before you build on it.

In the automation editor, this action is Loop actions in the Flow control family. Its group is control_flow, and it works with every trigger.

Send it in the actions array of Create an automation or Update an automation. An update replaces the whole array, so include the other actions.

Example​

An earlier collect_app_records action collected the open invoices of database app 12345. The loop skips invoices with the category option Paid (9001) and emails a payment reminder for each other one:

{
"type": "for_loop",
"config": {
"iterable": { "kind": "variable", "source": "action", "action_type": "record_collection", "app_id": 12345 },
"continue_condition": {
"operator": "and",
"rows": [
{
"subject": { "kind": "variable", "source": "field", "field_id": 512, "field_type": "single_category", "previous": false, "collection": true, "triggering": false },
"operator": "is_any_of",
"value": { "type": "ids", "ids": [9001] }
}
]
},
"action_rows": [
{
"type": "send_email",
"config": {
"to_address": [
{ "kind": "variable", "source": "field", "field_id": 514, "field_type": "multi_email", "previous": false, "collection": true, "triggering": false }
],
"subject": [
"Payment reminder for invoice ",
{ "kind": "variable", "source": "meta", "meta_type": "app_record_id", "collection": true, "app_id": 12345 }
],
"message_body": ["<p>This invoice is overdue.</p>"]
}
}
]
}
}

Config​

PropertyTypeDescriptionExample value
iterablereferenceWhat the loop goes through: a record_collection from an earlier collect_* action, a multi-value field or a custom variable.{ "kind": "variable", "source": "action", "action_type": "record_collection", "app_id": 12345 }
action_rowsarray of nested actionsThe loop body. Tape runs it once per item. Empty when left out.[{ "type": "send_email", "config": { … } }]
break_conditionfilter group | nullStops the loop when it matches. Off when left out.{ "operator": "and", "rows": [ … ] }
continue_conditionfilter group | nullSkips to the next item when it matches. Off when left out.{ "operator": "and", "rows": [ … ] }

To find the field IDs, see App and field IDs. To find the option IDs for ids, see Retrieve a single app. It returns them in config.settings.options of the field.

What happens for each item​

  1. Tape loads the item. Inside the loop, references with collection: true to fields and metadata of the collection's database app point to this item. For a custom variable, a custom reference to that variable points to this item. To read one property of it, use a code value such as [<reference>, ".price"]. This works in field assignments and template values. The assignment_code of a custom_variable inside the loop body doesn't see the item yet and reads undefined.
  2. Tape checks continue_condition. When it matches, Tape skips the body and moves to the next item.
  3. Tape runs the actions in action_rows.
  4. Tape checks break_condition. When it matches, the loop stops.

An item that matches break_condition still runs the body once. Then the loop stops.

General behavior​

  • No key is required. An empty config is valid, but the loop does nothing.
  • The whole loop lives in config, like every other action.
  • Send the collection as iterable. The internal name iterable_variable_def isn't part of the API.
  • Leave break_condition or continue_condition out to switch it off. There are no *_enabled flags. A condition sent as null or as an empty group has no effect and reads back as null.
  • Without iterable, Tape skips the loop when the automation runs.
  • validate checks that iterable resolves. A reference with no matching earlier action, for example a collect_* action placed after the loop, reports action_variable_missing.
  • validate doesn't check that the value can be looped over. A single-value field, or an action output that isn't a record_collection, passes validate and fails when the automation runs. Use only a record_collection, a multi-value field or a custom variable.
  • An iterable that's empty or null when the automation runs gives zero iterations, without an error.
  • A custom variable that holds an array gives one iteration per entry. Any other value gives one iteration with the whole value.

Requirements​

  • To add or change this action through the API, your token needs the automations:edit capability. See Capabilities.
  • You must administer the workspace that the automation's database app belongs to.
  • When iterable references a collection or custom variable, an earlier action must create it, for example collect_app_records, custom_variable or http_call.

Next steps​