# For Each **For Each** cria um loop dentro de uma estrutura JSON, processando cada elemento da matriz em um subpipeline. A expressão configurada deve retornar uma matriz. Caso contrário, o loop For Each não será executado. [Saiba mais sobre as aplicações práticas do For Each](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/logic/for-each/for-each-example-of-use). ## Parâmetros Configure o conector usando os parâmetros abaixo. Os campos que suportam expressões Double Braces estão marcados na coluna **Suporta DB**. | **Parâmetro** | **Descrição** | **Tipo** | **Suporta DB** | **Padrão** | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------- | ---------- | | **Alias** | Nome (alias) para a saída deste conector, permitindo que você faça referência a ele posteriormente no fluxo usando expressões Double Braces. | String | ✅ | for-each-1 | | **Expression** | A expressão usada para filtrar e recuperar a estrutura JSON para iteração. Suporta expressões **Double Braces** e expressões **JSON Path**. | String | ✅ | $ | | **Element Identifier** | Elemento único que identifica a linha em processamento (por exemplo, elemento "id"). | String | ❌ | N/A | | **Parallel Execution** | Se ativado, este parâmetro processa até 10 elementos da matriz simultaneamente. À medida que cada execução é concluída, a próxima começa automaticamente até a conclusão. Se desativado, o processamento é serial, exigindo que cada elemento seja concluído antes do início do próximo. | Booleano | ❌ | *False* | | **Advanced** | Habilita opções avançadas. | Boolean | ❌ | False | | **Max Number Length** | Comprimento máximo permitido para valores numéricos em JSON. Se não for especificado, o limite padrão definido pelo Jackson (1000) será aplicado. | Integer | ✅ | N/A | | **Fail On Error** | Quando ativado, este parâmetro suspende o pipeline apenas se ocorrer um erro crítico dentro da estrutura de iteração, impedindo sua conclusão. Ele não é acionado para erros dentro dos subpipelines **onProcess** ou **onException**. Para interrupções baseadas em qualquer ocorrência, use o conector **Do While**. | Booleano | ❌ | *False* | ## Opções de sintaxe Cada conector permite dois métodos para definir a matriz de entrada: * **Expressões JSON Path**: o caminho tradicional (por exemplo: `$.body.items`). * **Expressões Double Braces:** permitem usar referências diretas de etapas anteriores ou funções integradas. ### **Exemplos de Expressões JSON Path** ``` $.[?(@.status == 'EXPIRED')] ``` A expressão acima mostra como a mensagem recebida pelo componente pode ser filtrada: neste exemplo, o *array* é a raiz do objeto e somente os elementos cujo atributo status seja EXPIRED serão processados pelo componente **For Each**. ``` $.body.* ``` Obtém todo o conteúdo do *body* da mensagem recebida. ``` $.body.products.* ``` Obtém o conteúdo de uma matriz de produtos que está dentro do corpo da mensagem recebida. Recomendamos que as expressões usadas no parâmetro Expressão JSON Path sejam validadas usando a seguinte referência: [https://jsonpath.com/ ](https://jsonpath.com/) ### Exemplos de Double Braces O conector **For Each** suporta todas as funções de **Double Braces** existentes que retornam valores de array para iteração de arrays. ``` {{step.stepName.response.array}} ``` A expressão acima representa uma referência ou um array proveniente de um componente específico. Você pode usar `step.stepName` no formulário de configuração do **For Each**. #### Acessando o elemento da iteração atual Ao usar o conector **For Each** na Digibee Integration Platform, cada iteração processa um elemento do array de entrada. Durante a execução, os conectores dentro da iteração podem sobrescrever o payload. Quando isso acontece, o elemento original que está sendo processado pode deixar de estar acessível usando `{{$.}}`. Para garantir acesso consistente ao elemento atual, a plataforma fornece uma referência reservada: ``` {{iterators..current}} ``` **Exemplo** Se o alias do seu **For Each** for `for-each-1`, você pode acessar o elemento atual usando: Essa referência permanece disponível durante toda a iteração, mesmo que outros conectores retornem novos payloads. ## Definindo o subpipeline que é executado a cada iteração Para definir o *subpipeline* que será executado a cada iteração, basta clicar no ícone **onProcess** do componente **For Each.** ![](https://3268428548-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSKBJ6ZiEWBU93x170HH4%2Fuploads%2FUY2lREfzZOZBkI7AWSNA%2Funknown.png?alt=media\&token=22f915a5-cd0d-425a-8caf-2401bb0546fa) Ao clicar nesse ícone, um *subpipeline* será criado (ou exibido, caso já exista). Então basta construir o fluxo desejado conforme a necessidade de execução de cada iteração. {% hint style="info" %} Caso sejam utilizados componentes [**Session Management**](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/structured-data/session-management) para manipular dados de cada elemento do *array* no *subpipeline* do **For Each** e a opção **Parallel Execution** esteja ativa, é necessário que a opção **Scoped** do **Session Management** esteja ativa para que cada execução em paralelo acesse os seus respectivos dados. {% endhint %} ## Tratando erros no loop O comportamento padrão do **For Each** é interromper a execução caso algum erro seja encontrado. Erros são situações atípicas na execução de um *pipeline* que incorrem em uma parada. Por exemplo, o uso de um componente [**Assert V2** ](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/tools/assert-v2)causa um erro no *pipeline* quando a condição de asserção não for satisfeita. Outras situações de erro ocorrem quando são utilizados componentes com a configuração **Fail On Error** habilitada. Conforme explicado anteriormente, é possível definir um *subpipeline* para tratamento de erros. A definição desse *subpipeline* é feita através do ícone **onException** do componente **For Each**: ![](https://3268428548-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSKBJ6ZiEWBU93x170HH4%2Fuploads%2FcvzhQQ9YrJBWftKZTi1O%2Funknown.png?alt=media\&token=073e460f-3448-4600-b021-2db62710401e) [ Leia o artigo sobre subpipelines para entender melhor o funcionamento](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/build-overview/pipelines/subpipelines). {% hint style="warning" %} Não é possível interromper a execução de todo o loop **For Each**. A interrupção pode ser feita apenas na iteração atual, através de componentes que possuam o parâmetro **Fail On Error** ativado dentro dos *subpipelines* *onProcess* e *onException*. {% endhint %} ## Erro grave de estrutura durante o *subpipeline* onException * o *loop* será interrompido; * o erro será lançado para o próximo componente ao qual o componente For Each esteja associado; * caso o **For Each** esteja no fluxo principal do *pipeline*, então o *pipeline* será interrompido; * se o **For Each** estiver dentro de um componente que possui *subpipeline*, então o *subpipeline onException* será invocado e o erro será informado na entrada desse *subpipeline*. ### Fluxo de mensagens #### Entrada For Each aceita qualquer estrutura JSON que contenha uma matriz. Essa matriz pode ser localizada por meio do JSON Path ou injetada por meio de chaves duplas. Se a expressão (independentemente da sintaxe escolhida) não retornar uma matriz válida, nenhuma iteração será realizada. #### Saída * **total:** número total de elementos processados. * **success:** número total de elementos processados com sucesso. * **failed:** número total de elementos que não puderam ser processados. {% hint style="info" %} Para informar que uma linha foi processada corretamente e iterar o valor do campo `"success"`, cada execução do *subpipeline* *onProcess* deve responder com `{ "success": true }` ao seu término. Somente desta forma a mensagem de saída representará corretamente o resultado dos processamentos. {% endhint %}