Como usar a REST API do 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 pelas suas automações, 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

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 axios

1	npm i express dotenv-safe axios

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=
USER=
PASSWORD=
BASE_URL=

#.env.example - commit to repo

PORT=

USER=

PASSWORD=

BASE_URL=

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

#.env don´t commit
PORT=3000
USER=seu-usuario-do-jira
PASSWORD=sua-senha-do-jira
BASE_URL=http://localhost:8080/

#.env don´t commit

PORT=3000

USER=seu-usuario-do-jira

PASSWORD=sua-senha-do-jira

BASE_URL=http://localhost:8080/

Importante ressaltar que o usuário e senha fornecido no .env deve ter permissão para fazer as atividades que você quer fazer via REST API.

E no index.js, vamos usar o pacote Express para criar a Web API que vai fazer a magia da automação, quando acessada, vai bater na API do Jira para fazer alguma coisa.

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

app.use(express.json());

app.use('/', async (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('/', async (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.

#3 – Jira REST API

Uma das formas mais versáteis (não necessariamente mais fácil) de se integrar com o Jira é através dos endpoints da sua REST API.

Atenção: vamos usar o método Basic de autenticação com a API do Jira. Este método deve ser usado somente sob SSL, para que não corra o risco das credenciais serem capturadas no ambiente produtivo.

Para manipular essa API mais facilmente, vamos criar um cliente próprio em um módulo de nome jiraClient.js que deve ser criado na raiz da nossa aplicação.

const axios = require('axios');

const options = {
    headers: {
        "Content-Type": "application/json"
    },
    auth: {
        username: process.env.USER,
        password: process.env.PASSWORD
    }
};

async function getIssue(id) {
    try {
        const result = await axios.get(
            `${process.env.BASE_URL}rest/api/2/issue/${id}`,
            options
        )
        return result.data;
    } catch (error) {
        console.error(error);
    }
}

module.exports = { getIssue }

const axios = require('axios');

const options = {

headers: {

"Content-Type": "application/json"

auth: {

username: process.env.USER,

password: process.env.PASSWORD

}

};

async function getIssue(id) {

try {

const result = await axios.get(

`${process.env.BASE_URL}rest/api/2/issue/${id}`,

options

)

return result.data;

} catch (error) {

console.error(error);

}

module.exports = { getIssue }

Por enquanto, criamos apenas uma função getIssue nele, que dado um id recebido por parâmetro, bate na API do Jira e retorna a mesma. Repare como uso a configuração auth do Axios para passar o usuário e senha que estão nas nossas variáveis de ambiente.

O principal erro que você pode ter aqui é o de falha de autenticação, caso passe usuário e/ou senha errados.

Para usar este módulo que criamos, podemos usar a nossa webAPI Node.js e importar o nosso módulo lá.

app.use('/', async (req, res, next) => {
    console.log(req.body);

    const jiraClient = require('./jiraClient');
    const issue = await jiraClient.getIssue('PT-1');
    console.log(issue);

    res.send('Hello World');
})

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

console.log(req.body);

const jiraClient = require('./jiraClient');

const issue = await jiraClient.getIssue('PT-1');

console.log(issue);

res.send('Hello World');

})

Para testar, troque o ID passado por parâmetro na função ou até mesmo deixe esse comportamento dinâmico conforme algum parâmetro que venha na URL. O resultado, você confere abaixo.

#4 – Transição no Jira

Agora para finalizar, vamos criar uma automação muito simples no Jira que faz uma issue mudar de um status para outro, o que chamamos de transição, mas em Node.js ao invés de manualmente.

Volte ao nosso módulo jiraClient.js e adicione mais uma função, que fiz com base na documentação oficial.

async function doneIssue(id) {
    try {
        const result = await axios.post(
            `${process.env.BASE_URL}rest/api/2/issue/${id}/transitions?expand=transitions.fields`,
            {
                "transition": {
                    "id": "41"
                }
            },
            options
        )
        return result.data;
    } catch (error) {
        console.error(error.response);
    }
}

module.exports = { getIssue, doneIssue }

async function doneIssue(id) {

try {

const result = await axios.post(

`${process.env.BASE_URL}rest/api/2/issue/${id}/transitions?expand=transitions.fields`,

{

"transition": {

"id": "41"

}

options

)

return result.data;

} catch (error) {

console.error(error.response);

}

module.exports = { getIssue, doneIssue }

Nesta função, fazemos um POST para o endpoint de transição de issue passando no body um objeto com a propriedade transition contendo o ID da transição no seu workflow. Para obter esse ID, vá até as configurações do seu projeto > Fluxos de trabalho e no modo texto de visualização, você encontra esta informação na terceira coluna.

As options (que contém os headers) continuam sendo as mesmas da outra função, por isso basta usarmos o objeto correspondente.

Agora ajuste a sua API Node.js para que ela chame essa função, passando o id da issue que você deseja fazer a transição automaticamente.

app.use('/', async (req, res, next) => {
    const jiraClient = require('./jiraClient');
    const result = await jiraClient.doneIssue('PT-1');
    console.log(result);

    res.send('Hello World');
})

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

const jiraClient = require('./jiraClient');

const result = await jiraClient.doneIssue('PT-1');

console.log(result);

res.send('Hello World');

})

Se tudo deu certo, você não verá nada de novo no console, mas ao consultar o Jira, a issue estará movida para o status correspondente (done no meu caso).

E com isso finalizamos esta segunda 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.

Se não atender tudo, certamente juntando com a primeira parte do tutorial (onde falei de webhooks) deve ficar uma solução muito profissional de automação do Jira.

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

Quer aprender a fazer outras automações usando ScripRunner ou Automation for Jira? Confira 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!