# Jira

**A service offered by Pier Cloud that allows the platform to integrate with Jira Cloud for sending notifications through cards creation.**\
This integration provides visibility into project costs, resource usage, and enables the tracking of initiatives related to identified anomalies and triggered alerts.

### Connecting Jira to the Pier Cloud Platform

{% hint style="success" %}

#### Prerequisite:

* An active Jira Cloud account with administrative rights.
* Preferably, use a dedicated user account for this integration, with an email address that has the necessary permissions for the API operations you intend to perform.
* Below, we will provide tips for selecting the appropriate email address and the advantages of creating a dedicated user account for integration with our platform.
* The Jira project (board) that will receive the notifications must not contain mandatory fields required for creating issues. If this is unavoidable, we recommend creating a dedicated project exclusively for receiving notifications, where no required fields are enforced.
* Access to the Pier Cloud platform with the necessary permissions to configure and manage integrations.
  {% endhint %}

### In the Atlassian Environment

#### Step 1: Generate an API Token in Jira Cloud

1. Log in to your Jira Cloud account via: <https://id.atlassian.com/manage/api-tokens>
2. Go to **Account Settings** and select **Security**.
3. Under **API Tokens**, click **Create API Token**.

* Assign a descriptive name for easy identification,&#x20;
  * e.g., *Pier Cloud Notifications Integration*.
* Set an expiration date (cannot exceed 1 year).

4. Click **Create**.
5. A screen will appear with the API Token.&#x20;

* Click **Copy** and store it in a secure location.

6. Finally, click **Done** to exit.

{% hint style="warning" %}
Keep the token in a safe place — **it cannot be retrieved again** once the window is closed.
{% endhint %}

### In the Pier Cloud Environment

#### Step 2: Create a Secret

1. Click on the **user profile**, then select **Settings**, as shown below:

<figure><img src="https://1687673077-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ9sinLUl52lDK1vg6b8g%2Fuploads%2FCHGnCUyHOqrLdvbEFWZr%2Fimage.png?alt=media&#x26;token=7da4de41-e9f5-4322-842b-1e68047488bf" alt=""><figcaption></figcaption></figure>

2. The system will display a side menu with several configuration options. Select **Secrets**.

<figure><img src="https://1687673077-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ9sinLUl52lDK1vg6b8g%2Fuploads%2FdgJ6kfa9HrZwUEmLhM0a%2Fimage.png?alt=media&#x26;token=6479a0d2-be14-49bb-b35a-8032d7d32726" alt=""><figcaption></figcaption></figure>

3. Click **Add**, and the system will present the secret creation screen, where the following information must be provided:

<figure><img src="https://1687673077-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ9sinLUl52lDK1vg6b8g%2Fuploads%2FRNHaswO5z9mJXKjneb5Q%2Fimage.png?alt=media&#x26;token=36e7ce4a-4243-49ef-8d33-7a753769e461" alt=""><figcaption></figcaption></figure>

* **Name:** Assign a name to identify the secret.
* **Type:** Select *Jira Token*.
* **E-mail:** The email address linked to your Jira account used for creating the token.
* **Jira API Token:** Enter the API token created in Atlassian (Step 5 above).
* **Server URL:** The URL of your specific Jira Cloud instance. Copy the URL up to *.net*, as in the example below, and paste it here:\
  Example: `https://yourdomain.atlassian.net`

<figure><img src="https://1687673077-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ9sinLUl52lDK1vg6b8g%2Fuploads%2FpcCe21Tse6D477glvdxh%2Fimage.png?alt=media&#x26;token=f8e1e82f-16f2-4d53-bf54-cbe39c4c06d3" alt=""><figcaption></figcaption></figure>

4. Once all the information is filled in, click **Save** and proceed with the notification configuration.

#### Step 3: Registering the Provider in Notifications

1. From the side menu, select **Notifications** and click the "![](https://1687673077-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ9sinLUl52lDK1vg6b8g%2Fuploads%2FGhH2eTQSEu27Te2h88OM%2Fimage.png?alt=media\&token=4a99072b-b5af-4dad-bd2a-88e34f9a8e79)" icon corresponding to the desired notification group to return to the Jira provider registration.

<figure><img src="https://1687673077-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ9sinLUl52lDK1vg6b8g%2Fuploads%2FpyySj1AatjR6phRbdFJF%2Fimage.png?alt=media&#x26;token=f2b681a1-ebad-4bc8-a59d-bcd45492e11c" alt=""><figcaption></figcaption></figure>

2. The system will display the screen with registered providers and allow adding new ones by clicking **Add**.

<figure><img src="https://1687673077-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ9sinLUl52lDK1vg6b8g%2Fuploads%2Funq0mE8s5T4jGCfdVOFh%2Fimage.png?alt=media&#x26;token=04debd93-8e2b-4b8e-8abb-19fd17ac75d9" alt=""><figcaption></figcaption></figure>

3. The provider registration screen will be shown, where the following fields must be completed:

<figure><img src="https://1687673077-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ9sinLUl52lDK1vg6b8g%2Fuploads%2FqVWfHMP0Mg1jVmy2sYXG%2Fimage.png?alt=media&#x26;token=56f91ba4-6201-4aa3-8f22-71f23b488146" alt=""><figcaption></figcaption></figure>

* **Select type:** Jira
* **Name:** Enter a name to identify the provider

In **Settings**, the following additional fields must be completed:

* **Project ID or Key:** Enter the project (board) ID or key that will receive the notification in Jira. This is usually an acronym assigned to the project upon creation and can be found in project settings.
* **Issue Type:** Enter the type of issue to be created, exactly as it is named in Jira (e.g., *Task*).
* **Select the API Key Secret:** At this step, select the secret created in Step 2.

Finally, click **Save**. The configuration of notifications for Jira is now complete.

***

### How to Select the Appropriate Jira Email Address

* **Identification:** The Jira email address is an important identifier for your Jira Cloud user account, essential for authenticating and authorizing the connection between Pier Cloud and Jira.
* **API Authentication:** For API requests in Jira Cloud, such as creating an issue, authentication is required to verify the legitimacy and authorization of the request. This usually involves using an email address combined with an API token for basic authentication.
* **Integration Context:** The chosen email determines the specific Jira account with which the Pier Cloud platform will interact. Any action (such as creating or updating issues) executed by the platform will use the privileges and permissions of the associated Jira account.
* **Audit and Traceability:** Actions executed via API are usually logged by Jira. The email address can identify the account involved in these actions, supporting audit trails and troubleshooting.

{% hint style="success" %}
Ensure that the selected Jira email address has the necessary permissions for the intended API operations. For example, if your integration is designed to create issues, the Jira account linked to the email must have the necessary permissions to create issues in the designated project.
{% endhint %}

***

### Creating a Dedicated Service User in Jira Cloud

#### Step 1: Create a New User Account

* Access Jira user management.
* Create a new user, exclusively designated for the integration.
* Assign a clear name such as *integration\_service\_user* for easy recognition.

#### Step 2: Assign the Necessary Permissions

* Grant the new user the required permissions for tasks such as creating and managing issues.

{% hint style="warning" %}
Avoid granting administrative permissions unless strictly necessary.
{% endhint %}

***

### Advantages of Using a Dedicated User

* **Permission Control:** Simplifies permission management and auditing, keeping them isolated from real user accounts.
* **Stability and Continuity:** The integration is not tied to a specific employee’s account, ensuring continuity regardless of team changes.
* **Enhanced Security:** Reduces the risks of using personal accounts for integrations and maintains a clear separation between user activities and automated processes.
* **Audit Trails:** Any action executed by the integration is attributed to the dedicated service user, making tracking and auditing easier.

***

### Important Points to Consider

* **Regular Maintenance:** As with any account, ensure that the service user’s credentials are securely managed and that its permissions are reviewed regularly for updates.