Integração de External tasks através da API REST do Camunda

Quando você integra seu processo de negócios com serviços externos que você não controla completamente (como serviços de cobranças, monitoramento de crédito, etc), é comum precisar que um serviço externo realize parte da tarefa, ou até mesmo a complete. Esse é um padrão de uso frequente. Você tem um client externo que precisa reivindicar uma tarefa, completá-la e devolver o controle ao processo no Camunda.

Outro caso bem comum de uso das external tasks, são para situações em que temos um grande processamento em uma única tarefa, e este pode ser bem demorado, então podemos optar pelas external tasks. Antes de começarmos, vale lembrar que o padrão de external tasks te permite utilizar diversas linguagens como Typescript, Java, Python, C# e outras, porém você perde parte da gestão e poder do motor do Camunda por estar executando esta tarefa externamente, ou seja, algumas coisas que você poderia fazer internamente com o motor do Camunda, você deverá implementar explicitamente em seu código em uma external task. Um exemplo disto seriam os "retries", no qual facilmente você pode implementar uma retentativa no próprio elemento BPMN utilizando implementação com connectors ou delegates, mas com external tasks você precisará implementar a lógica diretamente em seu código, caso desejar. Mas enfim, vamos ao que interessa...

Como completar uma External Task através do CLIENT ou da API REST do Camunda?

External Task - Considere o seguinte cenário abaixo na execução de uma external task:

No exemplo acima, um processo é recebido / iniciado, uma tarefa de serviço processa essa execução e a completa. Em seguida, definiremos a tarefa de serviço que trata dessa solicitação no Camunda Modeler.

Definição da Tarefa de Serviço

Na definição da tarefa de serviço no Camunda Modeler, definimos a tarefa como uma implementação externa e atribuímos a ela um tópico único, process_request. Os tópicos devem ser únicos, pois serão usados para reivindicar as tarefas.

Agora, vamos implementar a tarefa de serviço externa usando a biblioteca JavaScript para Camunda, que facilita a comunicação REST (configuração e manutenção da conexão HTTP, manipulação de certificados TLS, etc.).

Método EXTERNAL TASK CLIENT

Primeiro, instale a biblioteca cliente JavaScript do Camunda. Em seu terminal digite o seguinte comando abaixo:

npm install -s camunda-external-task-client-js

Depois, configure o cliente Camunda com a URL correta para a sua instância:

Com essa configuração, toda vez que uma instância chegar a essa tarefa de serviço, uma instância de tarefa externa será criada e colocada na lista de tarefas de saída, esperando que um trabalhador externo venha reivindicá-la.

A função client.subscribe() garante que o worker faça o polling na fila, buscando por novas tarefas, e então executa a função processRequestById(request_id).

Função de processamento da requisição

Uma função para tratar a solicitação pode ser escrita da seguinte forma:

Essa função imprime a variável "request_id" e retorna uma mensagem de sucesso.

Nota Importante: Ao "reivindicar" a tarefa, um bloqueio é definido, garantindo acesso exclusivo à tarefa, para que a mesma tarefa não seja reivindicada 2 ou mais vezes ao mesmo tempo, esse processo é chamado de FetchAndLock. Você pode liberar o bloqueio explicitamente ou simplesmente completar a tarefa e deixar o bloqueio expirar. Se o tempo de execução da external task exceder o tempo de bloqueio, ocorrerá um erro ao tentar completar a tarefa. Portanto, ajuste os tempos de espera conforme necessário. Os tempos de espera podem ser configurados globalmente pelo cliente ao se inscrever, ou individualmente em cada função de inscrição. Você também pode estender o bloqueio com uma callback ao motor:

Isso adicionará mais cinco segundos para completar a tarefa.

Se você quiser executar o código acima, pode usar a Task List no Camunda para iniciar um processo e definir a variável request_id manualmente.

Você verá uma saída similar a esta:

/usr/local/bin/node ./task-handler.js 
✓ subscribed to topic execucao_processo 
Processing request with ID: Gerando Codigo 
✓ completed task dc76f8f5-132f-11ad-a2ec-0192362eb5d5

Método API REST

Agora, digamos que você prefira não usar bibliotecas e optar por chamadas REST diretas para pegar e completar uma tarefa. Isso também é possível, mas requer um pouco mais de informações.

As bibliotecas que ajudam a construir workers de external tasks lidam com muitas configurações, mas você pode fazer tudo isso manualmente se preferir.

Se você iniciou sua instância do Camunda com a flag --swaggerui, você tem acesso a toda a API REST exposta pela Camunda Platform 7.

Para completar a tarefa execucao_processo via API REST, primeiro precisamos encontrar a instância do processo:

GET https://localhost:8080/engine-rest/process-instance?active=true

Isso retornará uma lista de todas as instâncias de processos ativas. Busque a instância desejada, que terá uma aparência similar a esta:

Com o ID da instância do processo, podemos buscar a tarefa externa:

GET https://localhost:8080/engine-rest/external-task/0997307a-6366-11ec-952c-0242661ea8d3

Isso nos dará detalhes sobre a tarefa:

Com essa informação, podemos buscar e bloquear a tarefa:

POST "https://localhost:8080/engine-rest/external-task/fetchAndLock

Vamos detalhar o JSON enviado:

Com a tarefa bloqueada, precisamos completá-la com outra chamada POST:

POST https://localhost:8080/engine-rest/external-task/0997307a-6366-11ec-952c-0242661ea8d3/complete

Novamente, vamos detalhar o JSON enviado para completar a tarefa:

Conclusão: Agora você conhece duas maneiras de completar tarefas externas: usando uma biblioteca do external task client e fazendo chamadas REST diretamente. Para ambientes de produção, o uso de bibliotecas do client é o mais recomendado pela Camunda, mas as chamadas REST são excelentes para aprendizado e entendimento profundo do funcionamento do Camunda e das bibliotecas client.

---

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