> 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/cases/jira-work-items.md).

# Jira work items

Create Jira work items from a case, track their status in Decube, and let Jira close the case when the work is done.

When a monitor on an asset you own fails, the fix often belongs to someone else: an engineer who owns the pipeline, an analyst who owns the model, or a team that works only in Jira. Linking a Jira work item to the case puts the problem in that team's queue, assigned to a named person, with the evidence attached. Decube shows the work item's status on the case and, if you turn on status sync, closes the case when Jira reports the work as done.

You can link work items in two ways:

* **From the case**, as described on this page, when you are triaging a case and decide who should pick it up.
* **From an alert rule**, which creates a work item for every new case raised by the monitors the rule targets. See [Jira](https://docs.decube.io/data-quality-v2/alerts/alert-channels/jira.md).

Both paths link to the same list on the case, and both follow the same status sync.

<figure><img src="https://1779874722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTw0qpCVzfrIXqS4FEg4T%2Fuploads%2Fgit-blob-fa4fefcb7811cee488800656291625fdeac43cec%2Fdq-v2-jira-case-work-items.png?alt=media" alt="Case details panel showing the Jira work items section with one linked work item"><figcaption><p>The Jira work items section on a case</p></figcaption></figure>

## 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 access to the case.** Creating, modifying and unlinking work items requires Edit on **Cases and incidents** for the asset's source. See [Source-based policies](https://docs.decube.io/group-access-policies/source-based-policies.md#data-quality-classic-and-v2).
  {% endhint %}

Status sync from Jira back to the case is optional. Set it up if you want a work item's Jira status to close the case for you. Without it, you can still create, track and modify work items, and you close the case in Decube yourself. See [How Jira status updates the case](#how-jira-status-updates-the-case).

## Create a work item

1. Open the case from the **Cases** tab, or from the link in an alert.
2. In the **Case details** panel, go to **Jira work items** and click **Create**. The **Create a Jira work item** form opens.
3. Fill in the work item:
   * **Select a project**: the Jira project that should own the work. The list shows every project the Jira account connected to Decube can access.
   * **Select a Work Item type**: for example Bug, Task or Incident, depending on what the project offers.
   * **Select an assignee**: the person in Jira who should pick it up. You can leave it empty and let the project's own triage assign it.
   * **Summary**: the work item title, up to 255 characters.
   * **Description**: the body of the work item.
4. Click **Create this work item**.

**Description** opens pre-filled with the case's context, formatted for Jira: when the case was first seen and how many incidents it holds, the monitor's type and name with a link to it in Decube, and the affected assets. The person picking up the work item has the evidence they need without opening Decube. Edit or add to it before you create the work item.

<figure><img src="https://1779874722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTw0qpCVzfrIXqS4FEg4T%2Fuploads%2Fgit-blob-e0fdcd470eb106b6f83c03c1b6635591882e4ab2%2Fdq-v2-jira-create-work-item.png?alt=media" alt="Create a Jira work item form with project, Work Item type, assignee, Summary and a pre-filled Description"><figcaption><p>The Create a Jira work item form</p></figcaption></figure>

Decube creates the work item in Jira, links it to the case, and records the action in the case's **Audit History** tab. A **Jira Linked** badge appears next to the case status, so anyone opening the case sees the work is already tracked.

### Link more than one work item

A case can carry up to 10 active work items at once, in the same project or in different ones. Use this when the fix spans teams, for example one work item for the data engineering team that owns the pipeline and another for the analytics team that needs to backfill a downstream report.

Work items you create here and work items created by an alert rule share the same limit. When a case reaches 10, unlink one before you add another.

## Track linked work items

The **Jira work items** section shows a card for every active work item on the case, oldest first. Each card shows:

* **Title**, the work item's summary, with its current Jira status beside it, for example `To Do`.
* **Work Item ID**, the Jira key, for example `DATA-142`. It links to the work item in Jira.
* **Assignee**, as currently set in Jira, or **Unassigned**.

The section treats every work item the same way, whether you created it from the case or an alert rule created it. The case's **Audit History** tab records how each one was added.

## Modify a work item

1. In **Jira work items**, click the pencil icon on the work item's card.
2. Change the **Summary**, **Description** or **Assignee**.
3. Save your changes.

Decube writes the change to the work item in Jira. The project and Work Item type are fixed once the work item exists. To move the work to another project, create a new work item there and unlink the old one.

## Unlink a work item

1. In **Jira work items**, click the unlink icon on the work item's card.
2. Confirm in the prompt.

Unlinking removes the work item from the case and stops all status sync for it. The work item itself stays in Jira, untouched.

{% hint style="warning" %}
Unlinking is permanent. You cannot relink the same work item to the case afterwards. If you unlink by mistake, create a new work item from the case.
{% endhint %}

## How Jira status updates the case

Status sync is optional. It lets a status change in Jira act on the case, so the team doing the work closes the investigation from Jira without opening Decube. To turn it on, set up two things on the Jira integration:

* **Map the project's statuses** to case actions, for example `Done` to Close. Only projects you map here sync. Mapping has no effect on which projects you can create work items in. See [Syncing statuses from Decube to Jira](https://docs.decube.io/collaboration/jira.md#syncing-statuses-from-decube-to-jira).
* **Register the Jira sync webhook** in Jira, so Decube hears about status changes. See [Adding Jira Sync Webhook to Decube](https://docs.decube.io/collaboration/jira.md#adding-jira-sync-webhook-to-decube).

If you skip either step, work items are still created and linked, but nothing you do in Jira changes the case. Close the case in Decube once the work is done.

With both in place, Decube listens for status changes on every active linked work item. When a work item moves to a Jira status, Decube looks that status up in the project's status mapping and applies the mapped case action, exactly as if a person had taken it on the case.

When a case has several work items, the **first** one to reach a status mapped to Close closes the case, even if the others are still open. This lets the team that resolves the root cause close the investigation without waiting on follow-up work elsewhere.

{% hint style="success" %}
**Suggested best practice:** If a case links work items in several projects, map Close only to the status that means the data problem is fixed, for example `Done` on the owning team's project. Leave follow-up projects mapped to statuses that do not close the case.
{% endhint %}

Status changes on unlinked work items, and on work items in projects that are not mapped, have no effect on the case.

## What Audit History records

The case's **Audit History** tab logs every Jira action with the work item key, linked through to Jira, alongside the timestamp and who made the change. Use it to trace who sent the case where:

<figure><img src="https://1779874722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTw0qpCVzfrIXqS4FEg4T%2Fuploads%2Fgit-blob-f96ea1f11150f7744dc001292c1b68736e1abf63%2Fdq-v2-jira-audit-history.png?alt=media" alt="Audit History tab on a case showing a Jira work item added entry"><figcaption><p>A Jira work item added entry in Audit History</p></figcaption></figure>

| Entry                                | When it is logged                                                                |
| ------------------------------------ | -------------------------------------------------------------------------------- |
| **Jira work item added**             | Someone creates a work item from the case. The entry names that person.          |
| **Jira work item added by alert**    | An alert rule creates a work item for the case.                                  |
| **Jira work item removed**           | Someone unlinks a work item. The entry names that person.                        |
| **Jira work item removed by system** | Jira is disconnected from Decube, which removes every linked work item.          |
| **Case closed by Jira**              | A linked work item reaches a status mapped to Close, and Decube closes the case. |

## Frequently Asked Questions

1. **I moved the work item to Done in Jira, but the case is still open.**

Status sync has to be set up for this to happen. Check three things, in this order:

* **The status mapping.** The work item's project must be mapped, and `Done` for that issue type must be mapped to Close. See [Syncing statuses from Decube to Jira](https://docs.decube.io/collaboration/jira.md#syncing-statuses-from-decube-to-jira).
* **The webhook.** The Jira sync webhook must be registered in Jira with the **Issue updated** event. See [Adding Jira Sync Webhook to Decube](https://docs.decube.io/collaboration/jira.md#adding-jira-sync-webhook-to-decube).
* **The link.** The work item must still appear in **Jira work items** on the case. An unlinked work item no longer syncs.

2. **Why can't I find my project in the project list?**

The list shows the projects that the Jira account used to connect Decube can access in Jira. Ask your Jira administrator to grant that account access to the project.

Mapping a project on the Jira integration only turns on status sync for it, and does not affect which projects are listed.

3. **Can I edit a work item that an alert rule created?**

Yes. Once linked, a work item created by an alert rule behaves like one you created yourself. You can modify its Summary, Description and Assignee, or unlink it.

4. **What happens to linked work items if Jira is disconnected?**

Decube removes every linked work item from every case and logs **Jira work item removed by system** on each. The work items stay in Jira. Existing Audit History entries keep their work item keys. Reconnecting Jira does not restore the links.

5. **Does closing the case in Decube close the work item in Jira?**

No. Sync runs from Jira to Decube only. Close or resolve the work item in Jira as part of your team's normal workflow.
