# Jira Cloud

This user guide provides step-by-step instructions to integrate Jira with the ReleaseOwl Dashboard, enabling seamless project tracking, automation, and real-time visibility of Jira updates within ReleaseOwl. By following this guide, users can create an OAuth 2.0 integration, configure permissions, register Jira credentials in ReleaseOwl, and establish webhook connections to ensure a smooth data flow between the two platforms.

### 1. Sign in to the Atlassian Developer Account

1.  Go to the [Atlassian Developer Console](https://developer.atlassian.com/).
2. Log in using your **Atlassian** account credentials.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FpYycHwJ2WDdGv5KlGXce%2Fimage.png?alt=media&#x26;token=d3c6b1b1-35f2-47f6-b265-32fda46bc6cf" alt=""><figcaption></figcaption></figure>

### 2. Create an OAuth 2.0 Integration

1. Click on the **Developer Console** option.
2. Click on **Create** and select **OAuth 2.0 Integration** from the available options.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FCp3FAEWQZUc2Q1jDKwqY%2Fimage.png?alt=media&#x26;token=6101ba36-4d35-46c7-b3be-f97cd3dceef0" alt=""><figcaption></figcaption></figure>

### 3. Create an App

1. Enter a name for the app that reflects its purpose for Jira.
2. Check the box to agree to the terms and conditions.
3. Click on the **Create** button to proceed.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2Fq8D7xG8ldSpjokKBFmjr%2Fimage.png?alt=media&#x26;token=b97880a3-1b61-4dcc-9c77-98980f7cf208" alt=""><figcaption></figcaption></figure>

### 4. Add Permissions

1. After the app is created, go to the **Permissions** section.
2. Under **Jira API**, click **Add** to grant the necessary permissions. Once added, the button changes to **Configure** — click **Configure**.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FQc3wlTHAId2OU4fEOYJV%2Fimage.png?alt=media&#x26;token=95c52101-ee6a-45d9-b8c5-30c66f9d4005" alt=""><figcaption></figcaption></figure>

3. Select **Edit Scopes** to grant permissions for both **Classic Scopes** and **Granular Scopes**.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FGSJ0Km9mKfsn5GZZ5F8A%2Fimage.png?alt=media&#x26;token=d83d3fd9-a989-4877-abf7-173b14eceebb" alt=""><figcaption></figcaption></figure>

4. **Classic Scopes**: Select all scope names available under the **Jira Platform REST API**.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FApJGh7rHxfjHg5c4uuQ4%2Fimage.png?alt=media&#x26;token=8e1b8ccc-0daf-41dd-ba31-6aaab4146b34" alt=""><figcaption></figcaption></figure>

5. **Granular Scopes**: Enable the following permissions:

| **Scope**                                | **Description**                                                                  |
| ---------------------------------------- | -------------------------------------------------------------------------------- |
| **read:project:jira**                    | Read Jira project details                                                        |
| **read:field:jira**                      | Read fields in Jira                                                              |
| **write:field:jira**                     | Update fields in Jira                                                            |
| **read:field.option:jira**               | Read field options (e.g., dropdown values)                                       |
| **read:sprint:jira-software**            | Read sprints in Jira Software                                                    |
| **read:issue-details:jira**              | Read detailed issue information                                                  |
| **read:jql:jira**                        | Execute and validate JQL queries                                                 |
| **read:dashboard:jira**                  | Read dashboards                                                                  |
| **read:issue.transition:jira**           | Read available issue transitions                                                 |
| **read:board-scope.admin:jira-software** | Read board scope and configurations                                              |
| **read:issue:jira**                      | Read Jira issues                                                                 |
| **write:issue:jira**                     | Create and update Jira issues                                                    |
| **read:issue:jira-software**             | Read Jira Software issues                                                        |
| **read:status:jira**                     | Read all Jira statuses                                                           |
| **read:issue-status:jira**               | Read issue statuses                                                              |
| **read:filter:jira**                     | Read filters                                                                     |
| **read:issue-type:jira**                 | Read issue types                                                                 |
| **read:issue.property:jira**             | Read issue properties                                                            |
| **write:issue.property:jira**            | Write and update issue properties                                                |
| **read:issue-meta:jira**                 | Read issue metadata (e.g., create metadata)                                      |
| **read:board-scope:jira-software**       | Allows reading board scope details (e.g., filters/JQL that define board issues). |

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2F65KYOqpVu6kDuYTWYDRO%2Fimage.png?alt=media&#x26;token=7ce3df73-ea04-41f1-a04f-9eb9d8040d35" alt=""><figcaption></figcaption></figure>

### 5. Authorization Configuration

1. Go to the **Authorization** section.
2. Click on the **Add** button in the action item to set the authorization type.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FPGsDgYGEWNntH7XCs4YZ%2Fimage.png?alt=media&#x26;token=859a1d66-a36a-40f1-a0fb-36407d88d5fd" alt=""><figcaption></figcaption></figure>

3. For the **Callback URL**, enter:\
   <https://na3.releaseowl.com/rateloginserver/api/jira/accesstoken>
4. &#x20;Click on **Save Changes.**

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FUFQGXrqy1MAWF9ZIMBGb%2Fimage.png?alt=media&#x26;token=54de0ca5-7bcc-4f71-9b70-9e1aab681e9f" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Note:** In the OAuth framework, there are refresh tokens and access tokens. When the access token expires, a refresh token is used to obtain a new access token. The configuration must be set to send the refresh token when required. Since local URLs are not recognized due to intra-network restrictions, the callback URL uses the ReleaseOwl server (na3.releaseowl.com) to handle token exchange.
{% endhint %}

### 6. Copy ClientID and Secret

1. Go to **Settings** in the **Developer Console**.
2. Copy the **Client ID** and **Client Secret** for later use when registering Jira in the ReleaseOwl Dashboard.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FGn6biNMXSSR39dsIomvV%2Fimage.png?alt=media&#x26;token=5bf84352-5b7d-4d70-8e6f-209cf0f80341" alt=""><figcaption></figcaption></figure>

### **7. Registering Jira in ReleaseOwl Dashboard**

To integrate Jira with ReleaseOwl for issue tracking and traceability, follow the steps below to register Jira credentials and set up project integration.

#### **A. Registering Jira using OAuth2 Authentication**

1. Go to  the ReleaseOwl Dashboard.
2. Navigate to **Administration**, then select **Credential Manager**.
3. Click on **Register Credential**.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2Ffalxm87MOl6MyhH8CE6r%2Fimage.png?alt=media&#x26;token=3a3db40a-3e73-42ec-9f34-6e9ecde7ad8a" alt=""><figcaption></figcaption></figure>

4. Fill out the credential form with the following details:

* **Credential Name:** Enter your preferred name for the credential.
* **Credential Type**: Jira
* **Scope** – Select the scope of the credential:
  * **Global** – Visible to all users.
  * **Private** – Visible only to the user who created it.
* **Authentication Type**: Select the authentication type as theOAuth2
* **Client ID and Client Secret:** Paste the Client ID and Client Secret obtained from the OAuth2 integration you created in the Atlassian Developer Console.
* **Jira URL**:  <https://api.atlassian.com/>
* **Proxy Type**: Select None

5. Click **Save** to register the credential.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FfSeTKXaIkVIcCiBPiCso%2Fimage.png?alt=media&#x26;token=0486a5bd-c86c-46de-b865-444db0c56c5a" alt=""><figcaption></figcaption></figure>

6. After clicking the ***Save*** button, the ***Generate Token*** button will appear. Use this button to verify that the entered credentials are correct. If the token is generated successfully, the connection is validated.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FpCyN4U7d82R9aL5BSAVp%2Fimage.png?alt=media&#x26;token=edb91afa-c5a3-4ead-ab9a-15b0f69f6383" alt=""><figcaption></figcaption></figure>

#### **B. Registering Jira using Basic Authentication**

**Steps to Generate API Token in Jira**

1. Log in to your Jira account.
2. Go to Account Settings, then select Security.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FFAe60JNu3t4lsQtE8WQ9%2Fimage.png?alt=media&#x26;token=984fb6fb-6524-4a07-8b05-bffe26bae3a2" alt=""><figcaption></figcaption></figure>

3. Click on **Create and manage API tokens**.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2F8NkwpHonuiYh0VV45Taf%2Fimage.png?alt=media&#x26;token=d31130ea-40ec-45d2-8ba0-8af600b73b82" alt=""><figcaption></figcaption></figure>

4. Click Create API Token, provide a token name, and click **Create**.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FFw1zDgJcCxrWYb9r2oxQ%2Fimage.png?alt=media&#x26;token=6ee608ad-6b21-4548-9e67-897399893a52" alt=""><figcaption></figcaption></figure>

5. Copy the generated **API** token.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FS6iQPNQZnr5zd4LOW7aN%2Fimage.png?alt=media&#x26;token=905889a7-e9db-45a8-9937-b1fdd4b3724c" alt=""><figcaption></figcaption></figure>

**Register API Token in ReleaseOwl**

1. Open the ReleaseOwl Dashboard.
2. Navigate to Administration, then select **Credential Manager**.
3. Click on **Register Credential**.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FbE4NmF9jYdyybUbwOBgY%2Fimage.png?alt=media&#x26;token=de5b7706-2fa7-4a4a-b2eb-eebff9deeb5c" alt=""><figcaption></figcaption></figure>

4. Fill in the form with the following details:

* **Credential Name:** Enter your preferred name for the credential.
* Credential Type: Jira
* **Authentication Type:** Basic
* **Username:** Your Jira account username (usually an email address)
* **Password or API Token:** Paste the copied API token
* **Jira URL:**  <https://saparate.atlassian.net>
* **Proxy Type**: Select None

5. Click Save to register the credential.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FV2NXQDix7tPMr1iyWYgf%2Fimage.png?alt=media&#x26;token=e693dc89-4320-4c21-8a00-f7c9f7e50e4b" alt=""><figcaption></figcaption></figure>

### 8. Jira Project Integration&#x20;

To link a Jira project with a ReleaseOwl project, follow these steps:

**1. Navigate to Project Settings**

1. Switch to the required working project in **ReleaseOwl**.
2. Go to **Project Settings**.
3. In the **Project Settings**, navigate to **ALM Integrations** and click on **Add**.

#### **2. Fill in the Required Details**

* **Name**: Enter a unique name for the integration.
* **Description**: (Optional) Provide a description for reference.
* **External System**: Select **Jira** from the dropdown list.
* **Credential**: Select the registered Jira credential from the dropdown list.
* **Host URL**: The Jira server URL (e.g., `https://saparate.atlassian.net`).

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FlNU00a3eMmHVf53cWpGk%2Fimage.png?alt=media&#x26;token=c9944853-6e9d-43a5-8c28-df736b21f534" alt=""><figcaption></figcaption></figure>

#### **3. Select Hosting Type**

Under **Hosting Type**, choose **On-Premise** if your Jira instance is hosted on a private server rather than Atlassian’s cloud. Choose **Cloud** if your Jira instance is hosted on Atlassian’s cloud platform. You can then choose from the following options:

**A. Using Boards**

* **Select Boards** if you want to sync issues based on a specific Jira board.
* **External Project**: Select the Jira project you want to link with ReleaseOwl from the pop-up list.
* **Board**: Select the appropriate **Scrum** or **Kanban** board for the project.
* **Webhook URL**:
  * This URL is autogenerated by ReleaseOwl.
  * The Webhook URL is used to capture and sync events from Jira to ReleaseOwl.
* **Webhook Request URL for Automation Rule** :
  * This URL is autogenerated by ReleaseOwl.
* **Disable writing of comments/ notes:** You can turn off comments within ALM Integration.
* After entering all the integration details, click on the **Save** button.&#x20;

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2Fxbo4V1vEjPI6YbkwtuQK%2Fimage.png?alt=media&#x26;token=ca06a5e5-e03b-47de-b28f-46c30da693e5" alt=""><figcaption></figcaption></figure>

* Once saved, the integration will appear in the list, and if the **"Default Integration"** checkbox was selected, it will be marked as **Default**. This means the system will automatically use this integration unless another one is specified.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FJEYoimEuc7Q3MO0WxvKa%2Fimage.png?alt=media&#x26;token=608b05bc-f2b9-4410-b14f-dfb270a5e2c0" alt=""><figcaption></figcaption></figure>

**B. Using Filters**

* **Select Filters:** Use this option if you want to sync issues based on Jira's saved filters instead of boards or JQL querie&#x73;**. View all filters** available on the Jira board will also be visible in the user stories when filters are chosen.
* **External Project**: Choose the Jira project you want to link with ReleaseOwl.
* **Filters**:

  * Click on the dropdown or the filter selection icon.
  * A list of available Jira filters will be displayed.
  * Select the desired **saved filter** from Jira.
  * Ensure the selected filter has proper permissions and is shared with the required users.

  <figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2F3jLtRupG8zB7ZDPf3Vag%2Fimage.png?alt=media&#x26;token=0dca841b-1e7f-4588-90e7-06019cb955f3" alt=""><figcaption></figcaption></figure>

**C. Using JQL (Jira Query Language)**

* Select **JQL**, a powerful tool to fetch the details in Jira.
* **External Project**: Choose the Jira project you want to link with ReleaseOwl.
* **JQL Query**:

  * Create a JQL query in Jira that retrieves the required issues.
  * Copy and paste the JQL query into ReleaseOwl.

  <figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2F74ud4MKMtEf589d6Y3w1%2Fimage.png?alt=media&#x26;token=1eea630f-3660-4116-b6d9-7b06ddeb2025" alt=""><figcaption></figcaption></figure>

### 9. How to Configure Webhook URL

1. Log in to your Jira account.
2. Go to Settings and click on System.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FFURnvVrVaIvcJUmmgACZ%2Fimage.png?alt=media&#x26;token=fa467b2e-6b8f-481b-bfa4-1e3b983cf20b" alt=""><figcaption></figcaption></figure>

3. In the System section, navigate to General Configuration and click on Webhooks.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2F4xZrrSeh9KWuDrGXyMH1%2Fimage.png?alt=media&#x26;token=d0de0dba-ecfd-48d8-ab3a-e632272ec680" alt=""><figcaption></figcaption></figure>

4. This will take you to the webhook configuration page.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FaP7uxe3SqI8yKpUPLfw0%2Fimage.png?alt=media&#x26;token=af55aed3-d379-4d03-8099-11d5dad35d92" alt=""><figcaption></figcaption></figure>

5. Copy the **Webhook URL** that was generated in ReleaseOwl.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2F9XNysVhsKZxUiuDFyZuF%2Fimage.png?alt=media&#x26;token=97382b04-905c-4095-8d06-c05b5a4e376b" alt=""><figcaption></figcaption></figure>

5. Paste the copied URL in the Webhook configuration page in Jira.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FafTQoLc87E3uSwH629ns%2Fimage.png?alt=media&#x26;token=c6ce8ce5-c1d9-4d6d-bec8-ca2aa0c1d9a5" alt=""><figcaption></figcaption></figure>

7. Select the issue-related events that you want to track for your project (e.g., story creation, updates, etc.).

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FaNE9h72PSzCgnIMtXRh2%2Fimage.png?alt=media&#x26;token=1e83c422-a1e0-4df7-b352-415961abf734" alt=""><figcaption></figcaption></figure>

8. After entering all the details, you can enable or disable the webhook in the status section.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2Fk8V8p0AqJ4ANUtwOigYK%2Fimage.png?alt=media&#x26;token=34d12657-b057-415a-8145-d0b31074b9c0" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Note:** Further information on registering / configuring webhooks in JIRA can be found @ <https://developer.atlassian.com/server/jira/platform/webhooks/>
{% endhint %}

### **Integrating User Stories from Jira to ReleaseOwl**

ReleaseOwl is bidirectional, so the user stories created in Jira can be synced with ReleaseOwl and vice-versa.

To integrate user stories from Jira, follow these steps:

1. Navigate to the required Project.
2. In **Change Management**, select **User Stories** Menu
3. Click the **Sync User stories** icon.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FSGIFkrp52vsj0fjdpMFR%2Fimage.png?alt=media&#x26;token=c53c9d9e-d7ae-4285-a2b6-785003919807" alt=""><figcaption></figcaption></figure>

4. Once the sync is completed, you will get a pop up saying, **User Story Sync completed**.
5. Click **Ok**.

<figure><img src="https://1890383800-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDWyxe6hm5vqosFaByVgs%2Fuploads%2FH6myXYhhWJtZbILRHr0q%2Fimage.png?alt=media&#x26;token=402fbc29-00dc-4acc-a990-eafd7d73873f" alt=""><figcaption></figcaption></figure>