Explorando a API Rest Jira Cloud

Apresentação realizada na reunião de 26 de junho de 2019 do Atlassian User Group de São Paulo. Demonstração de como a interface REST dos produtos da plataforma Atlassian podem ser considerados como alternativas aos APPS e a tarefas manuais pela interface Web. Ao final há um exemplo onde a opção de utilizar a interface REST economizou tempo e dinheiro e entregou o trabalho feito

1. João galdino M. de souza | Senior Principal | Infosys consulting Explorando a API Rest Jira Cloud

2. Agenda Motivação Por onde começo? Autenticação Algumas chamadas interessantes Exemplo de uso

3. Introdução João Galdino M. de Souza Infosys Consulting Senior Principal Experiência como Jira Admin e uso de REST API no Jira software, Jira Service Desk e Apps em versão Server (Saraiva) e Jira Service Desk em versão cloud (Infosys)

4. Essa apresentação não é exaustiva sobre REST API e expõe algumas lições que aprendi utilizando esta interface

5. Motivação Usar API Rest, por quê?

6. Por que usar REST API? Adicione seu motivo pessoal aqui Curiosidade Nerd (como matar o tédio) “Preguiça” de executar tarefas manualmente Interagir de forma sistemática com o Jira Automatizar tarefas repetitivas Integrações entre instâncias diferentes de Jira com controle mais granular Economia em relação aos APPs No Jira Cloud não há acesso ao file system ou a Base de Dados

7. Por onde começo? Escolha suas armas ferramentas

8. Que cliente utilizar? Não se esqueça de Requisitos não funcionais Desempenho E scalabilidade Robustez Segurança Aplicativo ( Curl , SOAP UI ) ou programa (Java, C, Go, Java script, Powershell , Perl, etc)? Linguagem formal ou script? Pense na sua plataforma (SO, ambiente, etc) Pense em suas competências e habilidades

9. Espaço API REST do Jira

10. A API REST do Jira – Verifique qual utilizar

11. https ://developer.atlassian.com/cloud/ Documentação extensa e completa Lembre-se de acessar a versão que você está usando

12. Documentação APPS – google “<NOME APP> REST API JIRA” Nem sempre a documentação é boa e completa Tempo timesheet API

13. Autenticação/ Autorização Como me identificar?

14. Como me identificar? O usuário que será utilizado para o acesso via REST API deve possuir permissão para executar as ações necessárias no Jira Connect (para apps) OAUTH (para apps que não usam o connect e para REST) Basic authentication Diferente da versão Server, é necessário gerar um Token para ser utilizado como senha durante o processo de autenticação Se estiver usando a versão Server, utilizar o par usuário e senha normalmente

15. Gerando Token para uso em REST API https://id.atlassian.com/manage/api-tokens Acessar a URL acima com o usuário que fará os acessos REST Este token será utilizado como a senha do usuário em Basic Authentication

16. $ cred= get-credential -Message "Enter you username and password to access Jira Cloud" $user = $cred.username $pass = [Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($cred.password)) $pair = "$($user):$($pass)" $encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair)) $authorization = "Basic $encodedCreds " Lendo credencial de usuário Lendo usuário e senha Montando string para basic authentication Codificando com BASE64 Powershell

17. Em uma janela Powershell com o usuário que será utilizado o programa que fará uso da credencial criar um arquivo que irá armazenar a credencial criptografada PS C:\> read-host -assecurestring | convertfrom-securestring | out-file C:\ cred.txt No Programa que fará uso da credencial, pode-se ler a credencial criptografada com o seguinte commando PS C:\> $password = get-content C:\cred.txt | convertto-securestring Como armazenar credenciais Windows Armazenar Credenciais Windows Powershell Powershell

18. $ user = “username” $pass = get-content C:\cred.txt | convertto-securestring $pair = "$($user):$($pass)" $encodedCreds = [System.Convert]::ToBase64String ([System.Text.Encoding]::ASCII.GetBytes($pair)) $authorization = "Basic $encodedCreds " Utilizando credencial armazenada Lendo usuário e senha Montando string para basic authentication Codificando com BASE64 Powershell

19. Criando issues No Jira Core

20. Descobrindo os tipos de Issues que podem ser criados em um projeto There is a REST for that! Get create issue metadata GET /rest/api/3/issue/createmeta Parametros ProjectId=1000[,1000]* ProjectKeys=KEY1[,KEY2]* Retorno: Json com lista de Issuetypes

21. soap ui para testar as requisições em desenvolvimento Utilize SOAP UI para obter todos os IDs e informações para gerar as requisições necessárias Ex : ProjectIds , UserID , Issuetypes, customfields , etc Dica

22. ... " issuetypes ":[ { "self": "https://xxx.atlassian.net/rest/api/3/issuetype/10500", "id": " 10500 ", " description ": "Descrição do Issuetype ", " iconUrl ": "https://xxx.atlassian.net/...", " name ": " Investigation ", " subtask ": false }, ... Retorno Precisamos do id do issue type

23. { " fields ": { " project ": { " id": " 1000“ }, " summary ": "REST API Example Task 1", " issuetype ": { "id": “ 10500 “ }, " assignee ": { “id": “99:01902...” }, " reporter ": { “id": " 99:01902 ..." }, " priority ": { "id": "1 " }, " description ": " This is an example task created through the REST API." } } Criando Issue POST / rest / api /3/ issue JSON no corpo da requisição Após GPDR é necessário usar id do usuário e não username

24. { "id": "10000", " key ": "TST-24", "self": "http ://xxx.atlassian.net/rest/api/3/issue/10000 ", " transition ": { "status": 200, " errorCollection ": { " errorMessages ": [], " errors ": {} } } } Retorno JSON com Issue criada Sempre verifique os status e mensagens de erros

25. Adicionando comentários em uma issue

26. { " visibility ": { " type ": "role", " value ": "Administrators" }, " body ": { " type ": " doc ", " version ": 1, " content ": [ { " type ": " paragraph ", " content ": [ { " text ": " Lorem ipsum dolor sit amet , consectetur adipiscing elit . Pellentesque eget venenatis elit . Duis eu justo eget augue iaculis fermentum . Sed semper quam laoreet nisi egestas at posuere augue semper .", " type ": " text " } ] } ] } } Incluindo comentários POST / rest / api /3/ issue /< IssueKey >/ comment Parâmetros em JSON no corpo da requisição

27. Transições Como executar transições com REST API

28. { " expand ": " transitions ", " transitions ": [ { "id": " 111 ", " name ": " Finish coding ", "to": { "self": "https ://xxx.atlassian.net/rest/api/3/status/12019 ", " description ": "", " name ": " Ready for Review ", "id": "12019", " statusCategory ": { "self": "https ://xxx.atlassian.net/rest/api/3/statuscategory/4 ", "id": 4, " key ": " indeterminate ", " colorName ": " yellow ", " name ": "In Progress " } }, " hasScreen ": true , " isGlobal ": false, " isInitial ": false, " isConditional ": true }, Pesquisando transições disponíveis GET / rest / api /3/ issue /{ issueIdOrKey }/ transitions GET / rest / api /3/ issue /TST-24/ transitions RETORNO >

29. { " transition “: { "id": " 111 ", } } Pode ser necessário incluir outros campos na transição, de acordo com a configuração do workflow no Jira Executando transição POST / rest / api /3/ issue /{ issueIdOrKey }/ transitions POST / rest / api /3/ issue /TST-24/ transitions Parâmetros no JSON

30. Pesquisando Issues Usando JQL

31. { " expand ": [ " names ", " schema "," operations " ], " jql ": " project = TST", " maxResults ": 15, " fieldsByKeys ": false, " fields ": [ " summary ", "status", " assignee " ], " startAt ": 0 } Pesquisando issues com JQL POST / rest / api /3/ search Parâmetros de busca no corpo da requisição Paginação com campos StartAt e maxResults

32. Exemplo Colocando algumas chamadas para trabalhar para mim...

33. Fazer backup de todos os issues de um projeto incluindo os anexos A opção de compartilhar o resultado de um filtro em DOC exporta todo o conteúdo das issues, porém não exporta os anexos. Opções: Adquirir um APP que permita exportar os anexos Desenvolver um script que use API REST do Jira para exportar os anexos Entrar em cada um dos issues (413 no total) e fazer o download de todos os anexos (estimativa de ~8 horas) APP suportado na versão do Jira? (somente 4 de 10 para Cloud) APP faz a função desejada? Os apps pesquisados não fazia o download e sim colocavam links para download em um PDF

34. Escolhida Opção 2 Construir um programa para exportar todos os anexos via REST API

35. Pesquisar todos os issues do cliente usando JQL que devem ser exportados (fazer paginações para obter todos os issues) { " jql ": "project = \“XX\" AND issuetype != Monitoramento AND status not in ( Cancelado ) ORDER BY component", " maxResults ": 50, " fieldsByKeys ": false, "fields": [ "summary", "status", "assignee" ], " startAt ": 0 } JSON usado na pesquisa Paginação de 50 em 50 POST / rest / api /3/ search Retorno é um JSON com a lista de issues para a página

36. Pesquisar todos os issues do cliente usando JQL que devem ser exportados (fazer paginações para obter todos os issues) Paginação de 50 em 50, o JSON de retorno indica a quantidade de issues retornado, é esse o valor que precisa ser controlado p ara consumir toda o resultado da pesquisa, no caso será necessário executar 9 buscas para obter todas as issues

37. { " id": "43857", "self": "https ://xxx.atlassian.net/rest/ api /3/issue/43857 ", "key": “<ID>", "fields": {"attachment": [ { "self": "https ://xxx.atlassian.net/rest/ api /3/attachment/45231 ", "id": "45231", "filename": “nome_do_arquivo.pdf", " author": {…} " created": "2018-11-13T17:32:57.684-0200", "size": 44991, " mimeType ": "application/pdf", "content": " https :// xxx.atlassian.net/secure/attachment/45231/nome_do_arquivo .pdf " }, … JSON resultado (resumido para no slide) GET / rest / api /3/ issue /<ID>? fields = attachment DICA: Fazendo a consulta com o parâmetro fields é p ossível r estringir a resposta para c onter apenas o campo Attachments (economiza banda e processamento) Fazer uma consulta REST solicitando o campo attachment

38. "content": " https:// xxx.atlassian.net/secure/attachment/45231/nome_do_arquivo .pdf " "filename": “nome_do_arquivo.pdf" GET / rest / api /3/ attachment /<ID> Para cada anexo de cada issue, fazer o download Utilizando o endereço obtido no campo content de cada um dos attachments e o nome do arquivo original, pode-se fazer o download com um simples GET no endereço e renomear o objeto

39. Script finalizado ~75 linhas em P owershell 2.639 arquivos de 413 issues +800MB de anexos Execução em minutos

40. Lições aprendidas Entenda e desenhe o workflow de como funcionará a interação com a API Rest do Jira Cuidado para não automatizar apenas uma parte do workflow Utilize ferramenta como o SOAP UI para explorar as chamadas REST na fase de desenvolvimento Cuidado na Autenticação, autorização e permissões. Escolha bem qual usuário utilizar Atenção com novas versões do Jira, causam mudanças no comportamento da API REST (pouco comum mas com alto impacto) Atenção com a escolha do cliente que irá consumir a interface REST

41. João galdino M. de souza | Senior Principal | Infosys consulting Thank you!