For Each

Saiba mais sobre o conector For Each e como utilizá-lo na Plataforma de Integração Digibee.

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.

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/

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.<for-each-alias>.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.

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.

Caso sejam utilizados componentes 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.

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 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:

Leia o artigo sobre subpipelines para entender melhor o funcionamento.

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.

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.

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.