IMPORTANTE: esta documentação foi descontinuada. Leia a documentação For Each atualizada no nosso novo portal de documentação.
O For Each realiza um loop dentro de uma estrutura JSON, processando cada elemento do array em um subpipeline.
Dê uma olhada nos parâmetros de configuração do componente:
JSON Path Expression: expressão que é aplicada à estrutura JSON recebida pelo componente For Each, filtrando-a. O For Each pode receber um objeto que possua vários elementos e a expressão JSON Path permite obter apenas aqueles que atenderem a uma condição específica.
Element Identifier: elemento único que identifica a linha em processamento (ex.: elemento "id").
Parallel Execution: quando habilitada, a opção faz com que elementos do array recebido pelo For Each sejam processados em paralelo, com um limite de até 10 execuções concorrentes - ou seja, caso o array recebido pelo componente For Each tenha 20 elementos, os 10 primeiros terão seu processamento iniciado imediatamente. Assim que um desses processamentos terminar, o próximo elemento do array será processado e assim por diante, até que todo o array tenha sido processado. Caso a opção Parallel Execution esteja desabilitada, os elementos do array recebido pelo For Each são processados em série - é preciso que o primeiro tenha sido processado para que o processamento do segundo elemento possa começar.
Fail On Error: a habilitação desse parâmetro suspende a execução do pipeline apenas quando há uma ocorrência grave na estrutura da iteração, impedindo a sua conclusão por completo. A ativação do parâmetro "Fail On Error" não tem ligação com erros ocorridos nos componentes utilizados para a construção dos subpipelines (onProcess e onException). Se você quiser que a execução seja interrompida para qualquer tipo de ocorrência de erro, avalie a utilização do componente Do While. Clique aqui para ler sobre esse componente e validar se ele se aplica ao seu cenário.
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 um array products que está dentro do body da mensagem recebida.
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.
IMPORTANTE: caso sejam utilizados componentes Session 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 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 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:
Clique aqui para entender melhor o funcionamento dos subpipelines.
Cenários de utilização do componente For Each com tratamento de erros
Propriedade "Fail on Error" habilitada e nenhum subpipeline definido em onException
o pipeline será interrompido imediatamente
um erro será emitido a partir do componente For Each
nenhum outro componente será invocado após o For Each
Propriedade "Fail on Error" habilitada e um subpipeline definido em onException
o pipeline será interrompido imediatamente
o subpipeline definido em onException será executado e a saída dele alimentará o próximo componente após o For Each
o componente após o For Each será invocado
Propriedade "Fail on Error" desabilitada e nenhum subpipeline definido em onException
a iteração onde ocorreu o erro será interrompida
uma mensagem de erro padrão será informada na entrada da próxima iteração e o loop continuará a ser executado normalmente
Propriedade "Fail on Error" desabilitada e um subpipeline definido em onException
a iteração onde ocorreu o erro será interrompida
o subpipeline definido em onException será executado e a saída dele alimentará a próxima iteração
o loop continuará a ser executado normalmente
Erro 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
O For Each aceita qualquer estrutura de JSON que contenha um array. Se o array não for a raiz do objeto, então uma expressão JSON Path deve ser definida para localizar e filtrar o array. Caso o componente For Each não receba um array, nenhum processamento será executado.
Saída
{
"total": 0,
"success": 0,
"failed": 0
}
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
IMPORTANTE: 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.