> For the complete documentation index, see [llms.txt](https://docs.decube.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decube.io/data-quality-v2/alerts/alert-channels/jira.md).

# Jira

Create Jira work items automatically from an alert rule, so every new case on the monitors it targets lands in your team's Jira queue.

Adding Jira to an alert rule creates a Jira work item for each new case raised by the monitors the rule targets. The work item lands in the project and Work Item type you choose, carries the same evidence as an alert email, and links back to the case. Use it when the people who fix data problems already plan their work in Jira. A failing monitor on an asset you own then becomes a work item in the owning team's queue, and nobody has to triage it into Jira by hand first.

Jira behaves differently from the other alert channels. Slack, Microsoft Teams, Email and Webhook send a message for each incident. Jira creates a work item that stays linked to the case and, with status sync set up, a Jira status change can then close the case. When later incidents join the same case, the rule's [repeat-incident policy](#choose-a-repeat-incident-policy) decides what happens to the existing work item.

To create a work item by hand from a case you are triaging, see [Jira work items](https://docs.decube.io/data-quality-v2/cases/jira-work-items.md).

## Before you start

{% hint style="info" %}
You need the following in place:

* **Jira connected to Decube.** An administrator connects Jira Cloud or Jira Data Center once for your organization from **Integrations** > **Third-party**. See [Set up Jira connection](https://docs.decube.io/collaboration/jira.md#set-up-jira-connection).
* **Edit on Manage Alerts**, to create or change alert rules. See [Module-based policies](https://docs.decube.io/group-access-policies/module-based-policies.md#data-quality-v2).
  {% endhint %}

**Select a project** lists every project the Jira account connected to Decube can access. You don't need to map a project on the Jira integration to use it on a rule.

Status sync from Jira back to the case is optional. It needs the project's statuses mapped and the Jira sync webhook registered. Without it, rules still create work items, and you close cases in Decube yourself. See [How Jira status updates the case](https://docs.decube.io/data-quality-v2/cases/jira-work-items.md#how-jira-status-updates-the-case).

Jira always appears in the channel list, even before Jira is connected. Until it is connected, there are no projects or Work Item types to choose, so you cannot add a new Jira channel.

## Add Jira to a rule

1. In **Set up alert channels**, select **Jira** on a channel row. **How to set up** beside it links back to this page.
2. In **Select a project**, choose the project the work item should be created in.
3. In **Choose a Work Item type**, choose the type, for example Bug, Task or Incident.
4. Write the **Summary**, using **Insert token** to add case details. See [Write the Summary template](#write-the-summary-template).
5. Under **Repeat-incident policy**, choose what happens when an incident joins a case that already has a work item linked. See [Choose a repeat-incident policy](#choose-a-repeat-incident-policy).
6. Click **Test alert**, then check the project for the test work item.
7. Click **Create this alert rule**.

<figure><img src="https://1779874722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTw0qpCVzfrIXqS4FEg4T%2Fuploads%2Fgit-blob-c7438f7c12b6c1cb7f619d23dd910a4f2eec92dc%2Fdq-v2-jira-alert-channel.png?alt=media" alt="Jira channel row in Set up alert channels with project, Work Item type, Summary with token buttons, and the repeat-incident policy options"><figcaption><p>A Jira channel on an alert rule</p></figcaption></figure>

To create work items in several projects from the same incident, add a Jira row per project. Each row delivers independently.

### Write the Summary template

The Summary becomes the work item's title. Write it once on the rule, and use tokens to fill in the details of each case. Click a token under **Insert token** to add it at the cursor, or type it yourself:

| Token             | Replaced with                       |
| ----------------- | ----------------------------------- |
| `{{MonitorName}}` | The name of the monitor that failed |
| `{{CaseId}}`      | The ID of the case                  |
| `{{MonitorId}}`   | The ID of the monitor that failed   |

For example, `[DQ] {{MonitorName}} failed (case {{CaseId}})` produces a title such as `[DQ] orders_daily freshness failed (case 4821)`. **Preview** under the field shows how the Summary reads as you type, with each token highlighted where its value will go.

The Summary can be up to 255 characters, which is Jira's own limit. A token that is not in the table above stays in the title exactly as you typed it, so check the preview for typos.

{% hint style="success" %}
**Suggested best practice:** Put a fixed prefix such as `[DQ]` at the start of the Summary. It lets your Jira team filter, report on and build automations for Data Quality work items without relying on labels.
{% endhint %}

### What goes in the work item

The work item's description carries the same content as an alert email: the monitor that failed, the asset it runs on, and the evidence Decube captured at the moment of failure. It ends with a link to the case in Decube.

Work items created by a rule are unassigned. Assign them through your project's own triage, a Jira automation, or by editing the work item from the case.

### Choose a repeat-incident policy

A case groups every incident from the same monitor while it stays open, so the same problem can fire the rule many times. The repeat-incident policy decides what the rule does when a new incident arrives and the case already has active work items in the rule's project and Work Item type. Work items count whether someone created them from the case or another rule created them.

| Policy                                      | Case has no work item in this project and type | Case already has one or more                             |
| ------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------- |
| **Do nothing**                              | Nothing is created                             | Nothing happens                                          |
| **Create a new Work Item**                  | Creates a work item                            | Creates another work item                                |
| **Add a new comment to existing Work Item** | Nothing is created                             | Adds the new incident's details as a comment on each one |

Pick the policy by how your team wants to work:

* **Create a new Work Item** is the only policy that opens the first work item for a case. Use it when the rule's job is to put every new case into Jira. Each repeat incident also opens another work item, so pair it with a narrow scope or with monitors that rarely repeat.
* **Add a new comment to existing Work Item** keeps one thread per problem. Use it on a rule alongside a manual workflow, where someone creates the work item from the case and the rule then keeps it updated as the problem recurs.
* **Do nothing** leaves existing work items alone. Use it when one work item per case is enough and repeat incidents would only add noise in Jira.

{% hint style="info" %}
A case can carry up to 10 active work items. If a rule tries to create one beyond that, the delivery fails and the reason is recorded on the case.
{% endhint %}

## Test alert

{% hint style="warning" %}
Unlike the other channels, a Jira test alert creates a real work item in the selected project and Work Item type. Its summary and description read `Test ticket created by Decube`. Close or delete it in Jira once you have confirmed it arrived.
{% endhint %}

A test confirms that Decube can reach the project and create that Work Item type. It does not evaluate the rule or use incident data, so it says nothing about whether the rule matches the monitors you expect. Use **Preview matching monitors** on the rule for that.

## When several rules match

Every enabled rule is evaluated independently, so several rules with a Jira channel can match the same incident. Decube merges identical Jira channels before it delivers:

* Channels with the same project, Work Item type and Summary create a single work item, not one per rule.
* Comments on the same work item are added once.

Channels that differ in any of project, Work Item type or Summary deliver separately.

## Where delivery is recorded

**Alerts Destinations** on each incident lists every work item a rule created or commented on under **Jira**, as the project name and work item key, for example `Jira-Decube Integration Test · JDIT-832`, with its delivery status. A failed delivery shows the reason, such as Jira not being connected or the case already holding 10 work items. See [Alerts destinations](https://docs.decube.io/data-quality-v2/cases/case-details.md#alerts-destinations).

<figure><img src="https://1779874722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTw0qpCVzfrIXqS4FEg4T%2Fuploads%2Fgit-blob-1c12e4a3c1bd1c7cbbd6fbc001ce948c5f37d788%2Fdq-v2-jira-alerts-destinations.png?alt=media" alt="Alerts Destinations on an incident showing a Jira work item delivered"><figcaption><p>A delivered Jira work item under Alerts Destinations</p></figcaption></figure>

Each work item a rule creates also appears in the case's **Jira work items** section, and the case's **Audit History** tab logs it as **Jira work item added by alert**.

## Frequently Asked Questions

1. **My rule matched, but no work item was created.**

Check the repeat-incident policy first. **Do nothing** and **Add a new comment to existing Work Item** never create the first work item for a case. Only **Create a new Work Item** does. If the policy is right, open the incident and read **Jira** under **Alerts Destinations** for the delivery status and reason.

2. **What happens to my rules if Jira is disconnected?**

Rules keep their Jira channels. While Jira is disconnected, every Jira delivery fails with `Jira is not connected` and is recorded on the case. Deliveries resume once an administrator reconnects Jira. Disconnecting also removes every linked work item from every case. See [Jira work items](https://docs.decube.io/data-quality-v2/cases/jira-work-items.md).

3. **Does a muted case still create work items?**

No. Muting suppresses delivery on every channel, Jira included. Incidents keep joining the case, and deliveries resume once the mute ends.

4. **Can a rule assign the work item to someone?**

Not from the rule. Work items created by a rule are unassigned. Use a Jira automation on the project to assign them, or set the assignee by editing the work item from the case.

5. **How does a work item close the case?**

The same way as a work item created by hand. With status sync set up, when a linked work item reaches a Jira status mapped to Close, Decube closes the case. See [How Jira status updates the case](https://docs.decube.io/data-quality-v2/cases/jira-work-items.md#how-jira-status-updates-the-case).
