Saltar para o conteúdo principal
O Iterador permite percorrer um array de registos e executar ações em cada um. É essencial para fluxos de trabalho que precisam de processar vários registos devolvidos por Pesquisar Registos ou recebidos via Webhooks.

​
Quando usar o Iterador

CenárioExemplo
Processar resultados da pesquisaEnviar e-mail a cada pessoa encontrada
Lidar com arrays de WebhooksCriar registos para cada item por ordem
Atualizações em massaAtualizar vários registos com valores calculados
NotificaçõesAlertar várias pessoas sobre um evento

​
Compreender o Iterador

O Iterador espera um array como entrada. Em seguida:
  1. Obtém o primeiro item do array
  2. Executa todas as ações dentro do Iterador com esse item
  3. Passa para o item seguinte
  4. Repete até que todos os itens sejam processados

​
Selecionar o array para iterar

A maioria das origens de arrays (Search Records, um campo de array de webhook, um gatilho manual em massa) pode ser selecionada diretamente no seletor de variáveis. Quando uma etapa de Code ou Logic Function retorna um array de nível superior, sua saída aparece no seletor de variáveis como entradas indexadas (0, 1, 2, …). Para iterar sobre o array como um todo, selecione a opção Whole list para essa etapa — o Iterator então deduz automaticamente o formato de cada item a partir da lista.

​
Configuração básica

​
Exemplo: Enviar e-mail a todos nos resultados da pesquisa

Objetivo: Encontrar todos os contactos numa empresa específica e enviar a cada um um e-mail personalizado.

​
Etapa 1: Pesquisar registos

  1. Adicione a ação Pesquisar Registos
  2. Objeto: Pessoas
  3. Filtro: Empresa igual a “Acme Inc”
  4. Isto devolve um array de pessoas

​
Etapa 2: Verificar se existem resultados

  1. Adicione a ação Filtro
  2. Condição: {{searchRecords.length}} é maior do que 0
  3. Isto evita erros do Iterador em resultados vazios

​
Etapa 3: Adicionar um Iterador

  1. Adicione a ação Iterador
  2. Entrada do array: selecione {{searchRecords}}
  3. Isto cria um ciclo

​
Etapa 4: Adicionar ações dentro do Iterador

As ações colocadas após o Iterador são executadas para cada item:
  1. Adicione a ação Enviar e-mail (dentro do Iterador)
  2. Para: {{iterator.currentItem.email}}
  3. Assunto: Olá {{iterator.currentItem.firstName}}!
  4. Corpo: Mensagem personalizada utilizando os campos do item atual

​
Resultado

Se Pesquisar Registos devolver 5 pessoas, o Iterador:
  • Envia e-mail para a pessoa 1
  • Envia e-mail para a pessoa 2
  • … continua para todas as 5

​
Aceder aos dados do item atual

Dentro do Iterador, use {{iterator.currentItem}} para aceder ao registo atual:
VariávelDescrição
{{iterator.currentItem}}Todo o objeto do registo atual
{{iterator.currentItem.id}}ID do registo
{{iterator.currentItem.email}}Campo de e-mail
{{iterator.currentItem.company.name}}Nome da empresa relacionada
{{iterator.index}}Posição atual no array (base 0)
No seletor de variáveis, você pode detalhar um campo específico do item atual ou escolher Use the whole item para fazer referência ao item atual inteiro ({{iterator.currentItem}}). Selecionar o item inteiro é útil quando você quer passar um registro completo diretamente para uma etapa subsequente, em vez de reconstruí-lo campo por campo.

​
Padrões comuns

​
Atualizar vários registos

Objetivo: Marcar todas as tarefas em atraso como “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

​
Criar registos a partir de um array

Objetivo: O Webhook recebe um pedido com vários itens, criar um registo para cada um 
1. Webhook Trigger (receives items array)
2. Filter (items.length > 0)
3. Iterator (trigger.body.items)
   └── Create Record
       - Object: Order Items
       - Name: {{iterator.currentItem.name}}
       - Quantity: {{iterator.currentItem.qty}}
       - Related Order: {{trigger.body.orderId}}

​
Processamento condicional dentro do ciclo

Objetivo: Enviar e-mail apenas para contactos com e-mails válidos 
1. Search Records (People)
2. Iterator (searchRecords)
   └── Filter (currentItem.email is not empty)
       └── Send Email
           - To: {{iterator.currentItem.email}}

​
Resolução de Problemas

​
”O Iterador espera um array”

Causa: Passou um único registo em vez de um array. Correção: Certifique-se de que está a passar o resultado de Pesquisar Registos ou um campo do tipo array, e não um único registo. 
✅ Correct: {{searchRecords}}
❌ Wrong: {{searchRecords[0]}}

​
O Iterador não é executado

Causa: O array está vazio. Correção: Adicione um Filtro antes do Iterador para verificar o tamanho do array: 
Filter: {{searchRecords.length}} > 0

​
Ações executadas vezes demais

Causa: Pesquisar Registos devolveu mais registos do que o esperado. Correção:
  • Adicione filtros mais específicos a Pesquisar Registos
  • Defina um limite em Pesquisar Registos (máx. 200)
  • Adicione um Filtro dentro do Iterador para condições adicionais

​
Considerações de desempenho

  • Utilização de créditos: Cada iteração consome créditos pelas suas ações
  • Tempo: Arrays grandes demoram mais a processar
  • Limites: Considere agrupar em lotes operações muito grandes
  • Limites de taxa: Chamadas a APIs externas podem atingir limites de taxa com muitas iterações

​
Melhores Práticas

  1. Verifique sempre o tamanho do array antes do Iterador para evitar erros
  2. Adicione filtros dentro dos ciclos quando nem todos os itens precisam de processamento
  3. Renomeie a etapa do seu Iterador para descrever o que está a percorrer
  4. Teste com arrays pequenos antes de processar conjuntos de dados grandes
  5. Monitorize as execuções dos fluxos de trabalho para garantir que as iterações se concluam conforme o esperado

​
Relacionados