ForEach

1. Visão Geral

O componente ForEach (foreach) repete a execução de um conjunto de passos para cada item de uma lista, de forma parecida com um laço de repetição em linguagens de programação. É usado quando o fluxo recebe uma lista (por exemplo, itens de um pedido, linhas de uma planilha, registros de uma API) e precisa executar a mesma sequência de ações para cada um deles.

Use quando precisar processar item por item de uma coleção. Não é indicado para decisões condicionais simples (use o Choice) nem para ler arquivos Excel diretamente (o componente Excel Reader já faz a iteração linha a linha sozinho, sem precisar de um ForEach por fora).

2. Pré-requisitos

Não há credenciais ou acessos externos necessários — é um componente interno da engine.

3. Autenticação e Conexão

Não aplicável.

4. Configuração / Operações Suportadas

O ForEach tem uma única operação: iterar sobre uma lista e executar um sub-fluxo para cada item.

Campo	Obrigatório	Tipo	Descrição	Exemplo
items	Sim	Expressão	Caminho/expressão que resolve para a lista a ser percorrida. Se o resultado não for uma lista (JSON array), o componente trata o valor como um único item.	Uma expressão que aponta para a lista de itens do pedido
step	Sim	Sub-fluxo	Sequência de componentes executada para cada item da lista.	Um passo que envia cada item para um sistema externo
isParallel	Não	Texto ("true"/"false")	Se true, os itens são processados em paralelo; se false (padrão), um item de cada vez, em ordem.	"true"
stopOnError	Não	Texto ("true"/"false")	Se true (padrão), um erro em qualquer item interrompe todo o processamento. Se false, o erro daquele item é registrado e o laço continua com os próximos.	"false"
isAggregatedResult	Não	Texto ("true"/"false")	Se true, o resultado final traz o corpo de resposta de cada item processado. Se false (padrão), o resultado traz apenas contadores (total, sucesso, erro).	"true"

Comportamento em caso de erro: se stopOnError estiver ativado e um item falhar, o processamento inteiro é interrompido com erro. Se estiver desativado, o item com erro é marcado como falho no resultado, mas os demais continuam sendo processados normalmente.

5. Exemplos Práticos

Exemplo simples: um fluxo recebe uma lista de e-mails e usa o ForEach para enviar uma notificação para cada um, um de cada vez (isParallel desligado), parando tudo se um envio falhar (stopOnError ligado, comportamento padrão).

Entrada:

{
  "emails": ["ana@exemplo.com", "bruno@exemplo.com", "carla@exemplo.com"]
}

Configuração do componente:

{
  "componentName": "foreach",
  "configurations": {
    "items": "{$.body.emails}",
    "step": {
      "componentName": "http",
      "configurations": { "url": "https://api.exemplo.com/notificar", "method": "POST" }
    }
  }
}

Resposta (contadores, comportamento padrão de isAggregatedResult):

{
  "itemsSize": 3,
  "success": 3,
  "error": 0
}

Exemplo avançado: o mesmo cenário, mas processando os envios em paralelo (isParallel ligado) para ganhar velocidade, sem parar o processo se algum e-mail específico falhar (stopOnError desligado), e trazendo o resultado detalhado de cada envio no final (isAggregatedResult ligado) para permitir uma auditoria posterior de quais itens tiveram sucesso ou erro.

Configuração do componente:

{
  "componentName": "foreach",
  "configurations": {
    "items": "{$.body.emails}",
    "isParallel": "true",
    "stopOnError": "false",
    "isAggregatedResult": "true",
    "step": {
      "componentName": "http",
      "configurations": { "url": "https://api.exemplo.com/notificar", "method": "POST" }
    }
  }
}

Resposta (um item, o e-mail do Bruno, falhou mas o processamento continuou):

{
  "items": [
    { "body": "{\"status\":\"enviado\"}" },
    { "body": "{\"error\":\"Falha ao conectar com o servidor de e-mail\"}" },
    { "body": "{\"status\":\"enviado\"}" }
  ]
}

6. Erros Comuns e Troubleshooting

Erro / Sintoma	Causa provável	Como resolver
Fluxo interrompido no meio do processamento de uma lista	stopOnError está ativado (padrão) e um dos itens gerou erro.	Se o objetivo é continuar mesmo com falhas pontuais, desativar stopOnError.
Resultado final não mostra detalhes dos itens processados	isAggregatedResult está desligado (padrão), trazendo apenas contadores.	Ativar isAggregatedResult para receber o corpo de resposta de cada item.
ForEach processa a lista inteira como um único item	A expressão de items não resolveu para uma lista JSON válida.	Verificar se a expressão aponta corretamente para um array na mensagem de entrada.