> For the complete documentation index, see [llms.txt](https://docs.interlynk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interlynk.io/administration/jira.md).

# Jira

The Jira integration provides enterprise-grade, bidirectional vulnerability management between Interlynk and Jira. It supports automatic ticket creation, VEX field synchronization, and status tracking across both platforms.

***

## Purpose

* Create Jira tickets for vulnerabilities discovered in SBOMs — manually or automatically via policy violations.
* Synchronize VEX (Vulnerability Exploitability eXchange) status bidirectionally between Interlynk and Jira.
* Map vulnerability severity to Jira priority and custom fields.
* Track remediation progress across both platforms.

***

## Setup Steps

### Step 1: Connect Jira

1. Navigate to **Settings > Organization > Integrations > Connections**.
2. Click **Jira**.
3. Enter the following:
   * **Jira Host URL**: Your Jira instance URL (e.g., `https://yourcompany.atlassian.net`).
   * **User Email**: The email of the Jira user account that Interlynk will use.
   * **API Token**: A Jira API token generated for the user account.
4. Click **Verify** to test the connection.
5. On success, the verification panel displays: account name, account ID, account type, Jira URL, version, deployment type, and server title.
6. Click **Save**.

### Step 2: Provision Vulnerability Management

After connecting Jira, set up the vulnerability management configuration to enable custom field mapping and bidirectional sync.

1. Navigate to **Settings > Organization > Integrations > Connections > Jira Vulnerability Management**.
2. Click **Initialize**.
3. Interlynk provisions the following resources in your Jira instance (8-step process):
   1. Custom issue type (`InterlynkVuln`)
   2. Issue type scheme
   3. Custom fields (11 VEX-related fields)
   4. Workflow
   5. Workflow scheme
   6. Screen with fields
   7. Screen scheme
   8. Issue type screen scheme
4. Wait for provisioning to complete. Status is displayed as **In Progress**, **Completed**, or **Failed** (with the specific step that failed).

### Step 3: Associate Jira Projects

After provisioning, associate Jira projects with the vulnerability management configuration:

1. Select the Jira **project** from the dropdown.
2. The issue type scheme and screen scheme are applied to the project.
3. Repeat for each project that should receive vulnerability tickets.

### Step 4: Configure Per-Product Settings

For each Interlynk product that should create Jira tickets:

1. Navigate to **Settings > Organization > Integrations > Ticketing**.
2. Click the product to open its settings drawer. Each Environment has its own tab.
3. Set the project, work type, epic, assignee, components and sync for each Environment. **Copy these settings to other environments** copies the project, work type, assignee and epic; sync stays as it is in each Environment. Unsaved changes ask for confirmation before they are discarded.

The full set of fields, including default labels and the ticket title template, is also on the product's own **Settings > Jira** page, per Environment:

* **Jira Project**: The target Jira project for tickets.
* **Work Type (Issue Type)**: Select from issue types available in your Jira project. Interlynk queries your Jira project's create metadata and only renders issue types that project actually supports. Select **InterlynkVuln** for full VEX field support (requires provisioning to be completed first). A work type is required for projects with sync turned on.
* **Epic**: Link new tickets to an existing Jira Epic (optional). The dropdown lists Epics in the selected project.
* **Default Assignee**: The Jira user who receives new tickets (optional).
* **Default Reporter**: The Jira user listed as reporter (optional, required by some Jira projects).
* **Components**: Route tickets to specific Jira Components within the project (optional). The field appears only when the selected project and issue type support a Components field.
* **Default Labels**: Labels added to every ticket created from this Environment (optional). The field appears when the Jira project has a Labels field. The selector suggests labels that already exist in your Jira site, and you can type new ones.
* **Ticket Title**: A template for ticket titles (optional). See [Ticket Title Templates](#ticket-title-templates).
* **Bi-directional Sync**: Toggle two-way synchronization between Jira and Interlynk.

### Step 5: Test Your Integration

After configuring per-product settings, create a test ticket to verify the connection and field mapping before enabling automatic ticket creation:

1. In the per-product Jira settings, ensure **Project** and **Work Type** are selected.
2. Click **Create Test Ticket**.
3. The test ticket dialog pre-fills sample values: product version `1.0.0`, severity `high`, package `openssl` `3.5.6` and vulnerability `CVE-0000-00000`. Edit any of them to see how the title and fields come out. If the Environment has a title template, the title is built from it. Otherwise the title is `[Interlynk Test] <timestamp> - Safe to delete`.
4. Send the ticket. It is created in Jira using the current configuration, with the Environment's default labels plus a test label. Verify it appears in the correct project with the expected fields populated.
5. To test specific field mappings without saving them, pass Jira field overrides when sending the test ticket. Inline-selected fields are reflected in the created test ticket, so you can confirm a mapping before applying it to the saved configuration. Labels selected inline replace the saved default labels for that ticket.
6. Delete the test ticket from Jira after verification.

***

## Ticket Creation

### Manual Ticket Creation

Create Jira tickets for individual or multiple vulnerabilities:

1. Navigate to a product's vulnerability view.
2. Select one or more vulnerabilities.
3. Click **Create Jira Issue**.
4. The issue creation modal displays:
   * Pre-populated fields based on the vulnerability (summary, description, severity, affected package).
   * Standard fields: project, issue type, assignee, reporter, priority, labels.
   * VEX fields: status, justification, action response, impact statement, notes, action statement.
5. Click **Create** to submit.

**Bulk creation** supports up to 50 issues per request.

### Ticket Title Templates

Each Environment can set a title template on the product's **Settings > Jira** page, in the **Ticket Title** field. The template is plain text with placeholders in double braces:

| Placeholder            | Value                                 |
| ---------------------- | ------------------------------------- |
| `{{product_name}}`     | Product name                          |
| `{{product_version}}`  | Version of the SBOM the finding is in |
| `{{severity}}`         | Vulnerability severity                |
| `{{package_name}}`     | Affected component name               |
| `{{package_version}}`  | Affected component version            |
| `{{vulnerability_id}}` | Vulnerability ID, such as a CVE       |

Click a placeholder under the field to insert it, or click **Use example** to start from:

```
{{product_name}}:{{product_version}} - {{severity}} severity vulnerability in {{package_name}}:{{package_version}} - {{vulnerability_id}}
```

The field previews the title with sample values as you type. Click **Save** or press Enter to save, and Escape to cancel.

Rules:

* Only the six placeholders above are allowed. An unknown placeholder or an unmatched `{{` or `}}` is rejected when you save.
* A placeholder with no value, such as a component without a version, renders as `N/A`.
* Jira limits titles to 255 characters. Longer titles are shortened, and the preview warns when a template is likely to run over.
* A template cannot be only spaces. To go back to the default title, clear the field and save.
* When a finding is on a part, the product name and version come from the parent product you are creating the ticket from.

**Where the template applies:**

| Ticket                              | Title                                                                                                                               |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Manual ticket                       | The dialog pre-fills the title from the template. You can edit it before creating the ticket, and an edited title is kept as typed. |
| Bulk ticket creation                | Each ticket's title comes from the template.                                                                                        |
| Automatic (policy violation) ticket | The title comes from the template.                                                                                                  |
| Test ticket                         | The title comes from the template, filled with the sample values.                                                                   |

**Default titles.** Without a template, manual and bulk tickets use `[Vulnerability]: <vulnerability-id>`, and automatic tickets use:

```
Policy Violation: <product-name> (<environment>): <vulnerability-id> in <package-name>
```

### Ticket Descriptions

Ticket descriptions are sent to Jira as formatted content, so headings, code blocks, links and lists from the vulnerability advisory render as they do in the advisory. Ticket metadata such as package names and versions is shown as literal text and is never read as formatting. If an advisory cannot be formatted, the description falls back to plain text.

### Automatic Ticket Creation

Automatic ticket creation is driven by **policy violations**:

1. Define a policy with vulnerability conditions and enable **Create Ticket** on the policy.
2. When a policy scan produces violations, the `BulkAutoTicketCreationJob` processes them.
3. Tickets are created in batches of 50 per Jira project.
4. Each violation is linked to its Jira ticket. Duplicate tickets are not created for existing links.

Policy-driven tickets use the Jira configuration of the product context the violation came from, rather than a single organization-wide setting.

***

## Ticket Reuse

The same vulnerability usually reappears when a new SBOM version is uploaded, and often in a second Environment of the same Product. Rather than opening a fresh ticket each time, Interlynk can link the existing one.

Two Environment settings control this, both on the Environment's **Settings > Import & defaults > Version lifecycle** page:

| Setting                                             | Scope                                       | Default |
| --------------------------------------------------- | ------------------------------------------- | ------- |
| **Reuse Jira tickets for matching vulnerabilities** | Other SBOM versions in the same Environment | On      |
| **Reuse Jira tickets across environments**          | Other Environments of the same Product      | Off     |

Cross-Environment reuse has additional conditions:

* The setting is Product-wide. Toggling it writes the same value to every Environment in the Product, and reuse only applies when all of them agree.
* The source and destination Environments must point at the **same Jira project**. Environments configured against a different Jira project are skipped.

When a ticket is reused, the reused issue is updated with the SBOM versions it now covers, and stale links from deleted or superseded SBOMs are cleared first so a ticket is never linked to a version that no longer exists.

### Audit Trail

Each reuse is recorded on the vulnerability's Change Log as an `existing_jira_ticket_linked` entry, naming the issue key and the Environment and version it was reused from.

***

## Field Mapping

### Standard Fields

| Interlynk Field  | Jira Field            | Notes                                                                 |
| ---------------- | --------------------- | --------------------------------------------------------------------- |
| Vulnerability ID | Summary (title)       | Format: `Policy Violation: <product> (<env>): <vuln-id> in <package>` |
| Description      | Description           | Includes component details, severity level, and CVSS score            |
| Severity         | Priority              | Mapped via priority mapping (see below)                               |
| Affected package | Labels / Custom field | Configurable                                                          |
| SBOM version     | Affected Versions     | Automatically included from SBOM metadata                             |
| Components       | Jira Components       | Routes to the Jira component(s) configured in product settings        |

### VEX Custom Fields

The following VEX fields are synced bidirectionally as Jira custom fields:

| Custom Field             | Type   | Description                                                                                                                      |
| ------------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------- |
| Vulnerability ID         | Text   | CVE or vulnerability identifier                                                                                                  |
| Affected Package         | Text   | Package name                                                                                                                     |
| Affected Package Version | Text   | Package version                                                                                                                  |
| VEX Status               | Select | `affected`, `not_affected`, `fixed`, `in_triage`                                                                                 |
| VEX Justification        | Select | `code_not_reachable`, `code_not_present`, `requires_configuration`, `requires_dependency`, and more                              |
| VEX Action Response      | Select | `can_not_fix`, `will_not_fix`, `update`, `rollback`, `workaround_available`                                                      |
| VEX Impact Statement     | Text   | Freeform impact description                                                                                                      |
| VEX Internal Notes       | Text   | Internal team notes                                                                                                              |
| VEX Action Statement     | Text   | Remediation action description — also pushed to Jira when updated in Interlynk                                                   |
| CVSS Score               | Number | CVSS vulnerability score                                                                                                         |
| Severity                 | Select | `critical`, `high`, `medium`, `low`                                                                                              |
| EPSS Score               | Number | Exploit Prediction Scoring System score                                                                                          |
| Fix Available            | Select | Whether a fix is available. Set automatically to `Yes` when the advisory lists a fixed version for the component, otherwise `No` |
| Interlynk SBOM Link      | URL    | Link back to the SBOM in Interlynk                                                                                               |

### Severity to Priority Mapping

| Interlynk Severity | Jira Priority |
| ------------------ | ------------- |
| Critical           | Highest       |
| High               | High          |
| Medium             | Medium        |
| Low                | Low           |
| Unknown            | Lowest        |

***

## Bidirectional Synchronization

### Jira to Interlynk (Pull Sync)

Interlynk polls Jira on a schedule to pull updates from Jira tickets back into vulnerability records.

**What syncs from Jira to Interlynk:**

* VEX Status changes
* VEX Justification updates
* VEX Action Response
* Impact and action statements
* Internal notes

**How it works:**

1. The `JiraVulnSyncJob` runs on a schedule for organizations with the feature enabled.
2. The job fetches Jira tickets in batches of 50 using JQL queries.
3. For each ticket, the sync handler compares field values between Jira and Interlynk.
4. Changed fields are applied to the corresponding Interlynk vulnerability record.
5. A `ComponentVulnLog` entry is created for audit purposes.

**Manual sync:** You can trigger an immediate sync from **Settings > Organization > Integrations > Ticketing** by clicking the sync button.

### Interlynk to Jira (Push Sync)

When VEX dispositions are updated in Interlynk, changes are pushed to the corresponding Jira ticket.

**What syncs from Interlynk to Jira:**

* VEX Status
* VEX Justification
* VEX Action Response
* Impact and action statements
* A comment is added to the Jira ticket documenting the change

**How it works:**

1. When a vulnerability disposition is updated in Interlynk, the `JiraVexPushJob` is triggered.
2. The reverse field mapper converts Interlynk values to Jira custom field option IDs.
3. The Jira ticket is updated via the Jira REST API.
4. A comment is added to the ticket for audit trail.

### Sync Configuration

| Setting                   | Description                                       |
| ------------------------- | ------------------------------------------------- |
| Enable Sync (per product) | Toggles bidirectional sync for a specific product |
| Last Synced At            | Timestamp of the most recent sync                 |
| Last Sync Status          | Success or failure (with error details)           |

{% hint style="info" %}
Bidirectional sync works across all configured Jira issue types, not just **InterlynkVuln**. If you use standard issue types (task, bug, story), VEX field sync operates on whichever custom fields those issue types expose.
{% endhint %}

***

## Organization-Level Jira Defaults

Set default Jira configuration for all products in the organization, so new products inherit sensible settings without manual per-product configuration:

1. Navigate to **Settings > Organization > Environments > Defaults**.
2. Find the **Jira Defaults** section.
3. Configure defaults for: Project, Work Type (Issue Type), Epic, Assignee, Reporter, and Components.
4. Choose whether to apply defaults to **all existing projects** or only **future projects**.

Per-product settings override organization defaults. If a product has no Jira configuration set, it inherits the organization defaults.

***

## Required Permissions

### Jira User Permissions

The Jira user account used for the integration requires:

| Permission             | Purpose                                                         |
| ---------------------- | --------------------------------------------------------------- |
| Browse Projects        | Read project metadata and issue types                           |
| Create Issues          | Create vulnerability tickets                                    |
| Edit Issues            | Update ticket fields during sync                                |
| Add Comments           | Add sync comments to tickets                                    |
| Manage Schemes (Admin) | Required for provisioning custom fields, workflows, and schemes |

### Interlynk Permissions

| Permission           | Purpose                                |
| -------------------- | -------------------------------------- |
| `view_connections`   | View Jira integration settings         |
| `edit_connections`   | Configure Jira connection and settings |
| `delete_connections` | Remove the Jira integration            |

### Permission Health Checks

Interlynk proactively checks the Jira user's permissions and reports any that are missing, so integration failures surface early rather than during ticket creation or sync.

***

## Security Notes

* Jira API tokens are encrypted at rest.
* The integration uses Jira REST API v3 — no webhooks are required. All synchronization is poll-based.
* Use a **dedicated Jira service account** rather than a personal account to avoid disruption if a team member leaves.
* Grant the Jira service account only the permissions listed above.
* The provisioning step creates resources in your Jira instance — coordinate with your Jira admin before initializing.

***

## Troubleshooting

| Issue                                          | Cause                                                           | Resolution                                                                                                        |
| ---------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Connection verification fails                  | Invalid URL, email, or API token                                | Re-check the Jira Host URL, email, and generate a new API token                                                   |
| Provisioning fails at a step                   | Insufficient Jira admin permissions                             | Ensure the Jira user has scheme management permissions                                                            |
| Tickets not created automatically              | Policy does not have "Create Ticket" enabled                    | Enable the flag on the policy and ensure the product has a Jira project configured                                |
| Sync not updating Interlynk                    | Sync disabled for the product                                   | Enable sync in the ticketing settings for the product                                                             |
| VEX fields missing on Jira ticket              | Provisioning not completed                                      | Complete the provisioning process or re-initialize. Provisioning replaces custom fields that Jira no longer lists |
| Ticket creation reports a missing Jira project | The Jira project set for the product cannot be found in Jira    | Set the Jira project key for the product in the ticketing settings                                                |
| Duplicate tickets                              | Multiple policies triggering for the same vulnerability         | Consolidate policies or use exclusion rules                                                                       |
| Sync shows errors                              | Jira API rate limits or network issues                          | Check the `last_sync_status` for error details; retry later                                                       |
| Components field not appearing in settings     | Selected project or issue type does not have a Components field | Verify the Jira project has a Components field enabled for the chosen issue type                                  |
| Test ticket creation disabled                  | No project or issue type selected                               | Select both Project and Work Type before using Create Test Ticket                                                 |
| Duplicate Jira connection                      | Attempting to add a second Jira connection for the same org     | Only one Jira connection is allowed per organization; edit the existing connection instead                        |

***

## Common Misconfigurations

| Issue                                 | Symptom                                         | Fix                                                             |
| ------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------- |
| Personal Jira account used            | Integration breaks when employee leaves         | Use a dedicated service account                                 |
| Jira project not associated           | Tickets fail to create                          | Associate the Jira project with vulnerability management config |
| Issue type not configured per product | Default issue type may not have required fields | Configure the correct issue type in ticketing settings          |
| Sync enabled but no project key set   | Sync job runs but finds nothing to sync         | Set the Jira project key for each product                       |

***

## Recommended Best Practices

* Use a **dedicated Jira service account** with scoped permissions.
* Enable **bidirectional sync** only for products actively being triaged — unnecessary sync adds API load.
* Use the **InterlynkVuln** issue type (created during provisioning) for full VEX field support.
* Configure **automatic ticket creation** via policies to reduce manual effort for high-severity vulnerabilities.
* Review **sync status** regularly in the ticketing settings to catch failed syncs early.
* Coordinate with your Jira admin before provisioning to avoid conflicts with existing schemes.
