Tutorial de Workflow/BPM com Node.js (Camunda)

Este artigo considera que você já sabe o mínimo de Node.js e HTTP, é um tutorial intermediário em programação.

Desde 2017 que atuo em ambientes corporativos e uma coisa que aprendi a respeitar nesse mundo são os BPMS, ou Sistemas de Gestão de Processos de Negócio, os populares “workflows”. Dentre eles, o Camunda se demonstrou uma excelente ferramenta com esse propósito, o de orquestrar complexos processos como originação de contas digitais, automação de processos manuais simples e complexos e mesas de análise.

Além de possuir uma versão gratuita (community) e ter uma baixa curva de aprendizado, o Camunda permite a integração com web APIs Java, Node.js e REST em geral. E é essa conectividade com web APIs Node.js que vamos explorar no tutorial de hoje, criando um workflow simples que chama uma API Node quando chega na etapa correta.

Mas antes de começar, meu intuito com este tutorial é não apenas lhe ensinar como usar esse tipo de ferramenta, mas te motivar a conhecer esse mundo dos BMPS pois é muito promissor.

Vamos lá!

1 – Instalando o Camunda

O Camunda é feito em Java e por isso roda nos principais sistemas operacionais do mercado. Você pode baixar a versão gratuita e open-source, Community Platform, no site oficial.

O zip que você baixa e deve extrair em uma pasta à sua escolha possui o motor de processos, o recurso de Tasklist para processos manuais e o Cockpit, que é a parte de monitoramento.

Além do Community Platform, baixe o Open Source Modeler neste link, que é a ferramenta visual para criação dos fluxos de trabalho.

Ambos arquivos são bem leves de baixar e de rodar. Na própria página de download de cada um deles explica como executá-los no seu sistema operacional, sendo que você deve ter o Java 1.7+ instalado na sua máquina para que eles funcionem (JRE e/ou JDK), bem como as variáveis de ambiente JAVA_HOME (se instalou JDK) ou JRE_HOME (se instalou o JRE) configuradas (quem é programador Java certamente já fez isso antes).

Para executar o motor no Windows (Community Platform), basta executar o start-camunda.bat, enquanto que em sistemas Unix, rode o start-camunda.sh. Em ambos os casos, o terminal deve exibir que o motor está rodando e o navegador deve abrir uma página do Tomcat em localhost:8080, como abaixo.

A partir dessa tela é possível acessar as aplicações do servidor do Camunda para gestão e monitoramento.

Já o Camunda Modeler é ainda mais simples de usar, pois para Windows e Mac basta iniciar o executável da aplicação e no Linux é outro arquivo .sh.

2 – Modelando nosso primeiro processo

Quando ele iniciar, deve apresentar uma tela como abaixo, onde vamos iniciar nosso primeiro processo (BPMN Diagram). A título de curiosidade, BPMN é a notação padronizada e mundial para fluxos de trabalho, mantido pela OMG (a mesma instituição que mantém o UML).

Para aprender vamos criar um processo bem simples: dado que um usuário deseje se cadastrar no sistema, vamos salvar ele no banco e depois mandar um e-mail pra ele, de boas vindas. Esse processo curto e simples deve lhe ajudar a entender como funciona o Camunda e como a integração com o Node.js pode ser feita, inclusive simplificando sua arquitetura.

Como meu intuito aqui não é lhe ensinar BPMN ou a usar a ferramenta visual do Camunda (que é auto explicativa), modele um processo como abaixo e explicarei na sequência o que faz cada caixinha.

Basicamente o círculo representa o início do processo. Os retângulos, são atividades (Tasks), sendo que usei o ícone de ferramenta pra alterar o tipo para Service Task. O último círculo é o fim do processo.

Existem diferentes maneiras de executar Service Tasks com Camunda e aqui vou ensinar a que faz mais sentido para desenvolvedores Node.js que é usando o padrão External Task.

Clique no primeiro retângulo de Service Task e depois na aba Properties Panel à direita. Em Implementation selecione External e em Topic escreva o nome da fila desta atividade como “salvar-usuario-banco”, como na imagem abaixo.

Faça o mesmo procedimento para o segundo Service Task (enviar-email).

Agora vamos configurar nosso processo para execução. Para fazer isso é bem simples: clique em qualquer área branca do workflow e depois na aba Properties Panel para configurar um process id, process name e marcar que ele é executável, como abaixo.

Lembre-se desse process-id, vamos usá-lo mais tarde para inserir usuários no workflow pela API do Camunda.

Salve o arquivo de workflow em uma pasta que você ache depois.

3 – Programando o serviço externo

O próximo passo é criar o serviço externo que vai ficar olhando para o tópico ‘salvar-usuario-banco’ que definimos no Service Task de salvar o usuário no banco. Imagine este tópico como sendo uma fila que o Camunda vai adicionando usuários para serem salvos no banco. Precisaremos de um worker Node.js que vai ficar esperando chegar usuários nesta fila para serem cadastrados.

Para criar este worker, crie um novo projeto Node.js em sua máquina com o nome ‘salvar-usuario-banco-worker’ e rode um npm init nele.

mkdir salvar-usuario-banco-worker
cd salvar-usuario-banco-worker
npm init -y

mkdir salvar-usuario-banco-worker

cd salvar-usuario-banco-worker

npm init -y

Agora, vamos instalar a biblioteca do Camunda para clientes de serviços externos em Node.js, com o comando abaixo:

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

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

Agora, dentro da pasta do seu projeto Node.js crie um arquivo worker.js como abaixo, que vai fazer long polling na fila do Camunda com o tópico apropriado.

const { Client, logger } = require('camunda-external-task-client-js');

// configuration for the Client:
//  - 'baseUrl': url to the Process Engine
//  - 'logger': utility to automatically log important events
//  - 'asyncResponseTimeout': long polling timeout (then a new request will be issued)
const config = { baseUrl: 'http://localhost:8080/engine-rest', use: logger, asyncResponseTimeout: 10000 };

// create a Client instance with custom configuration
const client = new Client(config);

// susbscribe to the topic: 'salvar-usuario-banco'
client.subscribe('salvar-usuario-banco', async function({ task, taskService }) {
  // Put your business logic here

  // Get a process variable
  const username = task.variables.get('username');
  const email = task.variables.get('email');

  console.log(`Salvando o usuário ${username} com o email '${email}'...`);

  // Complete the task
  await taskService.complete(task);
});

const { Client, logger } = require('camunda-external-task-client-js');

// configuration for the Client:

// - 'baseUrl': url to the Process Engine

// - 'logger': utility to automatically log important events

// - 'asyncResponseTimeout': long polling timeout (then a new request will be issued)

const config = { baseUrl: 'http://localhost:8080/engine-rest', use: logger, asyncResponseTimeout: 10000 };

// create a Client instance with custom configuration

const client = new Client(config);

// susbscribe to the topic: 'salvar-usuario-banco'

client.subscribe('salvar-usuario-banco', async function({ task, taskService }) {

// Put your business logic here

// Get a process variable

const username = task.variables.get('username');

const email = task.variables.get('email');

console.log(`Salvando o usuário ${username} com o email '${email}'...`);

// Complete the task

await taskService.complete(task);

});

Atenção às variáveis da task que estou pegando, que são os inputs que definimos lá atrás, na Service Task. Também preste atenção na linha que faz o console.log, é ali que você colocaria a lógica de salvar no banco de verdade.

Coloque esse worker a rodar normalmente em Node e ele deve se conectar à sua instância do Camunda (ela precisa estar rodando como falei lá atrás).

4 – Implantando o processo

Agora que modelamos o processo e criamos o worker do Serviço Externo, é hora de publicarmos o nosso processo no Camunda, para que ele passe a funcionar.

No Camunda Modeler, o botão de deploy é o mais à direita no menu (parece um botão de upload) e ao clicar nele, a janela abaixo se abre para que você configure o deploy.

Caso tenha feito tudo corretamente, o deploy deve ser bem sucedido. Caso contrário, a aba inferior Logs vai se abrir explicando o que houve.

Para ver se seu processo está devidamente implantado no Camunda, você pode ir no navegador e usar o Cockpit em http://localhost:8080/camunda/app/cockpit (use usuário e senha demo)

Agora para testar se nosso processo está funcionando, você deve realizar uma chamada REST ao Camunda, o que recomendo que seja feito usando o POSTMAN.

Será um POST em http://localhost:8080/engine-rest/process-definition/key/cadastrar-usuario/start (note o nome do processo em negrito) com Content-Type application/json no header e o seguinte body (raw):

{
	"variables": {
		"username": {"value":"luiz"},
		"email": {"value":"contato@luiztools.com.br"}
	}
}

{

"variables": {

"username": {"value":"luiz"},

"email": {"value":"[email protected]"}

}

Se tudo der certo, ao você enviar essa requisição, terá retorno positivo no POSTMAN, como abaixo.

Olhando no terminal que está rodando o nosso worker Node.js, temos:

O que mostra que passou corretamente por onde deveria.

5 – Indo além

Mas e o que aconteceu quando o usuário chegou na etapa de envio de e-mail?

Dê uma olhada no Cockpit, acessando o nosso processo Cadastrar Usuário. Você vai ver que tem um número na Service Task de enviar email indicando que tem um usuário preso ali.

O processo chega nessa etapa e pára, pois não implementamos nada que consuma o tópico de envio de e-mail ainda. Esse é o funcionamento básico do workflow, ele vai ficar com o usuário preso até que ele seja consumido da sua fila por algum worker Node.js.

Se clicarmos no ID desse usuário, você consegue ver os seus dados e inclusive podemos editá-los.

Para podermos avançar, você terá de implementar um novo worker, para consumir o tópico de envio de e-mails. Faça isso usando o passo-a-passo que fizemos antes e coloque a rodar o seu novo worker que deve funcionar normalmente. Se quiser, use o que ensinei de Node Mailer para enviar e-mails de verdade usando Node.js, ou então o connector de envio de e-mails do Camunda.

Tão logo você suba um worker que consuma o tópico de envio de e-mails, a fila destrava e zera novamente.

Existem muitas outras coisas bacanas que dá para fazer com Camunda + Node, como colocar regras de negócio em DMNs, fazer transbordo de atividades para seres humanos, fornecer fronts para interagir com etapas do processo, postergar ações por tempo determinado, forks, syncs, startar tasks em paralelo e muito mais.

Espero ter despertado o seu interesse pelo assunto e no futuro pretendo escrever mais sobre ele conforme fizer sentido.

Confira a segunda parte deste tutorial neste link!

Curtiu o tutorial? Quer fazer com curso online de Node.js e MongoDB comigo? Clique no banner abaixo!