# Jira Cloud Destination ## Overview Destinations are integrations that receive alerts from rules, policies, system health notifications, and rule errors. Panther supports configuring Jira as the destination where you will receive alerts. When an alert is forwarded to a Jira destination, a bug, story, or task is created in the specified project with the specified assignee. You can choose to sync status updates, assignees, and comments between Panther alerts and their corresponding Jira issues in [either one or both directions](#one-way-sync-vs.-two-way-sync). This page explains how to set up a Jira Cloud destination. See the [instructions for Jira Data Center here](https://docs.panther.com/alerts/destinations/jira-data-center). ### One-way sync vs. two-way sync With the Jira alert destination in Panther, you can enable one-way sync or two-way sync for assignee, status, and/or comments. * **One-way sync (Panther > Jira)**: When the status or assignee is updated or a comment is created on a Panther alert, the same change in status, assignee, or comment is made on the corresponding Jira issue. * **Two-way sync**: In addition to the one-way sync functionality, when the status or assignee is updated or a comment is created or updated on a Jira issue that was created by a Panther alert, the same change in status, assignee, or comment is made on the corresponding Panther alert. {% hint style="warning" %} When setting up Jira Cloud destinations, note that: * It is possible to: * Set up multiple Jira Cloud destinations with one-way sync (linking to the same or different Jira projects in the same or different Jira tenants). * Set up a single Jira Cloud destination with two-way sync and one or more Jira Cloud destinations with one-way sync (linking to the same or different Jira projects in the same or different Jira tenants). * It is not recommended to: * Set up multiple Jira Cloud destinations with two-way sync that are linked to different projects within different Jira tenants. This configuration may cause an infinite loop of syncing. * It is not possible to: * Set up multiple Jira Cloud destinations with two-way sync that are linked to different projects within the same Jira tenant. This configuration causes an infinite loop of syncing. * Set up a single Jira Cloud destination with two-way sync that is linked to multiple Jira projects. {% endhint %} ## How to set up Jira alert destinations in Panther ### Prerequisites #### Prerequisite for two-way sync To enable two-way sync, you must first install the [Panther Cloud Sync](https://developer.atlassian.com/console/install/2046053e-4810-4dc6-a6ab-42b11eff3de7?signature=AYABeDBvFQaQV4%2FLY0dduoQJpO8AAAADAAdhd3Mta21zAEthcm46YXdzOmttczp1cy1lYXN0LTE6NzA5NTg3ODM1MjQzOmtleS83ZjcxNzcxZC02OWM4LTRlOWItYWU5Ny05MzJkMmNhZjM0NDIAuAECAQB4KZa3ByJMxgsvFlMeMgRb2S0t8rnCLHGz2RGbmY8aB5YBaNb0LU%2F6xBUNZ1CsWoYMjwAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDM%2FzlVgoA6hXuBUzEgIBEIA7J7JwulJA1Pp8sS3g7tTTRAiFtKM3Oi6DGfsY1s%2Bo7rCFsGPlnXmIad6h64yejrXbkeBypIEurZch%2BAsAB2F3cy1rbXMAS2Fybjphd3M6a21zOmV1LXdlc3QtMTo3MDk1ODc4MzUyNDM6a2V5LzU1OWQ0NTE2LWE3OTEtNDdkZi1iYmVkLTAyNjFlODY4ZWE1YwC4AQICAHhHSGfAZiYvvl%2F9LQQFkXnRjF1ris3bi0pNob1s2MiregE9RoiqESDHTxen7Z5hSRHTAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMVLm%2Bjur6rpcP%2B%2FmYAgEQgDsGCr6Ccz9S5M2Yg5TsxpDlSgUDm0GAclFY8RvvW43ioWxdZqqVGGXvfcbeivfJ9NUUu%2F9Uo0vbDkjjpAAHYXdzLWttcwBLYXJuOmF3czprbXM6dXMtd2VzdC0yOjcwOTU4NzgzNTI0MzprZXkvM2M0YjQzMzctYTQzOS00ZmNhLWEwZDItNDcyYzE2ZWRhZmRjALgBAgIAePadDOCfSw%2BMRVmOIDQhHhGooaxQ%2FiwGaLB334n1X9RCAZWc9xDiygfLLBvu5HZpgg4AAAB%2BMHwGCSqGSIb3DQEHBqBvMG0CAQAwaAYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAyV9A%2ByCyT6%2BDC1HDsCARCAO7KBKoaIkjh8BFlqCQ3adXS525SFufEb4o6eErs%2BzjtaS3N10krDQ2STQnaE4vNGcIDGd2V6uJ32HWC%2FAgAAAAAMAAAQAAAAAAAAAAAAAAAAAB%2BBnSuiuS1DJglQZKNnaeb%2F%2F%2F%2F%2FAAAAAQAAAAAAAAAAAAAAAQAAADJpYTVm6n%2BEWAxAHb1%2B16ajeg%2FRV%2FCb7O0kEIUc%2FamKrdAgb8XwxYcfVXQCjYLsMew5bHEuyEQAYcQIjx6VuMAB3UU%3D\&product=jira) app in your Atlassian instance, which will allow Panther to receive updates to Jira issues Panther created. Panther will not receive updates for issues that were not created by Panther. To install Panther Cloud Sync: 1. On the [Panther Cloud Sync page](https://developer.atlassian.com/console/install/2046053e-4810-4dc6-a6ab-42b11eff3de7?signature=AYABeDBvFQaQV4%2FLY0dduoQJpO8AAAADAAdhd3Mta21zAEthcm46YXdzOmttczp1cy1lYXN0LTE6NzA5NTg3ODM1MjQzOmtleS83ZjcxNzcxZC02OWM4LTRlOWItYWU5Ny05MzJkMmNhZjM0NDIAuAECAQB4KZa3ByJMxgsvFlMeMgRb2S0t8rnCLHGz2RGbmY8aB5YBaNb0LU%2F6xBUNZ1CsWoYMjwAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDM%2FzlVgoA6hXuBUzEgIBEIA7J7JwulJA1Pp8sS3g7tTTRAiFtKM3Oi6DGfsY1s%2Bo7rCFsGPlnXmIad6h64yejrXbkeBypIEurZch%2BAsAB2F3cy1rbXMAS2Fybjphd3M6a21zOmV1LXdlc3QtMTo3MDk1ODc4MzUyNDM6a2V5LzU1OWQ0NTE2LWE3OTEtNDdkZi1iYmVkLTAyNjFlODY4ZWE1YwC4AQICAHhHSGfAZiYvvl%2F9LQQFkXnRjF1ris3bi0pNob1s2MiregE9RoiqESDHTxen7Z5hSRHTAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMVLm%2Bjur6rpcP%2B%2FmYAgEQgDsGCr6Ccz9S5M2Yg5TsxpDlSgUDm0GAclFY8RvvW43ioWxdZqqVGGXvfcbeivfJ9NUUu%2F9Uo0vbDkjjpAAHYXdzLWttcwBLYXJuOmF3czprbXM6dXMtd2VzdC0yOjcwOTU4NzgzNTI0MzprZXkvM2M0YjQzMzctYTQzOS00ZmNhLWEwZDItNDcyYzE2ZWRhZmRjALgBAgIAePadDOCfSw%2BMRVmOIDQhHhGooaxQ%2FiwGaLB334n1X9RCAZWc9xDiygfLLBvu5HZpgg4AAAB%2BMHwGCSqGSIb3DQEHBqBvMG0CAQAwaAYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAyV9A%2ByCyT6%2BDC1HDsCARCAO7KBKoaIkjh8BFlqCQ3adXS525SFufEb4o6eErs%2BzjtaS3N10krDQ2STQnaE4vNGcIDGd2V6uJ32HWC%2FAgAAAAAMAAAQAAAAAAAAAAAAAAAAAB%2BBnSuiuS1DJglQZKNnaeb%2F%2F%2F%2F%2FAAAAAQAAAAAAAAAAAAAAAQAAADJpYTVm6n%2BEWAxAHb1%2B16ajeg%2FRV%2FCb7O0kEIUc%2FamKrdAgb8XwxYcfVXQCjYLsMew5bHEuyEQAYcQIjx6VuMAB3UU%3D\&product=jira), click **Get app**. 2. Under **Select a site to install this app on**, choose the Jira instance for which you would like to enable Panther two-way sync. 3. Click **Install**. * You will finish configuring this app after configuring the Jira alert destination in Panther. #### Prerequisite for one-way or two-way sync of assignees If you plan to enable one-way or two-way assignee sync, each of your organization's users who will be assigned to Jira issues created by Panther alerts must make their email available to installed apps in Jira. Each of these users should complete the process below: 1. In your Atlassian console, visit the [**Profile and visibility** tab within your account settings](https://id.atlassian.com/manage-profile/profile-and-visibility). 2. Scroll down to the **Contact** section. 3. For your email address, set the **Who can see this?** value to **Anyone**.\ ![](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-ad4367c57f41a4f9b697468e9bd7871d24b5e30d%2FScreenshot%202024-01-31%20at%204.37.50%20PM.png?alt=media) ### Step 1: Create a Jira API key {% hint style="info" %} You (the user generating this API key) will be displayed as the actor making the update when Panther performs an action in Jira (i.e., creates an issue, updates the assignee, status, or comments). {% endhint %} 1. Log in to your Atlassian account and navigate to the [API Token management page](https://id.atlassian.com/manage/api-tokens). 2. Click **Create API Token**, add a descriptive label, and click **Create**:\ ![The Token Management page in an Atlassian account is open. There is a popup dialog labeled "Create an API Token." It contains a "Label" field and the words "Jira API Key" are typed into it. There is a blue Create button at the bottom.](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-f7c4d0115155c7ab23315bd3c5f575fcef5934bc%2Fjira-key1.png?alt=media) 3. Click **Copy** and store the token in a secure location. * Note: The token is sensitive information and you will not be able to view it again. ### Step 2: Configure the Jira alert destination in Panther 1. In the left-side navigation bar of your Panther Console, click **Configure > Alert Destinations**. 2. Click **+Add your first Destination**. * If you have already created Destinations, click **Create New** in the upper right side of the page to add a new Destination. 3. Click **Jira Cloud**. 4. Fill out the form: * **Display Name**: Enter a descriptive name. * **Organization Domain**: Enter your organization's Jira domain. * For example: . * **Issue Type**: Enter the Issue type from Jira. This can be Bug, Story, Task, or any custom type. * **Project Key**: Enter the project identifier within your organization. You can find this in Jira in your project settings page or by browsing [your organizations' Jira projects](https://example.atlassian.net/projects) and locating the `key` column. * **Email**: Enter the email address of the Jira user who has permissions to create and delete the new issues with the corresponding Jira API Key. * **Jira API Token**: Enter the API token you generated in the earlier steps of this documentation. * **Severity Levels**: Select the severity level of alerts to send to this Destination. * **Default Alert Types**: Select the alert types to send to this Destination. * **Log Types**: By default, we will send alerts from all log types. Specify log types here if you want to only send alerts from specific log types. * **Allow Manual Dispatch**: Set this toggle ON if you'd like to be able to [manually dispatch alerts](https://docs.panther.com/alerts#manual-alert-dispatch) to this destination. 5. In the **Syncing Options** section, make a selection for each of the following:\ ![Under a "Syncing Options" header, there are three fields: Alert Status, Assignee, and Comments. Each field has three options: Do not sync, One-Way, and Two-Way](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-366c85a6a3ad8fd5303e8d07c1256187af593fac%2FScreenshot%202024-02-01%20at%202.19.31%20PM.png?alt=media) * **Alert Status**: * **Do not sync**: Updates to the status of an alert in Panther will not be reflected on the corresponding Jira issue, and vice versa. * **One-Way**: When the status of an alert is changed in the Panther Console or [Slack Bot](https://docs.panther.com/alerts/destinations/slack-bot), or via the [Panther API](https://docs.panther.com/panther-developer-workflows/api/graphql/alerts-and-errors), the status of the corresponding Jira issue is also updated. * Any alert status changes made in Panther will also be added as a comment on the associated Jira issue. * If you have custom transition rules in your Jira project workflows, Panther may not be able to transition the ticket from one status to the next. It is important that all Jira statuses are able to be transitioned from any other Jira status. This can be configured in the corresponding Jira project's workflow settings. * **Two-Way**: In addition to the one-way functionality described above, if the status of a Jira issue is updated, the status of the corresponding Panther alert will also be updated. * **Assignee:** * **Do not sync**: Updates to the assignee of an alert in Panther will not be reflected on the corresponding Jira issue, and vice versa. * **One-Way**: When the assignee of a Panther alert is updated (in the Panther Console or via the [Panther API](https://docs.panther.com/panther-developer-workflows/api/graphql/alerts-and-errors)), the assignee of the corresponding Jira issue is also updated. * The Panther alert and Jira issue assignees are matched by email address. If the email address associated to the Panther account cannot be found in Jira (either because it does not exist or [has not been made visible, as described in the Prerequisites](#prerequisites)), an update to the Jira issue will not be performed. * Currently, updates to the alert assignee in a Panther [Slack Bot](https://docs.panther.com/alerts/destinations/slack-bot) do not sync to the associated Jira issue. * **Two-Way**: In addition to the one-way functionality described above, if the assignee of a Jira issue is updated, the assignee will also be updated on the Panther alert, as long as there is a Panther user with a matching email address. * **Comments**: * **Do not sync**: Comments left on an alert in Panther will not be reflected on the corresponding Jira issue, and vice versa. * **One-Way**: When a comment is posted on a Panther alert (in the Panther Console or via the [Panther API](https://docs.panther.com/panther-developer-workflows/api/graphql/alerts-and-errors)), the comment is also posted on the corresponding Jira issue. * When a comment posted on an alert in Panther is synced to the corresponding Jira issue, the comment text is prepended with "\[Panther user] commented on Panther:" * When syncing a comment from Panther to Jira, Panther tries to maintain the original formatting so that comments look identical. In rare cases, due to conversion limitations, the comment may be formatted differently—without a loss of content. * **Two-Way**: In addition to the one-way functionality described above, if a comment is posted on a Jira issue, the comment will also be posted on the Panther alert. * When a comment posted on a Jira issue is synced to the corresponding Panther alert, the comment text is prepended with "\[Jira user] commented on Jira:" * When a comment on a Jira issue is edited, the comment on the Panther alert will be edited. * There are some limitations to comment formatting in Panther. See [Comment formatting in Panther](#comment-formatting-in-panther) for more information. 6. Click **Continue**. ### Step 3: Configure Jira issue properties On the **Configure Jira Issue Properties** page, fill out the form: * **Assignee ID**: Select the user that issues will be assigned to. * The users available in this dropdown field are pulled from your Jira instance. * **Label and prioritize issues based on severity level**: Enable this if you would like to apply labels and a priority level in Jira based on alert severity in Panther. If disabled, you can still set labels and a priority level globally i.e., not based on severity). The labels and priority levels available in these dropdown are pulled from your Jira instance. If you create a new label in the **Labels** dropdown, it will also be created in your Jira instance. * If set to **ON**: For each severity level, specify the **Labels** and **Priority**.
A toggle near the top says "Label and prioritize issues based on severity level." Below, various severities have an associated Labels an Priority field.
* If set to **OFF**: Specify the **Labels** and **Priority** for all Jira issues created by Panther.
### Step 4: Configure Panther/Jira syncing 1. (Only if you enabled one-way or two-way status syncing) On the **Status Syncing** page, map the Panther alert statuses to the corresponding statuses you'd like to use in Jira. * Click **Save Changes**.\ ![Under a "Status Syncing" header, there are two columns: Panther Alert Statuses and Jira Alert Statuses. Each column value in the former points to a value in the latter.](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-683ad4d6ade06b3e3da2cac2c9a4350582d9edb4%2FScreenshot%202024-10-18%20at%204.37.17%E2%80%AFPM.png?alt=media) 2. (Only if you enabled two-way sync for alert status, assignee, or comments) On the **Two-Way Sync** page, copy the **Panther Instance URL** and **API Token** and store them in a secure location, as you will need them in the next step. The API Token will not be shown to you again. * Click **Continue**.\ ![A "Two-Way Sync" page displays two values a Panther Instance URL and API Token. Below these is a Continue button.](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-d7d8aaa3ef67cd66d4b1115ca176c982b6f04b70%2FScreenshot%202024-06-26%20at%202.35.31%20PM.png?alt=media) ### Step 5 (for two-way sync only): Finish setting up the Panther Cloud Sync app {% hint style="info" %} If you did not enable two-way sync for status, assignee, or comments, you can skip this step. {% endhint %} 1. In your Jira console, navigate to **Settings** > **Apps**, then click **Manage apps**. 2. Under **User-installed apps**, click **Panther Cloud Sync** to expand its section. 3. Click **Configure**. 4. Under **Panther Application Configuration**, enter values for the following fields: * **Panther Instance URL**: Enter the **Panther Instance URL** you generated in Panther in the previous step. * **Panther Secret**: Enter the **API Token** you generated in Panther in the previous step. * **Tracked Jira Project**: Select the project you would like to sync to Panther. This project should match the one for which you entered a Project Key in Panther. 5. Click **Save**. ### Step 6: Finish setting up the Jira alert destination in Panther * On the final page of the destination configuration in Panther, optionally click **Send Test Alert** to test the integration using a test payload. When you are finished, click **Finish Setup**. {% hint style="info" %} For information on troubleshooting Jira alert destinations, please see this KB article: [Guide to Troubleshooting Jira Alert Destinations in Panther](https://help.panther.com/Alerts_and_Destinations/Destinations/Guide_to_Troubleshooting_Jira_Alert_Destinations_in_Panther). {% endhint %} ## Comment formatting in Panther When two-way sync for comments is enabled and a comment on a Jira issue is created or updated, advanced formatting (e.g., tables or images) will be stripped from the comment's representation in Panther. The comment formats supported in Panther include: * Bold * Italic * Strikethrough * Links * Code blocks * Paragraphs and line breaks * Quotes * Bulleted lists * Numbered lists ## Alert Context Formatting The `alert_context` payload is JSON [pretty printed](https://docs.panther.com/resources/help/glossary#pretty-print) using JIRA's native formatting. Additionally, Panther `Rule ID` and `Alert ID` fields are surfaced in the ticket’s description for better automation support. ![The image shows an alert in Jira. It contains the title "Test alert title", fields for Description, Runbook, Rule ID, Alert ID, Severity, Tags, and AlertContext.](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-060d616b846950a3d02a54d985075cdeef7f8bb7%2Fjira%20destinations%20ss.png?alt=media) The request body payload looks similar to the example below:
Request body payload ``` { "fields": { "summary": "Some Failure: My Summary", "description": "*Description:* My Description\n [Click here to view in the Panther UI|https://panther.io/alerts/my-alert-id?source=jira]\n *Rule ID:* my-rule-id\n *Alert ID:* my-alert-id\n *Severity:* INFO\n *AlertContext:*\n {code:JSON}\n{\n \"some\": \"json\",\n \"or\": \"code\",\n}{code}", "project": { "key": "MYPROJ" }, "issuetype": { "name": "Task" }, "assignee": { "id": "assignee-jira-id" }, "labels": ["my-label"] } } ```
The request header that Panther sends is in the following format: ``` Authorization: Basic ``` ## Additional Information on Destinations For more information on alert routing order, modifying or deleting destinations, and workflow automation, please see the Panther docs: [Destinations](https://docs.panther.com/destinations).