> For the complete documentation index, see [llms.txt](https://help.hyperflow.global/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.hyperflow.global/docs/builder-hyperflow/gerenciamento-de-aplicativos/fluxos/controle-de-fluxo/foreach.md). # ForEach ## 🔁 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. **📷 Inserir print:** visão geral do módulo ForEach na área de trabalho do fluxo, mostrando a área do contêiner *** ### 🧭 Como acessar 1. No menu lateral, clique em **Gerenciamento de aplicativos**. 2. Em seguida, clique em **Fluxos**. 3. Abra ou crie um fluxo e acesse a área de trabalho do fluxo. 4. No painel de módulos, localize a categoria **Controle de fluxo** (identificada pela cor ciano). 5. Arraste o módulo **ForEach** para a área de trabalho do fluxo. 6. Arraste os módulos que devem se repetir para **dentro** da área do ForEach. **📷 Inserir print:** painel de módulos com a categoria Controle de fluxo expandida e o módulo ForEach visível *** ### 🔍 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. **📷 Inserir print:** painel de configuração do módulo ForEach aberto *** #### 📋 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. **📷 Inserir print:** campo Fonte de dados preenchido com uma variável de lista *** #### 🔢 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. **📷 Inserir print:** campo Limite de iterações preenchido com um valor de exemplo (ex.: 50) *** #### ⚙️ 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. {% hint style="info" %} Atualmente, mesmo informando um valor no campo **Tamanho do lote**, o processamento paralelo agrupa os itens em lotes de até 10 por vez. {% endhint %} **📷 Inserir print:** campo Modo de execução com o modo Paralelo selecionado, mostrando o campo Tamanho do lote *** #### ⚠️ 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). **📷 Inserir print:** campo Tratamento de erro com as opções Parar e Continuar *** #### 🔀 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. {% hint style="warning" %} 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. {% endhint %} **📷 Inserir print:** módulo ForEach com módulos internos conectados até a porta "Sucesso da iteração" *** ### 💡 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:** 1. Adicione um módulo de consulta ao banco de dados, que retorna uma lista de contatos aniversariantes. 2. Adicione o módulo **ForEach** logo em seguida, com **Fonte de dados** apontando para essa lista. 3. Dentro do ForEach, adicione um módulo de envio de mensagem, usando `{{input.item.nome}}` e `{{input.item.telefone}}`. 4. Conecte a saída desse módulo de envio à porta **Sucesso da iteração** do ForEach. 5. 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.