Como criar automações e scripts no Jira Server

Se você curte o Jira, não deixe de conferir meu artigo sobre gestão de backlog usando Jira!

O Jira permite criar diversos tipos de automações, principalmente através de plugins como o famoso Adaptavist ScriptRunner ou o Automation for Jira. Vou mostrar aqui como criar alguns tipos diferentes de automação, todas usando o Jira Server v7.10 (a versão que mais tive contato, mas é possível que funcione nas posteriores) e necessitando de permissão de administrador para serem criadas.

Como uma dica geral, todas automações que exigem script Groovy você pode usar log.warn(“mensagem”) para registrar logs e ajudar no seu debug enquanto estiver programando e quando estiver em produção e ter de fazer troubleshooting.

Atenção: Este artigo não tem a pretensão de ensinar a administrar Jira, mas apenas a dar um upgrade nas suas skills se já for um administrador de Jira Server. Para quem quer aprender a administrar Jira, recomendo meu curso online de Jira, clique no banner abaixo.

Tipo 1: Automações de Workflow

Você pode criar automações que serão disparadas quando uma issue for realizar uma transição dentro do seu workflow, ou seja, mudar de um estado para outro. Esse recurso é muito poderoso para:

• criar validações na troca de estado, como garantir que campos estejam preenchidos, por exemplo;
• Realizar atividades automáticas após uma troca de estado (atualizar um campo, disparar um script Groovy, etc);
• Disparar eventos que podem ser tratados depois, pelo Jira (listeners, mais adiante);

Para criar uma validação de campo obrigatório (ou que tenha de ter um valor específico preenchido), você deve:

1. Clicar em Project Settings (ícone da engrenagem);
2. Clicar em Workflows;
3. Clicar no botão de Edit do workflow em questão (ícone do lápis);
4. Seleciona a visualização em forma de Diagram;
5. Clica na linha da transição que deseja adicionar a validação;
6. Seleciona a opção Validators (ou Post Function se for querer disparar eventos depois da transição);
7. Clique no link “Add validator”;
8. Seleciona a opção “Script validator [Script Runner]”;
9. Seleciona a opção “Simple scripted validator”;

A seguir, preencha os campos da seguinte forma:

• Note: nome da validação;
• Condition: o seu código Groovy que deve retornar true ou false, dizendo se aquela transição vai poder acontecer ou não;
• Error Message: mensagem de erro que vai aparecer se a validação bloquear a transição (retorno false);
• Field: se você deixar esse campo em branco, a mensagem de erro vai aparecer no topo do formulário. Preencha se quiser que ela apareça ao lado do campo;

No exemplo abaixo, o campo Área de Negócio deve ser preenchido para que uma issue possa ser criada:

Caso você quer que algo aconteça DEPOIS da transição ocorrer, você usa post-function ao invés de validator e além de vários templates prontos, você também pode codificar o comportamento usando Script Runner.

Tipo 2: Automações para Jira Service Desk

Você pode criar automações baseadas no Service Desk e seus serviços. Para fazê-lo, precisa de permissão de administrador no Jira Service Desk ao invés do Jira Software. Esse recurso é muito poderoso para:

• Criar alertas diversos, como SLA expirando, por exemplo;
• Atualizar issues relacionadas toda vez que a principal for alterada;
• Reabrir issues que tenham sido comentadas;
• Muitos tipos de regras personalizadas;

1. Clique em Project Settings;
2. Clique em Automation;
3. Clique em Add Rule;
4. Selecione o tipo de regra que deseja adicionar, neste exemplo usarei Custom Rule (Regra Personalizada);

Preencha os campos como segue:

• Rule name: o nome da automação;
• Description: a descrição do que faz esta automação;

Construa a automação como segue:

• When: a situação ou evento que irá disparar esta automação. Adicione tantas triggers (gatilhos) quanto forem necessárias. Por exemplo, toda vez que o status de uma issue seja atualizado.
• If: a condição (uma ou mais) que será validada para esta automação executar ou não. As condições disponíveis no if dependem do when. Quando for uma issue, por exemplo, as condições vão ser relacionadas a issues.
• Then: uma ou mais ações que serão executadas quando esta automação ocorrer. Por exemplo, você pode mudar o estado de uma issue ou enviar um e-mail.

Neste tipo de automação não qualquer criação de script, é tudo visual.

Tipo 3: Automações com Escalation Services

Você pode criar automações que serão disparadas automaticamente, de tempos em tempos. Esse também é um recurso do ScriptRunner e permite fazer coisas como fechar chamados automaticamente depois de X tempo;

Para criar um escalation service, você deve:

1. Ir na administração geral do Jira Software estando autenticado como administrador;
2. Acesse a aba Add-ons;
3. No menu esquerdo, vá em Escalation Services, dentro da subseção Script Runner;
4. Clique em Create Escalation Service;

Existem vários tipos, vamos usar aqui o Escalation Service de Issue.

Preencha os campos do formulário como segue:

• Description: o nome do escalation service;
• JQL Query: a consulta que irã ser executada de tempos em tempos para executar a ação automática sobre as issues retornadas;
• As User: o usuário que irá executar a automação;
• Interval/CRON Expression: uma expressão CRON que determine a periodicidade da automação;
• Action: opcional, permite escolher uma transição de workflow pré-existente, útil se você apenas quer mudar o status das issues retornadas pelo JQL;
• Additional issue actions: script Groovy que faz a operação que você deseja, nas issues retornadas pelo JQL.
• Transition Options: alguns cheats para tornar a transição mais fácil como ignorar validators, permissões ou conditions.

Clique em Add e o tempo começará a correr, executando a automação no próximo CRON. Caso queira executar imediatamente, clique em “Run now”.

Tipo 4: Automações com Listeners

Você pode criar automações que serão disparadas automaticamente, quando algum evento acontecer no Jira. Esse também é um recurso do ScriptRunner e permite fazer coisas parecidas com as post-functions de workflow. Na verdade, a base dos Listeners são “escutar” (listen) eventos gerados por transições de estado, mas diferente das automações de workflow, você não cria em um workflow, mas de maneira global e genérica, o que é muito útil quando tem vários times com diferentes workflows mas uma automação e aplica a todos eles.

Para criar um listener, você deve:

1. Acesse Administration;
2. Add-ons;
3. Clique na opção Listeners, dentro da subseção ScriptRunner;
4. Clique em Create Listener;
5. Escolha um dos templates prontos ou a opção Custom Listener para adicionar um código Groovy personalizado, opção que vou usar aqui;

Preencha o formulário como segue:

• Note: o nome do listener;
• Project(s): um ou mais projetos que este listener vai ficar escutando eventos;
• Events: os eventos que vão disparar este listener. Você pode escolher eventos pré-definidos do Jira (que ele dispara sozinho) ou algum evento que você tenha criado manualmente e que dispare através de workflow post-functions ou de outras formas existentes;
• Inline script: seu código Groovy. Ele recebe um objeto event por padrão, com as propriedades do evento;
• Script file: opcional, permite dizer o caminho de um arquivo com o código Groovy dentro.

Clique em Add.

Um exemplo de código Groovy para listener pode ser visto abaixo. Neste exemplo, quando uma issue é resolvida (evento Issue Resolved) e ela está associada a um épico, ela propaga a sua informação de épico às issues de Service Desk (SDN) relacionadas à ela:

Tipo 5: Automações com e-mail

Você pode criar automações de e-mails que serão disparadas automaticamente, de tempos em tempos, baseada em consultas construídas por você (JQL). Esse é um recurso natural do Jira Software, embora com o Jira Service Desk também possa ser feito, como mencionado anteriormente.

1. Faça uma consulta qualquer (JQL) na caixa de pesquisa do Jira;
2. Salve a sua consulta, dando um nome à ela;
3. Clique em Details e selecione a opção New Subscription;

Configure a Subscription dessa forma:

• Recipients: quem vai receber essa assinatura de e-mails? Você pode enviar para grupos de pessoas;
• Schedule: qual a recorrência? Em Advanced você pode definir uma expressão CRON para a recorrência;
• “E-mail this filter…”: por padrão o resultado da consulta só é enviado por e-mail quando ele traz resultados. Marque se quiser receber um e-mail mesmo sem resultados na consulta.

Ao clicar em Subscribe, a automação de emails passará a funcionar.

Quer aprender a criar automações envolvendo outras aplicações da sua empresa? Confira este tutorial de WebHooks!

Espero ter ajudado!

Infelizmente eu não possuo um curso de Jira, mas caso se interesse por métodos ágeis em geral, dê uma conferida no meu curso online de Scrum e Métodos Ágeis clicando no banner abaixo.