Skip to content

The open alternative to Salesforce, designed for AI.

5.6 KB
Raw Blame
---
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" />