# Jira

Um serviço oferecido pela Pier Cloud que permite integrar a plataforma com a ferramenta Jira Cloud para envio de notificações com abertura de cards. De forma a fornecer visibilidade sobre os custos dos projetos, o uso de recursos, com direcionamento de iniciativas referentes as anomalias identificadas e alarmes acionados.

### Conectando o Jira a Plataforma da Pier Cloud

{% hint style="success" %}
**PRE REQUISITO**:

* Uma conta ativa no **Jira Cloud**, com direitos administrativos.
  * Preferencialmente utilizar uma conta de usuário dedicado para essa integração, que possua endereço de email com as permissões necessárias para operações de API que deseja executar.
  * Mais abaixo iremos apresentar dicas para seleção do endereço de email apropriado e vantagens de criar uma conta de usuário dedicado para a integração com a nossa plataforma.
  * O projeto (board) no Jira que deseja receber as notificações, não deve possuir campos de preenchimento obrigatórios para abertura de cards. Caso seja necessário, nós recomendamos a criação de projeto dedicado para o recebimento das notificações, onde não existe a obrigatoriedade de preenchimento de nenhum campo.
* Acesso à plataforma da Pier Cloud, com as permissões necessárias para configurar e gerenciar integrações.
  {% endhint %}

### No ambiente da **Atlassian**

#### **Etapa 1: Gerar um token de API no Jira Cloud**

1. Acesse sua conta do **Jira Cloud** através do link: <https://id.atlassian.com/manage/api-tokens&#x20>;
2. Vá para **Configurações da conta** e selecione **Segurança**.
3. Em **Tokens de API**, clique em **Criar um token de API:**

* Atribua um nome descritivo para fácil identificação da sua API Token&#x20;
  * ex: `Integração Pier Cloud Notificações`
* Informe uma data de expiração, que não poderá exceder 1 ano.

5. Clique em **Criar**&#x20;
6. Será apresentada a tela para Copiar o Token de API

* Clique em **Copiar** e armazene o token em um local seguro

7. Por fim, clique em **Concluído**, para sair da tela.

{% hint style="warning" %}
Guarde o token em local seguro — ele **não poderá ser visto novamente** depois que você fechar a janela.
{% endhint %}

### No Ambiente da Pier Cloud

#### **Etapa 2: Criação do Segredo**

1. Clicando no perfil do usuário, na opção “**Configurações**”, conforme ilustrado abaixo:

<figure><img src="https://109632036-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcxn6hAOP0k8IqKSI8iRP%2Fuploads%2Fjuwj5agNed1e3ZYwwawd%2Fimage.png?alt=media&#x26;token=b44e7485-9ba2-46f1-9b50-c559cf50a16e" alt=""><figcaption></figcaption></figure>

2. O sistema apresentará o menu lateral com algumas opções de configuração, onde deve ser selecionada a opção “**Segredos**”:

<figure><img src="https://109632036-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcxn6hAOP0k8IqKSI8iRP%2Fuploads%2FSDhfty2x7kuQw69hfxyn%2Fimage%20(1).png?alt=media&#x26;token=a3f63acf-85b1-4be2-9cc8-9434c76fb56d" alt=""><figcaption></figcaption></figure>

3. Ao clicar na opção **Adicionar**, o sistema irá apresentar a tela para criação do segredo, onde devem ser inseridas as seguintes informações:

<figure><img src="https://109632036-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcxn6hAOP0k8IqKSI8iRP%2Fuploads%2FJxLdJiBVP2noA2GTTHSz%2Fimage.png?alt=media&#x26;token=1ee2bbcc-7ed8-48ff-b04a-e19ce6936d5c" alt=""><figcaption></figcaption></figure>

* **Nome**: Atribua um nome que identifique o segredo
* **Tipo**: Selecione o tipo **Jira Token**
* **Email:** O endereço de e-mail vinculado à sua conta Jira, utilizado para criação do token.
* **Jira API Token**: Insira o token de API criado no ambiente da Atlassian no passo 6.
* **URL do servidor**: A URL da sua instância específica do Jira Cloud. Copiar a URL até o .net, conforme exemplo abaixo, e colar aqui.
  * ex.: `https://seudominio.atlassian.net`

<figure><img src="https://109632036-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcxn6hAOP0k8IqKSI8iRP%2Fuploads%2FhOO0rIl1Aduo359JCwkc%2Fimage.png?alt=media&#x26;token=33fa361d-d786-4cf2-b6ba-453b2bf901d5" alt=""><figcaption></figcaption></figure>

4. Uma vez preenchida todas as informações, clique em **Salvar** e vamos continuar com a configuração da notificação.

#### **Etapa 3: Cadastro de provedor em Notificações:**

1. No menu laterial, selecione a funcionalidade de **Notificações** e clique no ícone "![](https://109632036-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcxn6hAOP0k8IqKSI8iRP%2Fuploads%2FVBfv8tfpzEXXbSvlWQyn%2Fimage.png?alt=media\&token=55aec71c-d6ab-47d3-b884-7e8fa81d3664)", correspondente ao grupo de notificação desejado, para retornar ao cadastro do provedor **Jira**:

<figure><img src="https://109632036-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcxn6hAOP0k8IqKSI8iRP%2Fuploads%2Fovimipkhb9n0pR6RSG58%2Fimage%20(2).png?alt=media&#x26;token=df53215f-e643-4f5a-a7d9-ae195a335b14" alt=""><figcaption></figcaption></figure>

2. O sistema irá apresentar a tela contendo os provedores cadastrados e possibilitando a inclusão de novos ao clicar no botão "**Adicionar**":

<figure><img src="https://109632036-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcxn6hAOP0k8IqKSI8iRP%2Fuploads%2FR6rtGtSnwfcg2DseIjrg%2Fimage.png?alt=media&#x26;token=42ddaa6c-97fe-4270-86b1-c0173e2a59c2" alt=""><figcaption></figcaption></figure>

2. O sistema irá apresentar a tela de cadastro do provedor, onde deveremos preencher os seguintes campos:

<figure><img src="https://109632036-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcxn6hAOP0k8IqKSI8iRP%2Fuploads%2FXp3r8uZjr6H9cYOxwkI2%2Fimage.png?alt=media&#x26;token=2d27dd2e-31c1-45e5-b675-a732f67f5207" alt=""><figcaption></figcaption></figure>

* **Selecione o tipo**: Jira
* **Nome**: Informar um nome que identifique o provedor

**Configurações**: Para o tipo de provedor **Jira**, será necessário preencher os seguintes campos adicionais:

* **ID ou Key do projeto**: Informar o ID ou chave do projeto (board) que irá receber a notificação no Jira.
  * Normalmente essa chave corresponde a uma sigla atribuída ao projeto na sua criação, podendo ser identificada na configuração do projeto.
* **Tipo de issue**: Informar o tipo de card que deve ser criado, conforme existente na abertura de um card no board do Jira. Escrever exatamente como estiver escrito no Jira.

  * Ex.: Bug

  <figure><img src="https://109632036-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcxn6hAOP0k8IqKSI8iRP%2Fuploads%2FyJslPk2csY8hn0DS77MW%2Fimage.png?alt=media&#x26;token=5bccbd2e-64e0-4787-9264-472ecbba2ac0" alt=""><figcaption></figcaption></figure>
* **Selecione o segredo da sua Api Key**: Nesse passo, iremos selecionar o segredo criado no passo 4.

Por fim, clique no botão **Salvar** e o está concluída a configuração das notificações para o Jira.

***

### Como selecionar o Endereço de E-mail Apropriado do Jira?

* **Identificação:**\
  O endereço de e-mail do Jira é um identificador importante da sua conta de usuário no Jira Cloud, essencial para autenticar e autorizar a conexão entre a plataforma da Pier Cloud e o Jira.
* **Autenticação da API:**\
  Para requisições de API no Jira Cloud, como a criação de um **issue** é necessária autenticação para verificar a legitimidade e a autorização da solicitação. Normalmente, isso envolve o uso de um endereço de e-mail combinado com um token de API para autenticação básica no Jira Cloud.
* **Contexto da Integração:**\
  O e-mail escolhido determina a conta específica do Jira com a qual a plataforma irá interagir. Isso é importante, pois qualquer ação (como criar ou atualizar issues) executada pela plataforma será realizada com os privilégios e permissões da conta Jira associada.
* **Auditoria e Rastreabilidade:**\
  As ações executadas via API geralmente são registradas pelo Jira. O endereço de e-mail pode ser usado para identificar a conta envolvida nessas ações, auxiliando em trilhas de auditoria e no diagnóstico de problemas.

Garanta que você selecione um endereço de e-mail do Jira que possua as permissões adequadas necessárias para as operações de API que pretende executar. Por exemplo, se a sua integração tem como objetivo criar issues, a conta Jira vinculada ao e-mail deve ter as permissões necessárias para criar issues no projeto Jira designado.

***

### **Criar um usuário de serviço dedicado no Jira Cloud**

**Etapa 1: Criar uma nova conta de usuário**

* Acesse a seção de **gerenciamento de usuários** no Jira.
* Crie um novo usuário, designado exclusivamente para a integração.
* Forneça um nome claro, como `integration_service_user`, para fácil reconhecimento.

**Etapa 2: Atribuir as permissões necessárias**

* Conceda ao novo usuário as permissões necessárias para tarefas como criação e gerenciamento de issues.

{% hint style="warning" %}
**Atenção:** evite conceder permissões administrativas, a menos que seja realmente necessário.
{% endhint %}

***

### **Vantagens de utilizar um usuário dedicado**

* **Controle de Permissões:** facilita o gerenciamento e auditoria de permissões, mantendo-as isoladas de contas de usuários reais.
* **Estabilidade e Continuidade:** a integração não fica vinculada à conta de um colaborador específico, garantindo continuidade independentemente de mudanças na equipe.
* **Segurança Aprimorada:** reduz os riscos de usar contas pessoais para integrações e ajuda a manter uma separação clara entre atividades de usuários e processos automatizados.
* **Trilhas de Auditoria:** qualquer ação executada pela integração é atribuída ao usuário de serviço de integração, facilitando o rastreamento e a auditoria.

***

### **Pontos importantes a considerar**

* **Manutenção Regular:** como qualquer conta, garanta que as credenciais do usuário de serviço sejam gerenciadas com segurança e que suas permissões sejam revisadas regularmente para eventuais atualizações.