ForEach

O módulo ForEach executa uma sequência de módulos uma vez para cada item de uma lista (por exemplo, uma lista de contatos ou o resultado de uma consulta). É útil sempre que você precisa repetir a mesma ação várias vezes, uma para cada item, sem duplicar módulos manualmente no fluxo.

Diferente dos demais módulos, o ForEach é um contêiner: ele aparece no diagrama como uma área que pode ser redimensionada, e você posiciona os módulos que devem se repetir dentro dele.

🧭 Como acessar

No menu lateral, clique em Gerenciamento de aplicativos.
Em seguida, clique em Fluxos.
Abra ou crie um fluxo e acesse a área de trabalho do fluxo.
No painel de módulos, localize a categoria Controle de fluxo (identificada pela cor ciano).
Arraste o módulo ForEach para a área de trabalho do fluxo.
Arraste os módulos que devem se repetir para dentro da área do ForEach.

🔍 Conhecendo o módulo

Ao clicar no módulo (fora da área dos módulos internos), um painel de configuração é aberto na lateral da tela.

📋 Fonte de dados

No campo Fonte de dados, informe a variável do fluxo que contém a lista de itens a processar (ex.: {{input.contatos}}). O valor precisa ser uma lista — se a variável não for uma lista, o ForEach não consegue processar e segue pela saída de erro.

🔢 Limite de iterações (opcional)

Defina o número máximo de itens que serão processados. Se deixar em branco, o módulo processa até 1.000 itens da lista.

⚙️ Modo de execução

Sequencial — processa um item de cada vez, na ordem da lista.
Paralelo — processa vários itens ao mesmo tempo.

Quando o modo Paralelo é escolhido, aparece o campo Tamanho do lote, para definir quantos itens processar simultaneamente.

Atualmente, mesmo informando um valor no campo Tamanho do lote, o processamento paralelo agrupa os itens em lotes de até 10 por vez.

⚠️ Tratamento de erro

Parar — se algum item falhar durante o processamento, o ForEach interrompe e segue pela saída de erro do módulo.
Continuar — o ForEach processa todos os itens possíveis, mesmo que alguns falhem, e segue pela saída de sucesso com o resultado de cada item (indicando quais tiveram sucesso e quais falharam).

🔀 Portas do módulo

O ForEach tem portas de dois tipos:

Início — conecta ao primeiro módulo dentro do contêiner; é por onde cada iteração começa.
Sucesso da iteração / Erro da iteração — dentro do contêiner, você precisa conectar a saída do último módulo daquela sequência interna de volta a uma dessas duas entradas do ForEach, para indicar que aquela iteração terminou.
Sucesso / Erro (fora do contêiner) — disparam apenas depois que todos os itens da lista já foram processados.

Apenas o primeiro módulo conectado à porta Início recebe diretamente os dados do item atual ({{input.item}}) e sua posição na lista ({{input.index}}). Se você tiver mais de um módulo em sequência dentro do ForEach, os módulos seguintes só recebem o que o módulo anterior repassar.

💡 Caso de uso

Cenário: uma empresa tem uma lista de contatos que precisa receber uma mensagem personalizada de aniversário, gerada a partir de uma consulta a um banco de dados.

Configuração:

Adicione um módulo de consulta ao banco de dados, que retorna uma lista de contatos aniversariantes.
Adicione o módulo ForEach logo em seguida, com Fonte de dados apontando para essa lista.
Dentro do ForEach, adicione um módulo de envio de mensagem, usando {{input.item.nome}} e {{input.item.telefone}}.
Conecte a saída desse módulo de envio à porta Sucesso da iteração do ForEach.
Conecte a saída Sucesso (externa) do ForEach à continuação do fluxo.

Resultado: cada contato da lista recebe automaticamente sua própria mensagem de aniversário personalizada.

📌 Dicas úteis

Use o modo Sequencial quando a ordem de processamento importa; use Paralelo para acelerar o processamento de listas grandes quando a ordem não é importante.
Sempre conecte a saída interna do último módulo à porta Sucesso da iteração (ou Erro da iteração), para que o ForEach saiba quando cada item terminou.
Se precisar processar mais de 1.000 itens, será necessário dividir a lista em partes antes de usar o ForEach.
Use Continuar no tratamento de erro quando quiser processar o máximo de itens possível, mesmo que alguns falhem.

📝 Resumo

O módulo ForEach repete uma sequência de módulos para cada item de uma lista.
É um contêiner: os módulos que devem se repetir ficam posicionados dentro dele no diagrama.
Processa até 1.000 itens por padrão, nos modos Sequencial ou Paralelo.
Só o primeiro módulo dentro do ForEach recebe diretamente os dados do item ({{input.item}}) e sua posição ({{input.index}}).
As saídas Sucesso e Erro externas só disparam depois que todos os itens forem processados.