dehatanes/superpower-jira-report-creator-at-notion

Command line para extrair screenshots e dados do Jira para *automagicamente* criar um relatório da sprint ✨

Superpower Jira Report Creator at Notion

Language	Python 3.8
External API	Notion API - 2022-06-28 version
	Jira API

Um comando poderoso para extrair screenshots e dados do Jira para automagicamente criar um relatório de sprint no notion - no seu database de preferência ✨

1. O que esse comando faz afinal?

todo

2. Setup

Instalando dependências

Uma vez que o projeto está instalado no seu computador, vá para a pasta dele no terminal e instale as dependências do projeto usando o comando:

pip3 install -r requirements.txt

Configurando variáveis de ambiente do Notion

Para a cli funcionar, você precisa adicionar algumas variáveis de ambiente no seu terminal. Para isso rode os comandos a seguir alterando o que está depois de = por seus respectivos valores:

• Troque <your_notion_workspace_url> pela url do seu workspace (tem a carinha https://www.notion.so/nome_aquii/)
• Troque <your_notion_api_key> pelo token que você recebe ao configurar uma nova integração no Notion.
• Troque <your_notion_database_id> pelo id do "database de atas" que você deseja inserir a nova ata criada pela cli.
• Troque your_notion_template_page_id> pelo id de uma página que tem o conteúdo que você quer usar de template e copiar para a nova página que criar.

export NOTION_BASE_URL=<your_notion_workspace_url>
export NOTION_API_KEY=<your_notion_api_key>
export NOTION_DATABASE_ID=<your_notion_database_id>
export NOTION_TEMPLATE_PAGE_ID=<your_notion_template_page_id>

Configurando variáveis de ambiente do Jira

Ainda não acabou. No mesmo esquema das variáveis acima, você também vai precisar de algumas relacionadas ao Jira para que isso aqui possa funcionar. Rode os comandos a seguir alterando o que está depois de = por seus respectivos valores:

• Troque <your_jira_workspace_name> pelo nome do seu workspace (você encontra ele na url do seu jira - é o nominho que fica entre o https:// e .atlassian.net)
• Troque <your_jira_dashboard_id> pelo id da sua dash do jira (é o último número na url da sua dashboard tipo https://{{your_jira_workspace_name}}.atlassian.net/jira/dashboards/<AQUI>)
• O valor de <your_jira_cloud_session_cookie> é mais chatinho de encontrar. Você precisa:
  • Estar logado no Jira através de um browser
  • Pegar os cookies do seu browser
  • Separar o valor do cookie chamado cloud.session.token e usá-lo aqui (é uma string grandinha mesmo)

export JIRA_WORKSPACE_NAME=<your_jira_workspace_name>
export JIRA_DASHBOARD_ID=<your_jira_dashboard_id>
export JIRA_CLOUD_SESSION_TOKEN=<your_jira_cloud_session_cookie>

Configurando variáveis de ambiente da AWS

Para conseguirmos salvar os screenshots do Jira e salvá-los no Notion, precisamos de um bucket da AWS que seja publicamente acessível. Então para isso:

• Crie seu bucket e um usuário com acesso a ele (você pode usar esse tutorial da aws para isso
• Configure sua máquina com as infos do seu usuário para que as requisições para os serviços da aws consigam ser autenticadas, você pode usar esse tutorial para isso.
• Com o nome do buscket que criou em mãos, configure essa variável de ambiente substituindo o valor de <your_bucket_name>:

  export BUCKET_NAME=<your_bucket_name>

3. Como usar

Para usar basta estar na pasta do projeto e rodar o comando:

python3 -m report_creator.main

E esperar a mágica acontecer :)

4. Referências legais para fazer algo parecido

• Meu outro repo: dehatanes/super-useful-notion-cli

---

Made with ❤️ by @dehatanes & @thomasdoconski

superpower-jira-report-creator-at-notion's Issues

Adicionar tratativa de erros de geração da página do Notion

Hoje no notion_adapter.py está responsável por capturar as informações necessárias para poder montar a página do Notion com o relatório da Sprint. Esse adapter não possui algumas tratativas de erro para os casos da API não retornar as informações das páginas e banco de dados necessários, ou de erros vinculados a criação da página nova para o relatório.

• Atualmente se a página não é criada isso gera um stacktrace por não conseguirmos acessar o id da pág.

Objetivo dessa issue é adicionar as tratativas pertinentes para dar um feedback de algum erro de acesso a API ou de configuração do adaptador que acessa ela.

• O ideal seria informar ao usuário que a página não pôde ser criada e guardar um log dos erros.

Verificar a captura e expiração do Token JIRA

Verificar se o Token do JIRA expira e criar uma maneira de capturar o token sem precisar manualmente setar como varíavel de ambiente toda a vez que for rodar o projeto.

Verificar se um report já foi criado no dia antes de criar um novo

Adicionar uma verificação para se já existir um report do notion para aquele dia, nós sobrescrevermos o conteúdo dele ao invés de criar uma nova pág.

Permitir que a imagem adicionada a página do Notion seja hospedada no Notion

O código atual usa a API do Notion para poder subir a imagem que teve upload na S3.
Se essa imagem ficar indisponível ou se ela for sobrescrita, a imagem que está no relatório gerado pelo código será alterada também, já que a API faz referência a imagem pelo link original.
Hoje, pela a API do Notion, não é possível fazer o upload da imagem, como pode ser visto na documentação do próprio Notion.

Externally hosted files vs. Files hosted by Notion
For files and URLs hosted outside of Notion, we support retrieving the link as well as updating it to a different link. We don't currently support uploading files to Notion through the API, however, for files already uploaded to Notion, we support retrieving the file URL. The table below details what's supported for Embed, Image, Video, Audio, and File blocks, as well as page icon and page cover image properties.
https://developers.notion.com/reference/file-object

A proposta é que se crie uma maneira automatizada, talvez pelo Selenium mesmo, que adicione a imagem capturada a nova página de relatório criada, de modo que ela fique hospedada no Notion e não corra risco de alterações.

Capturar o sprint report do JIRA

No layout template do report de review do JIRA, um dos tópicos pertinentes para armazenamento e checagem da sprint é o relatório Sprint Report. O intuito é adicionar o screenshot desse relatório a página do Notion criada na sessão correspondente.
Ele pode ser acessado através do link :

https://{{jira_workspace}}.atlassian.net/jira/software/c/projects/{{jira_project_id}}/boards/{{jira_board_id}}/reports/sprint-retrospective?sprint={{jira_sprint_id}}

No link acima:

• jira_workspace é a instância do JIRA, environment variable JIRA_WORKSPACE_NAME
• jira_project_id é a sigla do projeto que se quer extrair o relatório de sprint
• jira_board_id é o id do board do projeto que se quer extrair o relatório de sprint
• jira_sprint_id é o número da sprint.

No caso do Board e Sprint, talvez haja uma maneira de capturar pela API do próprio JIRA, tentando descobrir qual o board padrão e qual a sprint ativa.

Caso o link acima não esteja disponível (isso pode acontecer pois a versão Team Managed e Company Managed do JIRA Cloud possuem relatórios diferentes) uma alternativa para o relatório de Burndown seria o link:

https://{{jira_workspace}}.atlassian.net/jira/software/projects/{{jira_project_id}}/boards/{{jira_board_id}}/reports/burndown

❕ Validar os comportamentos dos dois links

Permitir os inputs de algumas informações ao invés de env var

A gente hoje tem algumas envinronment variables para capturar algumas informações, mas acho que algumas dessas infos poderiam ser feitas com input no console.
Talvez com o workspace, tenha como consultar os projetos.
Consultando os projetos, acho que talvez dê para consultar os boards, sprints e etc.
Além de descobrir se o projeto é Team Managed ou Company Managed. (Essa parte é especialmente útil para descobrir comportamentos diferentes do Jira Cloud).

Adicionar ao README quais as versões que estamos utilizando

A gente está usando algumas integrações com as API's e versões do Jira.
Acho que seria legal colocar qual a versão do JIRA, qual a versão da API do Notion e qual a versão da API do JIRA (depois), porque aí fica mais definida a compatibilidade.
Não sei se tem alguma outra versão que é pertinente.

Adicionar o template JSON ao projeto como resource

Como a gente usa um template específico, acho que seria legal adicionar o template da página para que qualquer um que pegue esse projetinho consiga reproduzir o mesmo resultado com um JIRA + Notion.

Tratar erros quando a página do Notion não é criada corretamente

Atualmente se a página não é criada isso gera um stacktrace por não conseguirmos acessar o id da pág.

O ideal seria informar ao usuário que a página não pôde ser criada e guardar um log dos erros.

Adicionar informações das tarefas nas subseções do relatório no Notion

Objetivo dessa issue é popular as 3 sub seções do relatório com informações pertinentes da Sprint:

1. Na seção para "Destaques" onde ficam as histórias, tarefas e bugs principais da Sprint que foram finalizados.
   Para recuperar as informações da sprint vigente usando a sintaxe interna do JIRA (JQL), podemos fazer a seguinte pesquisa:
   project = "{{jira_project_id}}" AND issuetype in ({{issueTypes}}) AND sprint in openSprints() AND statusCategory = Done ORDER BY issueType

• jira_project_id - Referente a sigla do projeto.
• issueTypes - Refere-se a uma lista predefinida de tipos de tarefas que se enquadram como mais importantes, por exemplo: Stories, Tasks, Bugs.

2. Na seção para "Refinamentos" onde ficam as issues de Refinamento (tipo customizado) que foram finalizadas.
   Para recuperar as informações da sprint vigente usando a sintaxe interna do JIRA (JQL), podemos fazer a seguinte pesquisa:
   project = "{{jira_project_id}}" AND issuetype in ({{refiningType}}) AND sprint in openSprints() AND statusCategory = Done ORDER BY issueType

• refiningType - Refere-se ao tipo customizado para Refinamento.

3. Na seção para "Cards não finalizados" onde ficam todas as atividades não finalizadas da sprint.
   Para recuperar as informações da sprint vigente usando a sintaxe interna do JIRA (JQL), podemos fazer a seguinte pesquisa:
   project = "{{jira_project_id}}" AND sprint in openSprints() statusCategory != Done ORDER BY issueType

Colocar as atividades que entraram e saíram da Sprint

Descobrir como capturar a informação das atividades no JIRA que entraram e saíram da Sprint ativa e adicionar a lista das atividades na seção de "Alterações de Escopo".