> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plerion.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Jira
> Integrate Plerion with Jira to automatically create and track findings, vulnerabilities, and risks, helping your team manage work in Atlassian’s project management platform.
With the [Jira integration](https://app.plerion.com/settings/integrations/add/Jira/Jira), you can send alerts from Plerion directly into your chosen Jira project, allowing your team to prioritize and resolve issues within your existing workflows.
**Note:** This is a one-way outbound integration. Issues created or updated in Plerion will appear in Jira, but changes made directly in Jira will not sync back to Plerion.
## Steps for adding a Jira integration
Review the requested permissions and click `Accept` to authorize the connection.
If you have access to multiple Jira instances, carefully select the correct one.
This choice can only be made once.
If you select the wrong instance, you must delete the Jira integration and set it up again. If you skip this step, the integration status will remain as **'Pending'** and cannot be used in workflows.
After adding Jira, you can send a test issue to confirm the setup.\
Choose the Jira project and issue type for the test issue.
If the test is successful, Plerion will display a link to the created Jira issue, as shown below.
***
## Create a workflow on Plerion
After adding the Jira integration, you must create a workflow for any alerts to be sent to Jira.
Enter a workflow name and ensure the Enabled toggle is turned on.
* Under **Conditions**, you can build the workflow using any of the three available condition categories:
* **Asset**
* **Findings**
* **Vulnerabilities**
Under **Actions**, click `Add action` and select your Jira integration.\
Add your Jira project, issue type and resolved status.
To set more fields on each issue, such as Priority or Assignee, see [Map Jira fields](#map-jira-fields).
Click `Save` to finish setting up your workflow.
***
## Map Jira fields
With **Field mapping** in a workflow's Jira action, you can fill in the fields of every issue Plerion creates, either from a Plerion field or from a fixed value. The fields on offer come from the Jira create screen of the project and issue type you select in the action, so select those first.
### Fields you can set
Plerion offers every field you can set on that create screen:
* **Built-in fields:** Priority, Labels, Components, Assignee, Reporter, Due date, Fix versions, Affects versions, Environment, Parent and Security level.
* **Custom fields:** text, number, date, date-time, single select, multi-select, checkboxes, labels and user picker fields.
* **Jira Service Management:** the **Organizations** field.
Cascading select fields aren't offered. Plerion always sets the project, issue type, summary and description itself. To send a field that isn't offered, use [custom JSON](#add-custom-json).
Each field in the **Jira fields** list shows its type in brackets, such as **Priority (Single choice)** or **Labels (List)**.
### Steps to map a field
Select the **Project** and **Issue type**. The field list loads from Jira for this pair.
A new row appears.
Choose the field under **Jira fields**.
* **Plerion field:** the value comes from the alert. Choose the field under **Plerion fields**.
* **Fixed value:** every issue gets the same value.
* **Days after creation:** shown instead of **Fixed value** for date and date-time fields. Enter a whole number of days from 0 to 3650, and Plerion sets the date that many days after the issue is created.
For a fixed value, the input matches the Jira field. See [Fixed value inputs](#fixed-value-inputs).
Click `Save` to save the workflow. You can [send a test issue](#send-a-test-issue) first to check the mapping.
To remove a row, click the remove button at the end of it. Required rows can't be removed.
### Fixed value inputs
| Jira field type | Examples | Input |
| - | - | - |
| Single choice | Priority, Security level, single select | Dropdown of the field's options in Jira |
| Multiple choice | Components, Fix versions, Affects versions, multi-select, checkboxes | Multi-select of the field's options in Jira |
| List | Labels | Type a value and press Enter to add it |
| User or Users | Assignee, Reporter, user picker | Search Jira users by name and pick from the list. For **Assignee**, the search covers people who can be assigned issues in the project |
| Organizations | Organizations | Search the organizations linked to the project's service desk |
| Issue | Parent | Issue key, such as `ABC-123` |
| Text or Number | Environment, text and number fields | Text or number input |
| Date or Date and time | Due date, date and date-time fields | **Days after creation** |
For **Organizations**, if no organizations are linked to the project's service desk, or Plerion can't list them, type the organization IDs instead. Organization IDs are whole numbers, such as `32`. If the field asks you to reconnect Jira, see [Update Jira permissions](#update-jira-permissions).
### Map severity to a Jira value
When you set a single-choice Jira field, such as **Priority**, from a Plerion field that has a fixed set of values, the row expands into a table. **Severity** is that kind of field: for each of its values (**Critical**, **High**, **Medium**, **Low** and **Informational**), pick the **Jira value** to send.
Map at least one value. A severity left as **Not sent** sends nothing, so Jira's default for the field applies.
Plerion works out the severity of an alert as follows:
* **Finding alerts:** the severity of the finding.
* **Vulnerability alerts:** the severity level of the vulnerability.
* **Other alerts:** a band of the asset's risk score.
| Risk score | Severity |
| - | - |
| 0 or no score | Informational |
| Above 0 and below 4 | Low |
| 4 to below 7 | Medium |
| 7 to below 9 | High |
| 9 or above | Critical |
### Required fields
When you select a project and issue type, Plerion adds a row for every field Jira requires on the create screen, unless Jira has a default for it or your custom JSON already sets it. These rows are marked **Required**, can't be removed, and need a value before you can save the workflow. If you change the project or issue type, Plerion clears your field mappings and adds the required fields for the new project and issue type. Your custom JSON is kept.
### Add custom JSON
Tick **Add custom JSON** to send Jira fields the list doesn't offer, such as a cascading select. Enter a JSON object keyed by Jira field ID:
```json theme={"system"}
{
"customfield_10050": { "value": "APAC", "child": { "value": "Sydney" } }
}
```
Plerion merges these fields into each new issue. The editor checks the JSON as you type, and you can't save while it shows an error. The rules are:
* Keys are Jira field IDs, such as `customfield_10004` or `labels`.
* `project`, `issuetype`, `summary` and `description` aren't allowed. Plerion sets these itself.
* A field a row already sets isn't allowed. Set each field in one place only.
* At most 50 fields, 8 KB in total, and nested at most 5 levels deep.
Anyone who can view workflows or alerts in Plerion can see the custom JSON. Don't include secrets.
### When Plerion sets each field
* **When the issue is created:** Plerion sends every row and the custom JSON.
* **When the alert changes later:** Plerion sends only the rows set from a Plerion field, including severity tables, along with the summary and description. Fixed values, days after creation and custom JSON aren't sent again, so changes your team makes to those fields in Jira stay in place.
### Send a test issue
Click `Send test issue` below the field mapping to create one real issue in Jira from a sample alert. The test uses the whole mapping as it is on screen, including changes you haven't saved yet.
* The button is available once a project and issue type are selected and the mapping has no errors.
* The test issue's summary starts with `[Plerion test]` and it has the label `plerion-test`.
* If Jira creates the issue, **Test issue created** appears with a link to it.
* If Jira rejects the issue, **Jira rejected the test issue** appears. Jira's message for a field shows next to that field's row, and any other messages are listed under the heading.
The test issue stays in Jira. Delete it there when you're done.
### Example: share issues with a customer organization and set priority from severity
This example uses a Jira Service Management project whose service desk has an organization called **Acme**. Under **Field mapping**:
* Add a row for **Organizations**, choose **Fixed value**, then search for and select **Acme**.
* Add a row for **Priority**, choose **Plerion field**, then select **Severity** and fill in the table:
| Plerion value | Jira value |
| - | - |
| Critical | Highest |
| High | High |
| Medium | Medium |
| Low | Low |
| Informational | Not sent |
* Click `Send test issue` and check the new issue in Jira.
* Click `Save`.
Every new issue is shared with Acme. Its priority follows the alert's severity, and informational alerts get the project's default priority. Because Priority comes from a Plerion field, Plerion sends it again whenever it updates the issue, while the organization set at creation stays as your team leaves it.
***
## Update Jira permissions
Picking organizations by name needs the latest Jira permissions. Jira integrations connected before this feature show an `Update permissions` button on the integration page. The integration stays **Active** and keeps sending alerts until you update.
Review the requested permissions and click `Accept`.
Until you update, you can still type organization IDs in the **Organizations** field.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.