# Add Jira Connection

Source: https://userguide.qualytics.io/settings/integrations/ticketing/jira/how-tos/connection/add-connection/

Connect the Jira integration so Qualytics can create and link Jira issues from anomalies. The credentials are validated against your instance before anything is saved, so the connection is only created once Jira accepts them.

> **Info: Prerequisites**
>
> Complete the [Jira Configuration](https://userguide.qualytics.io/settings/integrations/ticketing/jira/how-tos/jira-configuration/) steps first to generate the API token and note your instance URL.

> **Info: Permissions**
>
> Users with the **Manager** or **Admin** role can connect the Jira integration. See the [Permissions](https://userguide.qualytics.io/settings/integrations/ticketing/jira/deep-dive/permissions/) page for details.

## Field reference

The **Add Jira Integration** modal is laid out in three groups.

### Connection Properties

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Instance URL** | Yes | Text | The URL of your Jira Cloud instance, for example `https://your-domain.atlassian.net`. Do not include a trailing slash. |
| **Credentials** | Yes | Secret | Your Jira account email and API token joined by a colon, in the format `email:api_token`, for example `user@example.com:your_api_token`. The value is masked once saved. |

### Options

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Allowed Projects** | Yes | Multi-select | The only Jira projects Qualytics can create tickets in. Every ticket, whether opened by a person, a Flow, or AgentQ, goes to one of these. The list is read from Jira using the credentials above, so it stays empty until those are filled in. |
| **Issue Type** | No | Select | One field per allowed project, labeled with the project's name and key. It sets the type of every issue Qualytics creates in that project, and it starts on `Task`. Opening it reads the list from Jira: the top-level types the account can create in that project, without sub-task types. For a Jira Service Management project, pick a service type such as **Service request**, because a default service project has no `Task` type. |
| **Default Project** | Yes | Select | The project used when a Flow or AgentQ creates a ticket without naming one. Only the allowed projects are offered. |

> **Info: Jira Service Management projects**
>
> A service project can be an allowed project like any other, but the integration account has to be a licensed agent on it. Without an agent seat, the project's **Issue Type** field shows an error instead of a list. See [Jira Service Management Projects](https://userguide.qualytics.io/settings/integrations/ticketing/jira/deep-dive/requirements/#jira-service-management-projects).

### Sync Settings

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Two-way sync** | No | Toggle | On by default. Comments and status notes are posted to every linked issue, and any single issue can still be set to read only from its card. Turn it off to make the whole integration read only, so issue status, title, and comments are still read back and nothing is written to Jira. |
| **Anomaly status sync** | No | Toggle | Off by default. When on, anomaly and issue statuses move together through the mapping below. When off, issue statuses are still read back and shown on the ticket cards, but neither side moves the other. |
| **Mapping** | No | Dialog | Pairs each anomaly status with an issue status. Available only while **Anomaly status sync** is on. |

### Status Mapping

The **Mapping** row opens the **Status Mapping** dialog, with one row per anomaly status. Each row asks the same question: when an anomaly reaches this status, where should its issues sit in Jira? The same pairing is read in reverse, so an issue arriving at that status moves the anomaly back.

| Anomaly status | What it means | What to pair it with in Jira |
| --- | --- | --- |
| **Active** | Detected and awaiting triage. | The status new work starts in, such as `To Do` or `Backlog`. |
| **Acknowledged** | Reviewed by someone, still needs follow-up. | The status that means someone owns it, such as `In Progress`. |
| **Resolved** | A real concern that has been addressed. | The status that closes work normally, such as `Done`. |
| **Duplicate** | The same issue as another anomaly. | A closing status. Pair it with the same one as Resolved unless your workflow has a distinct status for duplicates. |
| **Invalid** | Not a real data quality concern. | A closing status. Use a distinct one, such as `Won't Do`, when your workflow has it, so a false positive is not counted as work delivered. |
| **Discarded** | No longer relevant or under review. | A closing status, the same choice as Invalid. |

The rows do not start empty. Turning **Anomaly status sync** on fills them with `To Do`, `In Progress`, and `Done` for the four archived statuses, whenever your projects have statuses by those names, and with the first status of the matching category otherwise.

Four of the six statuses archive the anomaly, so in most workflows they end up pointing at the same closing status. Splitting them is worth it only when your Jira reports treat those outcomes differently.

Four rules apply while you fill the dialog:

- **A status your projects do not have can still be typed.** The list suggests the statuses of your allowed projects, grouped by category, with chips naming the projects that have each one.
- **A row can be left out.** Clearing it makes the field read **Leave unchanged**, and that anomaly status then moves no issue and is never moved by one. At least one row has to be paired.
- **A workflow that lacks the paired status still moves.** The issue goes to the nearest status in the same category, which is what the dialog states under the table.
- **Reset starts the rows over.** The **Reset** button reloads the statuses from your projects and fills the rows with the defaults again, discarding the edits made since the dialog opened. It leaves the dialog open so you can check the result, and **Apply** is still what saves it. **Cancel** closes the dialog and leaves the saved mapping alone.

For what each sync mode writes and reads, see [Read only and two-way sync](https://userguide.qualytics.io/settings/integrations/ticketing/jira/deep-dive/sync-behavior/#read-only-and-two-way-sync) and [Anomaly status sync](https://userguide.qualytics.io/settings/integrations/ticketing/jira/deep-dive/sync-behavior/#anomaly-status-sync).

## Steps

**Step 1**: In the left side panel, click **Settings** .

**Step 2**: The **Connections** tab opens by default. Click the **Integrations** tab.

**Step 3**: Scroll to the **Ticketing** group, find the **Jira** row, and click **Connect** . The **Add Jira Integration** modal opens.

**Step 4**: Fill in the required fields. See the [Field reference](https://userguide.qualytics.io/settings/integrations/ticketing/jira/how-tos/connection/add-connection/#fields) above for what each one holds and which are required. Each allowed project gets its own **Issue Type** field, so change it for any project where `Task` is not the type you want.

**Step 5**: If you turned **Anomaly status sync** on, click the **Mapping** row to open the **Status Mapping** dialog, pair each anomaly status with one of your Jira statuses, and click **Apply**.

**Step 6**: Click **Create**. Qualytics validates the credentials against your instance, and a success message appears with the **Jira** row now showing **Connected** and your instance URL.

*Last updated: October 27, 2026.*
