Loop action

Loop action allows you to execute another action as many times as the amount of items in your array. It is very useful when you have an array of items and need to make additional request for each item of the array, or when you simply need to send a bunch of items to the API.

Use cases

1. Bulk users creation/update - collect all new/edited users in an array and then call POST/PUT API methods for every new item;

2. Load additional data - load your users and then make additional request for every user to load some extra information about them;

3. Send multiple notifications - find users that need to be notified about something and then send them Slack notifications.

Input & Output

Input - expects an array of items to iterate through.

Output - {{data}} - an array of execution results, {{error}} - array of execution errors.

Setup

Loop action takes a {{data}} variable passed from the previous step and if this variable is an array, executes a provided action as many times as the amount of items in the array.

1. Action to call in a loop - the main setting which determines which action will be executed in a loop;

2. Transform result - custom JavaScript function can be provided to modify the result of the action calls. Available variables: {{data}} and {{error}} - an array of results and errors;

3. Custom array to iterate - in case when you need to iterate some custom value, you can provide it instead of the previous step result. For instance, iterate over {{ui.table.value}} - an array of table rows.

To prevent the Loop action running into the API rate limits (in UI Bakery, the limit is 3 requests per second), you can configure the max iterations number - the maximum amount of iterations to be performed. When the iteration value is not set or set to 0, the number of iterations will be automatically set to infinity.

Additionally, you can run the iterations in chunks. To set this up, use the Execute in chunks of setting. The actions in chunks will be executed in parallel. If you don't want the chunking, set the number to 1.

To configure the delay between the chunks, use the corresponding setting Delay between chunks (ms). By default, it is set to 300 ms.

Parallel and sequential action execution

By default, the loop action tries to execute all iterations in parallel. This means that all iterations will start almost simultaneously. The resulting array will still respect the order: the result of the first run will be under the 0 index, the second run under the 1 index, etc.

If you turn it to the Sequential execution, the iterations will be sequential, and the second iteration only happens when the first one is completed (successfully or with an error).

Parallel execution is faster in a way. For example, if you do multiple database requests that don’t depend on each other, it is recommended to run them in parallel. But if you are inserting items and need to respect the insert order, then the sequential execution is a better choice.

Examples

Send a Slack message for each loaded user

Let's take a look at how to send a bunch of Slack messages to the users that we load from an API request.

1. Load users - create a Multi-step action, where the first step will load the users list - HTTP API call in our case.

2. Add a Loop action as a second step and click on Add new action button:

3. Create a new action that will be executed in a loop. To reference a single item of the initial users array, use {{data}} variable:

4. Now its time to test! Run the requestUsers action and check the result of the Loop action. You can see that it has all 5 responses from the Slack action the same amount as the users array:

The Logs section of the sendMessage action will also have 5 records of the action execution:

Send a message to each user selected in a table

Let's take a look at how to send a notification to a list of users selected in a table:

1. First, add a selected column to the table by adding a selected field with a boolean type and setting. This column will be used to filter out only selected rows:

2. Add a Loop action, enable Array to iterate through and a reference of a UI component value with a filter function, and specify a new sendMessage action:

3. Complete the sendMessage action:

Troubleshooting & Debug

If an executed action has failed, its' result will be set as undefined in the {{data}} results array and an error will be added into the {{error}} errors array: