Marcadores de várias instâncias

Visão geral

Use marcadores para configurar uma tarefa para ser executada uma vez para cada elemento em uma variável da Lista, criando várias execuções sequenciais ou paralelas. Acesse Marcadores no capítulo BPMN Primer para obter notação e orientação conceitual.

Quando usar marcadores de várias instâncias

Use um marcador de várias instâncias quando você tiver uma lista de itens e precisar executar a mesma tarefa uma vez para cada um deles — por exemplo:

• Validar cada fatura em uma lista de IDs de faturas
• Enriquecimento de um conjunto de registros chamando uma API externa por registro
• Envio de uma notificação para cada destinatário em uma lista

Sem um marcador, você precisaria criar um loop manual usando fluxos de sequência, que são mais difíceis de ler e mais difíceis de rastrear.Um marcador de várias instâncias mantém seu diagrama de processo limpo e dá visibilidade por item na trilha de execução — a execução de cada item aparece separadamente, com seu próprio status e saída.

Use o modo Sequencial quando a ordem for importante ou quando cada execução depender da anterior. Use o modo Paralelo quando os itens forem independentes e você quiser taxa de transferência mais rápida.

Tipos de coleção compatíveis

O Maestro trata os seguintes tipos de coleção como repetíveis para a execução de várias instâncias. Se sua variável for um desses tipos, você pode usá-la diretamente no campo Itens :

• System.Collections.Generic.List<T>
• System.Collections.Generic.IList<T>
• System.Collections.Generic.IEnumerable<T>
• System.Collections.IEnumerable
• System.Data.DataTable
• Newtonsoft.Json.Linq.JArray
• Tipos em que collectionDataType começa com List
• Tipos em que collectionDataType começa com Array
• Matrizes .NET primitivas, como int[], string[], bool[], double[], decimal[], long[]

Mantenha o trabalho por item idempotente e de curta duração. Use as seções Saídas e Atualizar variáveis se você precisar coletar resultados em uma única variável após todas as iterações finalizarem.

Para adicionar um marcador de várias instâncias

Importante:

Configure a Ação da tarefa antes de convertê-la para várias instâncias. A configuração de várias instâncias vincula-se às Saídas da tarefa no momento em que você aplica o marcador. Se nenhuma ação for selecionada nesse ponto, a associação será vinculada ao espaço reservado de saída padrão da tarefa em vez da saída real da ação — e selecionar uma ação posteriormente não atualizará essa associação. Cada iteração grava em uma saída não associada, produzindo entradas null na variável agregada no runtime. Se você já converteu a tarefa para várias instâncias primeiro, consulte A variável agregada contém nulos para a solução alternativa remover e reaplicar.

1. Selecione uma tarefa na tela e, no painel Propriedades, configure sua Ação. Confirme se a seção Saídas reflete a ação que você selecionou — por exemplo, uma ação de agente expõe uma saída response digitada e uma saída Error . Continue apenas após a seção Saídas corresponder à ação.

2. Na barra de ferramentas do elemento acima da tarefa, selecione Alterar elemento.

   

3. Escolha Instância múltipla sequencial ou Instância múltipla paralela.

   O marcador aparece na parte inferior do formato da tarefa.

   

4. No Painel de propriedades, expanda Múltiplas instâncias.

   

5. Em Itens, selecione a variável da lista sobre a qual você deseja iterar — por exemplo, vars.invoiceList.

   Isso informa ao Maestro qual coleção processar. Sem um valor de itens, a tarefa é executada uma vez como tarefa normal, não uma vez por elemento. O Maestro cria uma execução por elemento na lista.

6. Opcionalmente, expanda o Tratamento de erro e habilite Tentar novamente em caso de falha para tentar novamente execuções de itens individuais de forma independente.Para obter opções de configuração, consulte NovasTentativas no nível de elemento.

Observação:

A multi-instância é compatível apenas para tarefas. O tipo de marcador que você seleciona (sequencial ou paralelo) determina a ordem de execução.

Referência ao item atual

A seção Múltiplas instâncias precisa apenas da lista de itens — é onde você informa ao Maestro sobre qual coleção iterar.As expressões do iterador vão para um lugar diferente: a seção Entradas da tarefa, onde você mapeia o item atual vai para uma entrada específica para cada execução.

A expressão que você usa depende de o marcador ser aplicado diretamente à tarefa ou se a tarefa é executada dentro de um subprocesso chamado a partir de uma tarefa de várias instâncias.

Cenário	Expression	Onde usá-lo
Marcador aplicado diretamente à tarefa	iterator.item	Nos campos de Entradas da tarefa
A tarefa é executada dentro de um subprocesso chamado a partir de uma tarefa de várias instâncias	iterator[0].item	Nos campos de Entradas da tarefa do subprocesso

Observação:

O [0] em iterator[0].item refere-se ao escopo do iterador mais externo quando uma tarefa é executada dentro de um subprocesso.Na multi-instância de nível único padrão, você sempre usará [0] — não há iterator[1].

Para passar todo o elemento atual, use iterator.item. Para passar uma Propriedade única, use iterator.item.propertyName. Alguns exemplos:

• iterator.item.invoiceId
• iterator.item.customer.email
• { id: iterator.item.id, flags: ["recheck"] }

Referenciar o item atual em uma tarefa

Quando você aplica o marcador de várias instâncias diretamente a uma tarefa, use iterator.item na seção Entradas do painel de propriedades para passar o elemento atual para cada execução.

Referência do painel de propriedades

• Ação: escolha como a tarefa é executada — ação do Integration Service, ação do agente ou Nenhum apenas para modelagem.

• Entradas: mostra os parâmetros definidos pela ação selecionada.Para cada parâmetro que você deseja preencher com o item de lista atual, defina seu valor como iterator.item (para passar todo o elemento) ou iterator.item.propertyName (para passar uma propriedade específica).

  

• Saídas: define o que cada iteração retorna. Quando uma ação é configurada na tarefa, as saídas da ação (normalmente response, mais Error para ações do agente) aparecem aqui automaticamente, cada uma associada à sua origem por meio do chip Valor . Para adicionar um valor extra por iteração no alto das saídas da ação, selecione + Adicionar novo e dê um nome a ele. Se as entradas listadas aqui não refletirem o que sua ação expõe — por exemplo, o chip Valor mostra um tipo de espaço reservado genérico em vez do tipo de saída real da ação — consulte A variável agregada contém nulos.

• Atualizar variáveis: especifica qual variável de processo armazena as saídas agregadas após a conclusão de todas as iterações. Selecione Definir valor da variável e escolha a variável de destino — por exemplo, vars.validationResults. A variável contém uma matriz com uma entrada por iteração: uma matriz de strings se cada iteração retornar uma string, uma matriz de objetos se cada iteração retornar um objeto. No modo Sequencial, as entradas seguem a ordem de entrada. No modo Paralelo, a ordem corresponde à conclusão da iteração e não é garantida.

Faça referência ao item atual dentro de um subprocesso

Quando uma tarefa é executada dentro de um subprocesso que foi chamado a partir de uma tarefa de várias instâncias, o item atual não está diretamente disponível como iterator.item. Em vez disso, use iterator[0].item nas Entradas da tarefa de subprocesso para acessar o elemento transferido da tarefa de várias instâncias pai.

Referência do painel de propriedades

• Ação: configure como a tarefa interage com o sistema externo, API ou agente.

• Entradas: adicione uma entrada para cada valor de que a tarefa precisa.Defina o valor para iterator[0].item para transferir todo o elemento atual ou iterator[0].item.propertyName para transferir uma propriedade específica.

  Exemplo — se sua lista contiver objetos com um campo id, adicione uma entrada na seção Entradas do painel Propriedades:

  • Nome do campo de entrada: currentItemId
  • Valor: iterator[0].item.id

  Substituir .id pelo nome real da propriedade de seus objetos de lista.

Exemplos

Exemplo: validar uma lista de faturas

Este exemplo mostra como configurar uma Tarefa de serviço para ser executada uma vez por fatura em uma lista.

1. Prepare uma variável de lista

1. Abra o Gerenciador de dados.
2. Criar uma variável:
   • Nome: invoiceList
   • Tipo: Array de objetos ou Array de strings
   • Valor padrão: ["INV-001", "INV-002", "INV-003"]

2. Adicione uma tarefa de serviço e configure a ação

1. Adicione uma Tarefa de serviço à tela e nomeie-a como Validar fatura.

2. Com a tarefa selecionada, abra a seção Ação no painel Propriedades e configure qual agente é executado para cada fatura:

   • Ação: Selecione Iniciar e aguardar o agente.
   • Agente: selecione o agente responsável por validar faturas. O agente já deve existir em seu tenant — você pode criar um no Agent Builder.

   

3. Confirme que a seção Saídas reflete a ação do agente — a saída response deve aparecer com seu tipo de saída real, ao lado de Error. Continuar apenas após essa correspondência.

3. Converta a tarefa para várias instâncias

1. Com a tarefa selecionada, abra a barra de ferramentas do elemento e selecione Alterar elemento → Múltiplas instâncias sequenciais.
2. No Painel de propriedades, expanda Múltiplas instâncias e defina Itens vars.invoiceList.

4. Mapeie o item atual para uma entrada

Após selecionar sua ação, a seção Entradas mostra os parâmetros definidos por essa ação — por exemplo, os argumentos de entrada de seu fluxo de trabalho de RPA ou os parâmetros de seu agente.

Para cada parâmetro que você deseja preencher com o item da lista atual, selecione seu campo de valor e iterator.item:

• Use iterator.item para transferir todo o elemento atual — por exemplo, a string "INV-001" se sua lista contiver strings.
• Use iterator.item.propertyName para transferir uma propriedade específica — por exemplo, iterator.item.id se sua lista contiver objetos.

5. Depure o processo

1. Selecione Debug → Debug passo a passo.
2. O Maestro executa Validar fatura uma vez por item de lista.

Resultado: a trilha de execução mostra uma execução por fatura, cada uma rotulada com seu valor de item.

Para executar todos os itens simultaneamente em vez de sequencialmente, escolha Múltiplas instâncias paralelas na etapa 2. Consulte também o exemplo de distribuição abaixo.

Exemplo: distribuir e coletar resultados

Cenário: você recebe uma lista de IDs de faturas de uma API externa e precisa validar cada uma de forma independente e, em seguida, usa os resultados agregados em uma etapa subsequente.

1. Certifique-se de que uma variável de lista — por exemplo, vars.invoiceIds — seja preenchida por uma etapa anterior, como uma tarefa Serviço que chama uma API externa.

2. Adicione uma Tarefa de serviço chamada Validar fatura e, na tarefa regular, configure a Ação que valida uma única fatura. Confirme se a seção Saídas reflete a ação — a entrada response deve mostrar o tipo de saída real da ação.

3. Com a tarefa selecionada, escolha Alterar Elemento → Múltiplas instâncias paralelas.

4. Na seção Múltiplas instâncias , defina Itens como vars.invoiceIds.

5. Na seção Entradas , mapeie iterator.item para o parâmetro ID da fatura de sua ação — por exemplo, defina a entrada invoiceId como iterator.item.

6. Na seção Saídas , verifique se a saída response da ação está listada e associada ao resultado da ação. Se precisar de um valor agregado adicional por iteração, selecione + Adicionar novo e defina-o. Se as saídas listadas não corresponderem ao que sua ação expõe, o marcador foi aplicado antes que a ação fosse configurada; consulte A variável agregada contém nulos.

7. Na seção Atualizar variáveis , selecione Definir valor da variável e escolha a variável para armazenar os resultados agregados — por exemplo vars.validationResults Após a conclusão de todas as iterações, essa variável contém uma entrada por fatura — uma matriz de strings se sua ação retornar uma string ou uma matriz de objetos se ela retornar um objeto.

   

Comportamento dos runtimes

1. Fan-out / fan-in: o Maestro cria uma instância de atividade por item e finaliza o grupo quando todas as instâncias finalizarem.
2. Ordenação: garantido no modo Sequencial; não garantido no modo Paralelo.
3. Concorrência: o modo paralelo executa itens simultaneamente, sujeito aos limites da plataforma e disponibilidade de recursos.
4. Falhas: o resultado de cada item é independente. Defina a lógica subsequente para lidar com falhas parciais — por exemplo, continuar, tentar novamente ou parar com base em um limite.
5. Observabilidade: cada execução de item é rastreada individualmente na Trilha de execução, mostrando o status e os resultados por item.

Solução de problemas

A variável agregada contém nulos

A variável agregada produzida por Atualizar variáveis contém null para cada iteração (por exemplo, [null, null, null]), mesmo que cada iteração seja executada com sucesso.

Isso acontece quando a tarefa é convertida para várias instâncias antes que sua Ação seja selecionada. A configuração de várias instâncias é associada ao espaço reservado de saída padrão da tarefa em vez da saída real da ação, e selecionar uma ação posteriormente não atualiza essa vinculação. Cada iteração grava em uma saída não associada e o agregador null.

Para corrigir uma tarefa existente:

1. Na barra de ferramentas do elemento, selecione Alterar elemento e converta a tarefa de volta para uma tarefa regular.
2. Confirme que a ação esteja selecionada e se a seção Saídas reflete a ação (por exemplo, response pela ação, mais Error para ações do agente).
3. Converta a tarefa para multi-instância novamente com Alterar elemento → Múltiplas instâncias sequenciais ou Múltiplas instâncias paralelas.
4. Na seção Saídas , verifique se as entradas ainda correspondem às saídas da ação.

Para evitar que isso aconteça em novas tarefas, sempre configure a Ação antes de converter a tarefa para várias instâncias.

A entrada dos itens é ignorada e a tarefa é executada uma vez

A tarefa é executada uma única vez e o valor dos Itens é tratado como uma entrada regular.

Isso acontece quando a variável passada aos Itens não é um dos tipos de coleção compatíveis. Verifique o tipo da variável no Data Manager contra os tipos de coleção compatíveis. Se você definiu a lista como uma string simples, converta-a para Matriz de strings ou Matriz de objetos.

As entradas de saída não refletem as saídas da ação

A seção Saídas não mostra as entradas que você espera da ação selecionada — por exemplo, uma ação de agente deve expor response e Error, mas apenas um placeholder response genérico aparece.

As saídas foram capturadas antes que a seleção de ação terminasse de se propagar. Desmarque o marcador de várias instâncias por meio de Alterar elemento → tarefa regular, confirme se a seção Saídas reflete a ação e, em seguida, aplique novamente o marcador.

Melhores práticas

1. Valide a coleção antes da distribuição — verifique se há listas vazias, nulas ou excessivamente grandes.
2. Mantenha o trabalho por item com curta duração e tolerante a falhasAdicione NovasTentativas quando apropriado.
3. Agregue apenas o que você precisa. Grandes agregações podem afetar o desempenho e a legibilidade.
4. Torne explícitos os critérios de sucesso.Após a tarefa de várias instâncias, adicione um Gateway exclusivo que avalie a variável de saída agregada — por exemplo, rotear para a próxima etapa apenas se o número de resultados bem-sucedidos atender ao seu limite.

Observação:

Várias instâncias paralelas executam elementos em lotes de 50. Se cada item for um objeto grande ou complexo — vários pares de chave-valor ou estruturas aninhadas — mantenha o tamanho total da coleção abaixo de 50 também, pois o tamanho do item afeta quantos podem ser mantidos simultaneamente.

Leia Marcadores (Introdução ao BPMN) para notação e orientação conceitual, e suporte BPMN para a lista completa de elementos BPMN compatíveis com o Maestro.

Trabalhando em um subprocesso ou atividade de chamada? Para escopo de variáveis, mapeamentos de entrada/saída e variáveis de Evento de fim, leia Subprocessos.