Skip to main content

Iterate Through Array

The Iterate Through Array action loops over an array of items and executes a set of nested actions once for each item. It is the primary way to perform batch operations in Email2AT: adding notes to multiple tickets, sending emails to multiple recipients, creating records for multiple devices, and so on.

When to Use This Action​

Use this action when:

  • You have queried Autotask for multiple results (using API: Query for Object(s)) and want to do something to each one
  • You want to process each attachment on an inbound email individually
  • You need to send notifications or create records for each item in a list

How It Works​

You provide:

  1. The array to iterate over: typically a variable set by a previous Query step
  2. A variable name for the current item: accessible as {{custom.variableName}} inside the nested actions
  3. The nested actions to run: executed once per item, with access to the current item's properties

On each pass through the loop, the current item is placed into the variable you name. When the loop is complete, execution continues with the next top-level action after the Iterate step.

Configuration​

FieldDescription
Field to IterateThe array to loop over. Use the selector to choose from available arrays, or unlock it to enter a variable path directly (e.g., custom.tickets).
Value Variable NameThe name for the current item variable (prefixed automatically with custom.). Inside nested actions, reference the current item as {{custom.<name>}} and its properties as {{custom.<name>.propertyName}}.
Key Variable NameThe name for the current index variable (0, 1, 2, ...). Useful if you need to know the position of the current item.
Actions to ExecuteThe nested actions to run for each item. These have access to the current item variable, the index variable, and all other workflow data from earlier steps.

Building the Nested Actions​

Inside the Iterate action, you can use any action that is available in a regular rule: API calls, Send Email, Perform Regular Expression, Stop actions, and more.

Reference the current item using the variable name you configured. For example, if you named the value variable ticket, you can reference {{custom.ticket.id}}, {{custom.ticket.ticketNumber}}, {{custom.ticket.accountId}}, and so on.

Behavior​

  • If the array is empty, the iteration is skipped silently and processing continues
  • If the field does not exist or is not iterable, a warning is logged and the action is skipped
  • A Stop Processing This Rule action inside the iteration stops only the current iteration pass and moves on to the next item
  • A Stop Processing This Message Completely action inside the iteration stops the entire workflow

Returned Variables​

This action does not return variables directly. Nested actions inside the iteration can store their own results using Store the results in variable, but those variables are scoped to the current iteration pass and overwritten on the next pass.

Common Pattern: Query Then Iterate​

The most common use of the Iterate action is in combination with API: Query for Object(s):

  1. API: Query for Object(s): query Autotask for all matching entities (e.g., all open tickets for a contact), store results as custom.tickets
  2. Iterate Through Array: loop over custom.tickets, calling the current item custom.ticket
  3. Nested actions: perform an operation on {{custom.ticket.id}} for each ticket in the array

This pattern can process as many items as the query returns without any additional configuration.

Example Use Cases​

Add a note to every open ticket for a contact​

Scenario: A customer emails in and you want to add a note to all of their open tickets at once.

Steps:

  1. API: Query for One Object (Contact): find the contact by email.from.address, store as custom.contact
  2. API: Query for Object(s) (Ticket): find all tickets where:
    • ContactID equals {{custom.contact.id}}
    • Status does not equal Complete
    • Store as custom.tickets
  3. Iterate Through Array: iterate over custom.tickets, value variable = ticket
    • Nested: API: Create an Object (TicketNote)
      • TicketID = {{custom.ticket.id}}
      • Title = {{email.subject}}
      • Description = {{email.body_stripped.visible}}
      • NoteType = Task Summary
      • Publish = All Autotask Users

Add a contract to every ticket missing one​

Scenario (scheduled task): Autotask sometimes creates tickets without associating the account's default service contract. A scheduled task finds those tickets and fixes them.

Steps:

  1. Render Text and Store as Variable: render {{date add="-4 weeks"}}, store as custom.startDate
  2. API: Query for Object(s) (Ticket): find all tickets where:
    • ContractID is null
    • CreateDate is greater than {{custom.startDate}}
    • Store as custom.tickets
  3. Iterate Through Array: iterate over custom.tickets, value variable = ticket
    • Nested: API: Query for One Object (Contract): find a contract where:
      • AccountID equals {{custom.ticket.accountId}}
      • IsDefaultContract equals true
      • StartDate is less than today
      • EndDate is greater than today
      • Store as custom.contract
    • Nested: API: Update an Object (Ticket): only if custom.contract.id is not null:
      • ID = {{custom.ticket.id}}
      • ContractID = {{custom.contract.id}}
      • Enable Suppress Autotask API exceptions because some tickets may legitimately reject contract assignment (e.g., billing is closed) and you do not want those to stop the loop

Create a ticket for every CI of a certain type​

Scenario (scheduled task): Monthly, create a maintenance ticket for every active server CI.

Steps:

  1. API: Query for Object(s) (InstalledProduct): find all CIs where:
    • IsActive equals true
    • ProductID equals your "Server" product type ID
    • Store as custom.configItems
  2. Iterate Through Array: iterate over custom.configItems, value variable = ci
    • Nested: API: Create an Object (Ticket)
      • AccountID = {{custom.ci.accountId}}
      • InstalledProductID = {{custom.ci.id}}
      • Title = Monthly maintenance - {{custom.ci.referenceTitle}}
      • Status = New
      • QueueID = your maintenance queue

Send email notifications to multiple recipients​

Scenario: Iterate over an array of recipient addresses stored in a variable.

Steps:

  1. (Previous step stores an array of recipients as custom.recipients)
  2. Iterate Through Array: iterate over custom.recipients, value variable = recipient
    • Nested: Send Email
      • To = {{custom.recipient.address}}
      • Subject = Alert: {{email.subject}}
      • Body = {{email.body}}

Notes​

  • Access nested properties using dot notation: {{custom.item.id}}, {{custom.item.accountId}}, {{custom.item.referenceTitle}}
  • The iteration variable (e.g., custom.ticket) is only meaningful inside the nested actions. After the Iterate step completes, it holds the value from the last iteration pass.
  • Autotask API queries return a maximum of 500 results. For very large datasets, consider filtering your query more precisely.