The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
---
title: Use Iterator
description: Loop through arrays of records to perform actions on each item.
---
import { PageBanner } from "/snippets/page-banner.mdx"
## When to Use Iterator
| Scenario | Example |
|----------|---------|
| **Process search results** | Send email to each person found |
| **Handle webhook arrays** | Create records for each item in order |
| **Bulk updates** | Update multiple records with calculated values |
| **Notifications** | Alert multiple people about an event |
## Understanding Iterator
Iterator expects an **array** as input. It then:
1. Takes the first item from the array
2. Runs all actions inside the Iterator with that item
3. Moves to the next item
4. Repeats until all items are processed
### Selecting the array to loop over
Most array sources (Search Records, a webhook array field, a Bulk manual trigger) can be selected directly in the variable picker.
When a **Code** or **Logic Function** step returns a *top-level array*, its output appears in the variable picker as indexed entries (`0`, `1`, `2`, …). To loop over the array as a whole, select the **Whole list** option for that step — the Iterator then infers the shape of each item from the list automatically.
## Basic Setup
### Example: Email Everyone in Search Results
**Goal**: Find all contacts in a specific company and send each one a personalized email.
### Step 1: Search for Records
1. Add **Search Records** action
2. Object: **People**
3. Filter: Company equals "Acme Inc"
4. This returns an array of people
### Step 2: Check Results Exist
1. Add **Filter** action
2. Condition: `{{searchRecords.length}}` is greater than 0
3. This prevents Iterator errors on empty results
### Step 3: Add Iterator
1. Add **Iterator** action
2. Array input: Select `{{searchRecords}}`
3. This creates a loop
### Step 4: Add Actions Inside Iterator
Actions placed after Iterator run for each item:
1. Add **Send Email** action (inside Iterator)
2. To: `{{iterator.currentItem.email}}`
3. Subject: Hello `{{iterator.currentItem.firstName}}`!
4. Body: Personalized message using current item fields
### Result
If Search Records returns 5 people, the Iterator:
- Sends email to person 1
- Sends email to person 2
- ... continues for all 5
## Accessing Current Item Data
Inside Iterator, use `{{iterator.currentItem}}` to access the current record:
| Variable | Description |
|----------|-------------|
| `{{iterator.currentItem}}` | The entire current record object |
| `{{iterator.currentItem.id}}` | Record ID |
| `{{iterator.currentItem.email}}` | Email field |
| `{{iterator.currentItem.company.name}}` | Related company name |
| `{{iterator.index}}` | Current position in array (0-based) |
In the variable picker, you can either drill into a specific field of the current item, or pick **Use the whole item** to reference the entire current item (`{{iterator.currentItem}}`). Selecting the whole item is handy when you want to pass a full record straight into a downstream step rather than rebuilding it field by field.
## Common Patterns
### Update Multiple Records
**Goal**: Mark all overdue tasks as "Late"
```
1. Search Records (Tasks, Due Date < Today, Status ≠ Completed)
2. Filter (length > 0)
3. Iterator (searchRecords)
└── Update Record
- Object: Tasks
- Record: {{iterator.currentItem.id}}
- Status: Late
```
### Create Records from Array
**Goal**: Webhook receives order with multiple items, create a record for each
```
1. Webhook Trigger (receives items array)
2. Filter (items.length > 0)
3. Iterator (trigger.items)
└── Create Record
- Object: Order Items
- Name: {{iterator.currentItem.name}}
- Quantity: {{iterator.currentItem.qty}}
- Related Order: {{trigger.orderId}}
```
### Conditional Processing Inside Loop
**Goal**: Only send email to contacts with valid emails
```
1. Search Records (People)
2. Iterator (searchRecords)
└── Filter (currentItem.email is not empty)
└── Send Email
- To: {{iterator.currentItem.email}}
```
## Troubleshooting
### "Iterator expects an array"
**Cause**: You passed a single record instead of an array.
**Fix**: Make sure you're passing the result of Search Records or an array field, not a single record.
```
✅ Correct: {{searchRecords}}
❌ Wrong: {{searchRecords[0]}}
```
### Iterator Doesn't Run
**Cause**: The array is empty.
**Fix**: Add a Filter before Iterator to check array length:
```
Filter: {{searchRecords.length}} > 0
```
### Actions Run Too Many Times
**Cause**: Search Records returned more records than expected.
**Fix**:
- Add more specific filters to Search Records
- Set a limit on Search Records (max 200)
- Add Filter inside Iterator for additional conditions
## Performance Considerations
- **Credit usage**: Each iteration consumes credits for its actions
- **Time**: Large arrays take longer to process
- **Limits**: Consider batching very large operations
- **Rate limits**: External API calls may hit rate limits with many iterations
## Best Practices
1. **Always check array length** before Iterator to avoid errors
2. **Add filters inside loops** when not all items need processing
3. **Rename your Iterator step** to describe what it's looping through
4. **Test with small arrays** before processing large datasets
5. **Monitor workflow runs** to ensure iterations complete as expected
## Related
- [Workflow Actions](/user-guide/workflows/capabilities/workflow-actions)
- [How to Use Branches](/user-guide/workflows/capabilities/use-branches-in-workflows)
- [Workflows FAQ](/user-guide/workflows/how-tos/need-more-help/workflows-faq)
<PageBanner illustration="card-page-sync-recovery" />