Marcadores de várias instâncias

Visão geral

Use marcadores para configurar a execução de um determinado tipo de tarefa para criar várias execuções dessa tarefa iterando sobre uma variável List. Acesse Marcadores no capítulo introdutório do BPMN para obter mais detalhes.

Com qualquer tipo de tarefa selecionado, selecione Alterar elemento e escolha um dos tipos de marcadores.

Para adicionar um marcador de várias instâncias

Você pode transformar qualquer tarefa compatível em uma tarefa de várias instâncias de um designer BPMN:

1. Selecionar uma tarefa na tela.
2. Na barra de ferramentas do elemento acima da tarefa, selecione Alterar elemento.
3. Escolha o marcador de várias instâncias (ícone sequencial ou paralelo).
   • Isso anexa o marcador BPMN à tarefa.
4. Abra o Painel de propriedades e expanda a seção Múltiplas instâncias para configurar a lista de itens.

Observações

• Adicionar o marcador BPMN não expõe controles extras como Alias ou modo; a única configuração aparece na seção Múltiplas instâncias, em Itens.
• O marcador é declarativo; o Maestro determina o modo de execução automaticamente.
• A multiinstância é compatível apenas com tarefas, não com subprocessos.

quando usar

Use a execução em várias instâncias para distribuir uma atividade em uma coleção, por exemplo:

• validando uma lista de IDs de faturas
• enriquecimento de registros
• Envio de notificações por destinatário

Esse padrão escala melhor do que um loop manual e preserva a observabilidade.

Configuração

• Selecione a tarefa que você deseja executar para cada elemento de uma lista.
• No Painel de propriedades, expanda Múltiplas instâncias.
• Em Itens, escolha a variável de lista que contém os elementos nos quais você deseja iterar (por exemplo, vars.invoiceList).
  O Maestro cria uma execução por elemento de lista.
  Faça referência ao item atual usando o índice ou suas propriedades (vars.invoiceList[index].id).
• (Opcional) Expanda Tratamento de erro e alterne Tentar novamente para falhas a fim de tentar novamente execuções de itens individuais.
• Execute ou Debug o processo para visualização de uma instância de atividade por elemento de lista na trilha de execução.

Expressão do iterador (quando disponível)

Algumas atividades fornecem um campo dedicado para mapear o item atual para o valor de entrada exato por execução.

Exemplos:

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

Os iteradores representam itens individuais quando uma tarefa de várias instâncias Processes uma Coleção.

A sintaxe correta depende de onde a iteração ocorre:

iterator.item — quando uma Tarefa tem um marcador de várias instâncias aplicado

Orientação do painel de propriedades

• Ação: escolha como a tarefa é executada (ação do Integration Service, ação do agente ou Nenhum para modelagem).
• Entradas: forneça valores para cada iteração.
  Exemplo:
  • Entrada: invoiceId
  • Value: vars.invoiceList[index].id
• Saídas: o Maestro agrega todas as saídas automaticamente.
• Atualizar variáveis: escolha para atualizar após cada iteração ou após o subprocesso terminar.

iterator[0].item — ao trabalhar dentro de um subprocesso chamado a partir de uma tarefa de várias instâncias

Orientação do painel de propriedades

• Ação: configure como o subprocesso interage com o sistema externo, API ou agente.
• Entradas: mapeie o elemento atual ou suas propriedades.

Exemplo:

• Entrada: currentItemId
• Value: vars.itemsToProcess[index].id

Exemplo: validar uma lista de faturas usando execução multi-instância.

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

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
   • Exemplo de valor: ["INV-001", "INV-002", "INV-003"]

2. Adicione uma tarefa de serviço

1. Adicione uma Tarefa de serviço e nomeie-a Validar fatura.
2. Abra o Painel de propriedades, expanda Múltiplas instâncias.
3. Em Itens, selecione invoiceList.

3. Use o item atual nas entradas

Na seção Entradas:

• Exemplo: defina ID da fatura = vars.invoiceList[index].
• Se a lista contiver objetos:
  Use vars.invoiceList[index].Id.

4. Configure a implementação

Na seção Implementação:

• Ação: Iniciar e aguardar o agente
• Agent: seu agente de validação de faturas

5. Depure o processo

1. Selecione Debug passo a passo.
2. Você verá uma execução de Validar fatura por item da lista.
3. A trilha de execução exibe a execução de cada item separadamente.

Exemplo de várias instâncias paralelas

1. Adicione uma Tarefa de serviço chamada Validar fatura.
2. Selecionar Alterar Elemento → escolha Múltiplas instâncias paralelas.
3. No Painel de propriedades, expanda Múltiplas instâncias.
4. Em Itens, escolha a variável de lista (por exemplo, vars.invoiceList).
5. Depure o processo para visualizar uma instância de atividade por elemento de lista na Trilha de execução.

Compatibilidade com loop

Use multi-instância para Substituir loops manuais.Trate a coleção como o limite do loop. O Modo sequencial Processes itens em Ordenar e aguarda que cada um finalize Antes que o próximo comece.O Modo paralelo inicia muitos itens de uma só vez e é concluído quando Todos finalizam ou quando sua Condição de parar é atendida.Mantenha o trabalho por item idempotente e de curta duração. Use agregação se você precisar de uma única saída combinada.

Tipos de coleção tratados como repetíveis

Para a execução em várias instâncias, o Maestro trata os seguintes tipos de coleção como repetíveis:

• 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[]

Comportamento dos runtimes

1. Fan‑out / fan‑in: o Maestro cria uma instância de atividade por item e completa o grupo quando todas as Instâncias terminam (ou antes, se você usar uma política de parada personalizada posteriormente).
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: trate o resultado de cada item de forma independente. A lógica subsequente deve definir como identificar falhas parciais (por exemplo, continuar, tentar novamente ou parar com base em limites).
5. Observabilidade: cada execução de item é rastreada, permitindo o status por item e resultados agregados.

Exemplo

Cenário: você recebe uma lista de IDs de faturas de uma API externa e deve validar cada fatura por meio de uma segunda API.

Plano:

1. Obtenha uma lista dinâmica de IDs de faturas (de uma etapa anterior ou interrogação externa).

2. Aplique um marcador de várias instâncias paralelas à atividade de validação para distribuir uma ação por fatura.

3. Use agregação para produzir uma única saída combinada (por exemplo, uma lista de {invoiceId, isValid, errors}) para etapas subsequentes.

   

Melhores práticas

1. Valide a coleção antes de distribuir (listas vazias, nulas ou excessivamente grandes).
2. Mantenha o trabalho por item de curta duração e tolerante a falhas; adicione novas tentativas 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 (por exemplo, proceed if ≥95% items succeed).

Observação:

Atualmente, as várias instâncias paralelas executam elementos em lotes de 50.

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.