Usar iterador

Percorra arrays de registros para executar ações em cada item.

O Iterador permite percorrer um array de registros e executar ações em cada um. É essencial para fluxos de trabalho que precisam processar vários registros devolvidos por Pesquisar registros ou recebidos via webhooks.

Quando usar o Iterador

Entender 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.

Configuração básica

Exemplo: enviar e-mail a todos nos resultados da pesquisa

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

Etapa 1: pesquisar registros

1. Adicione a ação Pesquisar registros.
2. Objeto: Pessoas.
3. Filtro: Empresa igual a “Comércio Andrade”.
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 registros devolver 5 pessoas, o Iterador:

• Envia e-mail para a pessoa 1.
• Envia e-mail para a pessoa 2.
• … continua para todas as 5.

Acessar os dados do item atual

Dentro do Iterador, use {{iterator.currentItem}} para acessar o registro atual:

Padrões comuns

Atualizar vários registros

Objetivo: marcar todas as tarefas em atraso como “Atrasada”.

1. Pesquisar registros (Tarefas, Data de vencimento < Hoje, Status ≠ Concluída)
2. Filtro (length > 0)
3. Iterador (searchRecords)
   └── Atualizar registro
       - Objeto: Tarefas
       - Registro: {{iterator.currentItem.id}}
       - Status: Atrasada

Criar registros a partir de um array

Objetivo: o webhook recebe um pedido com vários itens; criar um registro para cada um.

1. Gatilho de Webhook (recebe array de itens)
2. Filtro (items.length > 0)
3. Iterador (trigger.body.items)
   └── Criar registro
       - Objeto: Itens do Pedido
       - Nome: {{iterator.currentItem.name}}
       - Quantidade: {{iterator.currentItem.qty}}
       - Pedido relacionado: {{trigger.body.orderId}}

Processamento condicional dentro do ciclo

Objetivo: enviar e-mail apenas para contatos com e-mails válidos.

1. Pesquisar registros (Pessoas)
2. Iterador (searchRecords)
   └── Filtro (currentItem.email não está vazio)
       └── Enviar e-mail
           - Para: {{iterator.currentItem.email}}

Resolução de problemas

”O Iterador espera um array”

Causa: passou um único registro em vez de um array.

Correção: certifique-se de que está passando o resultado de Pesquisar registros ou um campo do tipo array, e não um único registro.

✅ Correto: {{searchRecords}}
❌ Errado: {{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:

Filtro: {{searchRecords.length}} > 0

Ações executadas vezes demais

Causa: Pesquisar registros devolveu mais registros do que o esperado.

Correção:

• Adicione filtros mais específicos a Pesquisar registros.
• Defina um limite em Pesquisar registros (máx. 200).
• Adicione um Filtro dentro do Iterador para condições adicionais.

Considerações de desempenho

• 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. Monitore as execuções dos fluxos de trabalho para garantir que as iterações se concluam conforme o esperado.

Relacionados

• Ações de fluxo de trabalho
• Como usar ramificações
• Perguntas frequentes sobre fluxos de trabalho