Como criar WebHooks no Jira Server com Node.js

O Jira é a ferramenta para gestão ágil de projetos mais utilizada no mundo tem algum tempo. Uma das coisas mais legais nesta ferramenta é a sua capacidade quase ilimitada para customização, em parte pelos seus esquemas próprios de configuração, outra parte pelo marketplace com mais de 4.000 add-ons, mas também pelos seus webhooks e REST API.

Com esses recursos todos, é possível não apenas consumir e transformar dados oriundos do Jira, como também automatizar muitas tarefas manuais que os times possam estar realizando repetidamente. Eu costumo dizer aos alunos do meu curso de Jira que eles tem de aprender a colocar o Jira a trabalhar pra eles, e não o contrário!

E é justamente sobre estas duas últimas formas citadas que vamos trabalhar nos próximos dois tutoriais aqui do blog: como criar automações no Jira Server usando webooks e a API REST através do Node.js.

Antes de avançarmos, valem alguns avisos:

este tutorial foi feito e testado no Jira Server v7.6.1, não posso afirmar que ele funcione igual na versão Jira Cloud, mas vale dar uma testada;
este é um tutorial de programação, se você não é programador, envie esse tutorial para o seu time de devs;
os exemplos de código são em Node.js e este não deve ser seu primeiro tutorial com esta tecnologia (comece com tutoriais mais básicos), mas se conhecer outra linguagem, você pode facilmente adaptar os exemplos mostrados

Dito isso, vamos em frente!

#1 – Ambiente de Dev

Para fazer o tutorial aqui descrito, você vai precisar de permissão de administrador em um servidor Jira Server. Como nem todo dev tem esse tipo de acesso na empresa, recomendo que baixe e instale uma versão trial (30 dias) do Jira Server na sua máquina. Além disso, como você estará desenvolvendo e testando em localhost, é interessante que o Jira também esteja em localhost.

Você pode fazê-lo no site oficial da Atlassian: https://www.atlassian.com/br/software/jira/download

Este tutorial foi feito com a versão 7.6.1 para Windows 10 64-bit, com o JDK previamente instalado (ele é necessário para rodar o Jira). No caso do Windows, a instalação é beeeem simples, só ir seguindo as orientações, criar a conta de administrador, ativar seu trial…nenhum mistério aqui.

Ao término da instalação, você terá um Jira Server rodando em localhost:8080 e permissão de administrador nele.

Crie um novo projeto no Jira, do tipo Kanban, e nele coloque uma história de teste, só para termos como testar algumas coisas.

#2 – Projeto Node.js

Se preferir, o vídeo abaixo mostra praticamente o mesmo projeto, passo a passo.

Crie uma pasta para o projeto na sua máquina e rode o comando abaixo para inicializá-lo:

npm init -y

1	npm init -y

Agora, instale as seguintes dependências nele:

npm i express dotenv-safe

1	npm i express dotenv-safe

Depois de instalado, abra o projeto no VS Code e crie os arquivos .env, .env.example e index.js

No arquivo .env.example, vamos definir o template de variáveis de ambiente que vamos usar:

#.env.example - commit to repo
PORT=

1 2	#.env.example - commit to repo PORT=

No .env, usamos as mesmas variáveis, mas definindo o seu valor.

#.env don´t commit
PORT=3000

1 2	#.env don´t commit PORT=3000

E no index.js, vamos usar o pacote Express para criar a Web API que vai fazer a magia da automação, recebendo estímulos do Jira, realizando processamentos e mandando comandos pra ele.

require('dotenv-safe').config();
const express = require('express');
const app = express();

app.use(express.json());

app.use('/', (req, res, next) => {
    console.log(req.body);
    res.send('Hello World');
})

app.listen(process.env.PORT, () => {
    console.log(`Running at ${process.env.PORT}`)
})

require('dotenv-safe').config();

const express = require('express');

const app = express();

app.use(express.json());

app.use('/', (req, res, next) => {

console.log(req.body);

res.send('Hello World');

})

app.listen(process.env.PORT, () => {

console.log(`Running at ${process.env.PORT}`)

})

Por enquanto, a nossa WebAPI apenas sobe um app Express na porta configurada com uma rota padrão que imprime o body da request no console e um Hello World como retorno.

Teste e verá que funciona perfeitamente, pode usar o Postman para o teste. Se nunca usou o Postman, o vídeo abaixo ensina.

#3 – WebHook no Jira

Uma das formas mais fáceis de se integrar com o Jira é através de webhooks.

Webhooks são requisições HTTP que um sistema faz em outro sistema quando algo acontece. Ou seja, ao invés de você ficar consultando o Jira para ver se uma issue mudou de status, por exemplo, você pode criar um webhook que avise a sua aplicação externa quando isso acontecer.

Para criar um webhook no Jira Server é bem simples, primeiro você tem de ir em Configurações > Sistema > Webhooks.

Agora, clique no botão Criar um WebHook, no canto superior direito.

Dê um nome sugestivo para o WebHook e cole nele a URL da sua WebAPI Node.js que acabamos de criar (hoje ela responde na raiz mesmo). Vai ficar assim.

Mais abaixo, você pode configurar em que ocasiões esse webhook vai ser disparado. Você pode fazê-lo marcando checkboxes, definindo um filtro JQL ou ainda associando este webhook a uma transição de status, lá pelo workflow. Vamos usar este último recurso, então inicialmente, salve sem marcar nenhuma das opções.

#4 – Transição no Jira

Agora o próximo passo é editarmos o nosso Workflow para, quando uma transição específica acontecer, o WebHook ser disparado.

Para isso, acesses as configurações do seu projeto > Fluxos de Trabalho > Editar.

Com o workflow aberto no modo visual, clique na linha da transição de um dos estados (aqui fui no In Progress) e na janelinha lateral de opções, escolha “Funções de Post”, que são aquelas que executam após a transição ser realizada.

Na janela que vai se abrir, escolha a opção para “criar uma nova função de post” e em seguida marque a opção “Desencadear um WebHook”. Se você criou o seu WebHook no Jira corretamente, ele vai aparecer para você selecionar.

Adicione o webhook e depois publique as alterações do seu Workflow.

Agora, você pode testar se a Post Function do Jira irá disparar o WebHook que por sua vez vai bater em nossa API Node.js quando uma issue for movimentada para In Progress.

O resultado você confere no console da sua WebAPI.

Repare como é um objeto cheio de informações úteis para integrações com a ferramenta, incluindo uma propriedade issue, com todos os dados da issue que ocasionou o disparo do WebHook.

E com isso finalizamos esta primeira parte do tutorial com sucesso e que, talvez, já atenda todas as suas necessidades de integrar o Jira com outra aplicação da sua empresa.

Não esqueça é claro de quando publicar a sua WebAPI em produção, de mudar a URL de destino do seu WebHook. Falando de ambiente produtivo, uma dica é você usar uma arquitetura Serverless para subir essa API Node, conforme ensino neste tutorial.

Quer aprender agora como a sua WebAPI pode manipular o Jira? Veja este tutorial de como usar a REST API do Jira Server.

Para outros tipos de automações usando ScriptRunner e Automation for Jira, consulte este tutorial.

Um abraço e até a próxima!

* Quer aprender a dominar o Jira, tirando o máximo proveito de todas suas funcionalidades? Conheça meu curso de Jira clicando no banner abaixo!