Before diving into how it works, it’s important to understand a foundational concept: Data Arrays (Lists).
In the world of integrations, information doesn’t always arrive as a single item; sometimes it arrives in groups. For example, a "Deal" in a CRM might have several associated products. Each product is a Row, and the collection of products is an Array.
Example JSON object:
{ "dealName": "Corporate Sale", "items": [ { "name": "AI License", "quantity": "2" }, { "name": "Technical Support", "quantity": "1" } ] }The Iterator Tool is designed to handle each element of an array individually. This ensures that any subsequent steps in the Flow will execute a corresponding number of times, based on the number of elements present in the array.
Note: The Iterator Tool is most commonly used after "Search for Multiple Records" actions.
What challenges does the Iterator Tool address?
Imagine you have a database of customers with pending invoices and you want to automate payment reminders. If a customer has 3 outstanding invoices, you don't want to send one generic email; you want to process and detail each invoice separately.
Example using the Iterator Tool:
Trigger: The Flow is triggered at the end of the month.
Retrieve Data: Darwin searches your CRM for all pending payments for a specific client (this returns a list).
Iterator Tool: This is where the tool comes in. The iterator loops through each invoice in the list, one by one:
It extracts the invoice number, amount, and due date for each item.
It formats these details for the message.
Action: For every invoice found, the Flow can perform an action, such as sending an individualized WhatsApp message or updating the status of each specific item in a spreadsheet.
How to Access and Configure the Iterator Tool
To apply iteration logic to your workflow, follow these steps:
Identify the List: Open your automation and ensure you have a previous step that generates a data array (like a multiple search).
Add the Tool: Click on the "+" (Plus) button underneath the step containing the array.
Select "Tool": Click the Tool option and then select Iterator.
Set the Source: In the Iterator configuration, select the field that contains the "Array" or list you wish to break down.
Configure Subsequent Steps: Any module placed after the Iterator will automatically repeat for every single item in the list.
✅ Success Tip
If you are going to send bulk messages based on a list (for example, notifying 20 contacts found in a search), we recommend placing a Delay Tool immediately after the Iterator. This prevents all messages from being sent in the exact same second, protecting your sending reputation and avoiding spam blocks.
Frequently Asked Questions (FAQs)
What happens if the list is empty? If the Iterator finds no elements in the array, the subsequent steps will simply not execute, and the Flow will finish successfully without errors.
Can I edit the data within the iterator? Yes! You can use formatting tools (like a text or number formatter) inside the iterator's cycle so that each item is processed with the correct format before reaching its final destination.
Is this the same as a "Loop"? Yes. In programming terms, the Iterator functions as a for-each loop, traversing each object in a collection from start to finish.