for_loop
Use this action to run a set of nested actions once for each item of a collection.
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
| Property | Type | Description | Example value |
|---|---|---|---|
iterable | reference | What 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_rows | array of nested actions | The loop body. Tape runs it once per item. Empty when left out. | [{ "type": "send_email", "config": { … } }] |
break_condition | filter group | null | Stops the loop when it matches. Off when left out. | { "operator": "and", "rows": [ … ] } |
continue_condition | filter group | null | Skips 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
- Tape loads the item. Inside the loop, references with
collection: trueto fields and metadata of the collection's database app point to this item. For a custom variable, acustomreference 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. Theassignment_codeof acustom_variableinside the loop body doesn't see the item yet and readsundefined. - Tape checks
continue_condition. When it matches, Tape skips the body and moves to the next item. - Tape runs the actions in
action_rows. - 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
configis valid, but the loop does nothing. - The whole loop lives in
config, like every other action. - Send the collection as
iterable. The internal nameiterable_variable_defisn't part of the API. - Leave
break_conditionorcontinue_conditionout to switch it off. There are no*_enabledflags. A condition sent asnullor as an empty group has no effect and reads back asnull. - Without
iterable, Tape skips the loop when the automation runs. validatechecks thatiterableresolves. A reference with no matching earlier action, for example acollect_*action placed after the loop, reportsaction_variable_missing.validatedoesn't check that the value can be looped over. A single-value field, or an action output that isn't arecord_collection, passesvalidateand fails when the automation runs. Use only arecord_collection, a multi-value field or a custom variable.- An
iterablethat's empty ornullwhen 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:editcapability. See Capabilities. - You must administer the workspace that the automation's database app belongs to.
- When
iterablereferences a collection or custom variable, an earlier action must create it, for examplecollect_app_records,custom_variableorhttp_call.