Como finalizar uma única instância em Multi-Instance no Camunda sem excluir o array todo.

Por William Robert Alves

Introdução

No Camunda, frequentemente trabalhamos com multi-instances para executar atividades repetidas vezes, seja de forma paralela ou sequencial. No entanto, pode haver situações em que precisamos finalizar, excluir ou cancelar uma única instância dentro de um multi-instance. Este artigo irá abordar como realizar essa tarefa de forma eficaz, evitando a exclusão de todo o array do multi-instance.

Cenário:

Imagine o seguinte cenário no fluxo abaixo:

Temos um array de cobranças executando em multi-instance sequencial, e por ser sequencial, o próximo elemento do array só será executado após a finalização do elemento anterior. De repente nos deparamos com um erro em um das cobranças, e precisamos finalizar ela de alguma forma, para que as próximas cobranças continuem sendo executadas... teremos um problemão e vamos entender logo abaixo!

Problema

Quando tentamos excluir ou cancelar uma única instância em um multi-instance no Camunda, frequentemente nos deparamos com a exclusão de todas as instâncias do array. Isso ocorre porque o motor do Camunda interpreta o multi-instance como uma execução única em loop, e caso ocorra algum problema em um dos elementos do array, entende-se que todo processo falhou, sendo assim, caso tentarmos excluir qualquer elemento do array durante a execução, o array todo será excluído.

Quando executamos um process instance modification em um elemento do multi-instance este problema também ocorre, pois para este processo, precisamos primeiro criar um "clone" deste elemento com o "startBeforeActivity", e após isto, fazer o "cancel" do elemento de transição anterior, e é neste cancelamento que o Camunda acaba cancelando / finalizando o array todo.

Solução proposta

Para resolver este problema, utilizamos uma abordagem que envolve a criação de um subprocesso adicional que encapsula as atividades do multi-instance. Dentro desse subprocesso, usaremos eventos de mensagem para correlacionar e gerenciar a finalização de uma única instância sem afetar as demais.

Aqui está um passo a passo detalhado de como configurar isso no Camunda.

Passo a Passo

1. Configurar o Multi-Instance

1. Modelar o Processo Principal: Comece modelando seu processo principal e parametrizando o array na entrada do multi-instance. Esse array será utilizado para iterar sobre as atividades no multi-instance.
   

2. Configurar Multi-Instance: Configure o bloco de multi-instance para iterar sobre o array. Certifique-se de que está configurado como sequencial ou paralelo conforme a necessidade do seu processo.
   

Note que na imagem acima (config do multi-instance), receberemos um objeto chamado Cobrancas, e dentro deste objeto temos a propriedade "cobrancas" que contém nosso array de cobranças. Para cada elemento dentro deste array, criaremos um elemento dentro do multi-instance com o nome "cobranca", conforme definimos no campo "Element Variable".

2. Envolver as atividades internas em um Subprocesso

Criar Subprocesso: Crie um subprocesso que encapsule todas as atividades internas de nosso multi-instance, em nosso exemplo são as Call Activities 1 e 2. Isso nos permitirá gerenciar melhor a instância específica dentro do multi-instance.

Subprocesso usado para manipular a instância em qualquer etapa do multi-instance: Este subprocesso criado dentro do multi-instance será usado apenas para manipular nossa instância com eventos em qualquer etapa em que ela se encontre.

3. Adicionar Event de Mensagem

Adicionar Event de Mensagem de Intermediário: Dentro do subprocesso, adicione um evento de mensagem de borda interruptivo (intermediate boundary event). Esse evento será utilizado para receber mensagens que indicarão a finalização de uma instância específica.

Não esqueça de definir o "Global message reference" / "Name", que em nosso exemplo abaixo definimos como "desviarInstancia", e nos permitirá manipular a instância.

Por questões de boas práticas de modelagem, não ligamos este elemento diretamente ao "End event", mas sim criamos um exclusive gateway para direcionarmos a instância ao fim do multi-instance.

Correlacionar com BusinessKey e Loop Counter: Configure o evento de mensagem para correlacionar utilizando a businessKey e o loopCounter. A businessKey pode ser utilizada para identificar a instância do processo, enquanto o loopCounter identifica a posição específica do elemento do array que queremos manipular no multi-instance.

Para isto podemos fazer uma request HTTP, utilizando alguma aplicação como Postman ou Insomnia com o seguinte request body abaixo:

POST - http://localhost:8080/engine-rest/message

{
  "messageName": "desviarInstancia",
  "businessKey": "1",
  "correlationKeys": {
    		"loopCounter": {"value": 1, "type": "Integer"}
  }
}

4. Implementar a Lógica de finalização

Criar Serviço de finalização: Você pode fazer esta request manualmente caso ocorra algum erro, ou caso queira automatizar isto, pode implementar alguma lógica em seus delegates para chamar o endpoint de message, passando este request body acima dinâmicamente.

Configurar Evento de Fim: Configure um evento de fim apropriado dentro do subprocesso para direcionar a instancia com problema e para garantir que, após a finalização deste elemento, o processo continue corretamente com as instâncias restantes.

Conclusão

Com essa abordagem, você pode finalizar uma única instância dentro de um multi-instance no Camunda sem afetar todo o array. Utilizando subprocessos e eventos de mensagem, conseguimos isolar e gerenciar a finalização de forma mais granular e controlada. Esta técnica é especialmente útil em processos complexos onde a gestão de instâncias individuais é crucial.

---

Quer conhecer um pouco mais sobre esta ferramenta e outras tecnologias? Nos siga nas redes sociais @gerandocodigo (instagram / youtube / tiktok / facebook).