> ## Documentation Index
> Fetch the complete documentation index at: https://docs.backline.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Jira Integration (Token)
> Sync vulnerabilities and remediations with Jira tickets using Jira API Token
## Overview
Link your Jira projects to automatically create and update issues based on Backline Vulnerabilities and Remediations.
## What You Can Do
With the Jira integration, Backline can:
* Automatically create a Jira ticket for a remediation when its pull request is opened
* Route each remediation ticket to the right Jira project based on the affected application or repository
* Set the new ticket's fields — priority, status, and more — from your Backline remediation field mapping
* Assign each ticket to the remediation's own owner — its code owner, or the manager of an affected application's owning team
* Cross-link any existing vulnerability Jira tickets to the new remediation ticket
* Track remediation work in your team's existing workflow
## Prerequisites
Before connecting Jira, ensure you have:
* A Jira Cloud instance
* Ability to create a service account in your Jira Cloud domain
* Access to generate API tokens
* Your Atlassian Cloud ID
## Connecting Jira
Create a dedicated service account in your Jira Cloud domain.
Generate an API token from the service account. Visit: [https://id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
Add the needed scopes (Classic or Granular - see below), generate the token, and copy it.
Retrieve your Atlassian Cloud ID. Follow the instructions at: [https://support.atlassian.com/jira/kb/retrieve-my-atlassian-sites-cloud-id/](https://support.atlassian.com/jira/kb/retrieve-my-atlassian-sites-cloud-id/)
In Backline, go to the Integration Hub from the main menu.
Find and click on the Jira integration card.
Provide your connection details:
* **API Token**: The token you generated in Step 2
* **Cloud ID**: Your Atlassian Cloud ID from Step 3
* **Email Address**: The email address of the service account used to generate the token
Click **Connect** to verify your credentials. Once verified, you'll move to the Configuration tab.
Backline supports Jira Cloud only.
## API Token Scopes
When creating your API token, you can choose between Classic or Granular scopes:
### Classic Scopes
```
read:jira-work
read:jira-user
write:jira-work
```
### Granular Scopes
```
read:application-role:jira
read:audit-log:jira
read:avatar:jira
read:board-scope:jira-software
read:comment:jira
read:comment.property:jira
read:custom-field-contextual-configuration:jira
read:field-configuration:jira
read:field.default-value:jira
read:group:jira
read:issue:jira
read:issue-details:jira
read:issue-field-values:jira
read:issue-meta:jira
read:issue-status:jira
read:issue-type:jira
read:issue-type-hierarchy:jira
read:issue-type.property:jira
read:issue.transition:jira
read:label:jira
read:project:jira
read:project-category:jira
read:project-role:jira
read:project-version:jira
read:project.component:jira
read:project.property:jira
read:sprint:jira-software
read:status:jira
read:user:jira
read:user.property:jira
write:attachment:jira
write:comment:jira
write:comment.property:jira
write:issue:jira
write:issue-link:jira
write:issue.property:jira
```
## Configuring Projects
After connecting, you'll need to configure which Jira projects Backline should use:
In the Configuration tab, choose a Jira Project from the list of available projects.
Select the issue type you want Backline to create for remediation tickets in this project.
Once the issue type is chosen, the mandatory and optional fields from Jira appear. Map each Jira field to one of the following:
* A value from Jira
* A Backline remediation field (see below)
* A manually entered value
The Backline remediation fields available for mapping are **Remediation Status**, **Remediation Priority**, **Remediation Mode**, **Remediation Type**, **Remediation Title**, **Highest Severity**, and **Time to SLA**. Map Jira fields such as Priority and Status to the matching Backline remediation field so Backline can set them on the tickets it creates.
Complete the field mapping and save your project configuration.
## Automatic Remediation Tickets
Backline creates Jira tickets at the **remediation** level — one ticket for a fix that may span several vulnerabilities. Backline does not create tickets for individual vulnerabilities.
### When tickets are created
When **Auto-Create Ticket** is enabled, Backline creates a remediation ticket when a **pull request is opened** for the remediation. If the remediation already has a ticket, Backline does not create another one.
### Ticket content
Each ticket is composed automatically from the remediation record and includes:
* A short summary of the vulnerabilities addressed and the fix applied
* Remediation details — title, type, mode, and priority
* Impact — highest severity, number of affected vulnerabilities, affected application/service, and repository or image
* A recommended action — review and merge the pull request
* Links back to the Backline remediation and the pull request
On creation, Backline sets the ticket's Jira fields from your field mapping (see [Map Fields](#configuring-projects)), and links any existing vulnerability Jira tickets on the remediation's vulnerabilities to the new ticket.
By default, a remediation ticket carries only the assignee you configured for the destination Jira project, if any. Turn on [Auto Assign Ticket Owner](#auto-assign-ticket-owner) to have Backline assign the remediation's owner instead. Connect a messaging integration like Slack to be alerted if a ticket can't be created after automatic retries.
## Configuration
The **Configuration** tab — shown right after you connect — is where you set up automatic remediation tickets.
### Auto-Create Ticket
Toggle **Auto-Create Ticket** on to let Backline create a ticket when a remediation's pull request is opened. It is **off by default**: no remediation tickets are created until you enable it.
### Auto Assign Ticket Owner
Toggle **Auto Assign Ticket Owner** on to have Backline put the remediation's own owner on each ticket it creates. It is **off by default**, so no ticket is routed to a person until you turn it on.
The assignee is the first of these Backline can match to a Jira user:
1. The remediation's **code owners**, highest confidence first.
2. The **manager of an owning team** of each affected application, primary application first.
3. The **assignee configured for the destination Jira project** in your field mapping.
4. If none of those match, the ticket is created with **no assignee**.
The owner is chosen when the ticket is created. Backline does not reassign a ticket afterwards, and turning the switch on does not change tickets that already exist.
### Global Ticket Title Template
Define the title format for the Jira tickets Backline creates, so titles stay consistent and easy to search. The default is:
```
[Backline] {remediation_title}
```
Combine free text with any of these tokens, in any order:
| Token | Value |
| - | - |
| `{remediation_title}` | The remediation's title in Backline |
| `{remediation_priority}` | The remediation's priority (`P1`, `P2`, or `P3`) |
| `{app_name}` | The affected application's name |
| `{remediation_status}` | The remediation's status (e.g. `Pending Approval`, `Manual Fix`) |
| `{remediation_mode}` | The remediation's mode (`Auto` or `Hybrid`) |
A token with no value for a given remediation is dropped from the title without failing ticket creation.
### Project routing
Remediation tickets are routed to a Jira project based on the affected application or repository:
* **Project Mapping** — upload a CSV that maps each application or repository to a Jira project. Download the template (pre-filled with your known repositories and detected applications), fill in the `jira_project_name` column, and upload it. After upload, a preview lists every row with its resolved status; rows that fail validation — unknown identifier, Jira project not found, or missing/duplicate identifier — are flagged and skipped. You can also [override specific Jira fields per row](#overriding-fields-per-repository-or-application).
* **Default Jira Project** — the fallback project for any application or repository not covered by the mapping. A Default Jira Project is **required** before the integration can be activated.
The CSV has four columns — `jira_project_name`, `application`, `repository_url`, and the optional `field_overrides`. Each row maps one Jira project to exactly one identifier — either an `application` or a `repository_url`, leaving the other blank:
```
jira_project_name,application,repository_url,field_overrides
PAYMENTS,payments-api,,
PLATFORM,,https://github.com/acme/platform-service,
```
Uploading a new mapping merges into the existing one — adding or updating rows — and never removes rows absent from the new file. Identifiers are stored by a stable internal ID, so renaming an application or repository later won't break routing. The issue type for created tickets comes from the destination Jira project's own default issue type, so no extra configuration is needed.
### Overriding fields per repository or application
By default, every ticket a project creates uses that project's [field mapping](#configuring-projects). The optional **`field_overrides`** column lets a single repository or application set its own values for specific Jira fields, on top of the project mapping — for example, routing a repo's tickets to a different component or parent epic, or giving one repo a higher priority.
Leave the column **blank** to use the project's field mapping unchanged. When set, it's a JSON object keyed by the Jira field's **display name** (exactly as it appears in the field mapping). Only the fields you list are overridden; everything else keeps the project default.
| Field kind | Value format | Example |
| - | - | - |
| Single-value field (select, component, assignee, …) | the value's display name | `{"Component":"Billing"}` |
| Multi-value field | an array of display names | `{"Components":["api","web"]}` |
| **Parent** | the parent issue's **Jira key** (not its name) | `{"Parent":"BKLN-186"}` |
| **Priority** | an object mapping each remediation priority to a Jira priority | `{"Priority":{"P1":"Highest","P2":"High","P3":"Medium"}}` |
| **Status** | an object mapping each remediation status to a Jira status | `{"Status":{"PendingApproval":"In Review","ManualFix":"In Progress"}}` |
Priority and Status are **keyed** because Backline maps them from the remediation's own priority (`P1`/`P2`/`P3`) or status (`PendingApproval`, `ManualFix`) — so you provide a value per key, just like in the field-mapping UI.
Because the value contains commas and quotes, wrap the whole JSON object in double quotes and double every inner quote (standard CSV escaping):
```
jira_project_name,application,repository_url,field_overrides
PAYMENTS,payments-api,,"{""Priority"":{""P1"":""Highest"",""P2"":""High""},""Component"":""Billing""}"
PLATFORM,,https://github.com/acme/platform-service,"{""Parent"":""BKLN-186""}"
```
All values are validated **on upload** against the destination project: each field name and value must resolve to a real Jira field and option. If any value is invalid — an unknown field, a value that isn't a valid option, a parent key that doesn't exist, or the wrong shape for the field — that row is flagged and skipped, and the rest of the upload is rejected, so a bad override never reaches ticket creation.
## Managing the Integration
### Managing Projects
To view and manage your connected Jira projects:
From the Jira Integration card, click the **three dots menu** and choose **Manage Project**.
You'll see all connected Jira projects listed.
For each connected project, you can:
* **Edit** the configuration to modify field mappings or issue types
* **Delete** the project to remove the connection
Click **Add Project** to configure additional Jira projects.
Connect a messaging integration like Slack to receive notifications if there's an issue connecting or updating a ticket during the remediation process.