> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rootly.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Jira
> Connect Jira to Rootly to create and update issues from incidents, and sync Jira changes back into Rootly.
Rootly's Jira integration keeps incidents and Jira issues in sync. When an incident is declared, a Jira issue is automatically created. Updates flow both ways: incident changes update Jira, and Jira changes can update incidents.
Auto-create Jira issues at incident start without building workflows
Advanced automation with triggers, conditions, and multiple actions
Map incident data to Jira native and custom fields
Follow-up tasks become Jira subtasks linked to the parent issue
***
## How It Works
Authenticate via OAuth and configure webhooks for bidirectional sync.
Use Smart Defaults for instant setup, or build custom workflows for conditional logic.
When an incident is created, Rootly automatically creates a Jira issue.
Changes to incidents update Jira. Jira events can trigger incident updates.
***
## Before You Begin
**Before you start, you'll need:**
* A Rootly account with **Admin** or **Owner** permissions
* A **Jira Cloud** account with admin rights to your instance
### Required Jira Permissions
The Jira account you use to install must have these permissions:
| Permission | Description |
| --------------------- | --------------------------------------------- |
| **Assign issues** | Ability to assign issues to users |
| **Close issues** | Ability to close issues |
| **Create issues** | Ability to create new issues |
| **Delete issues** | Ability to delete issues |
| **Edit issues** | Ability to edit existing issues |
| **Link issues** | Ability to link issues to one another |
| **Transition issues** | Ability to transition issues between statuses |
Learn more about Jira permissions in [Atlassian's documentation](https://confluence.atlassian.com/adminjiraserver073/managing-project-permissions-861253293.html).
### Required OAuth Scopes
Rootly requests these OAuth scopes during installation:
**Read permissions:**
* `read:application-role:jira`
* `read:avatar:jira`
* `read:field-configuration:jira`
* `read:group:jira`
* `read:issue:jira`
* `read:issue-status:jira`
* `read:issue-meta:jira`
* `read:issue-security-level:jira`
* `read:issue-type:jira`
* `read:issue-type-hierarchy:jira`
* `read:issue.changelog:jira`
* `read:issue.transition:jira`
* `read:issue.vote:jira`
* `read:priority:jira`
* `read:project:jira`
* `read:project-category:jira`
* `read:project-version:jira`
* `read:project.component:jira`
* `read:project.property:jira`
* `read:status:jira`
* `read:user:jira`
* `read:user.property:jira`
**Write permissions:**
* `write:attachment:jira`
* `write:comment:jira`
* `write:comment.property:jira`
* `write:issue:jira`
* `write:issue.property:jira`
## Installation
Setting up the Jira integration involves two parts: connecting your Jira account via OAuth and configuring a webhook so Jira can send events back to Rootly. Both are required for full bidirectional sync.
The OAuth flow connects your Jira Cloud instance to Rootly. You'll be redirected to Jira to authorize the connection, then returned to Rootly automatically.
In the Rootly sidebar, click **Configuration → Integrations**.
Search for **Jira Cloud** and click **Setup**.
You'll be redirected to Jira. Verify you're installing on the correct instance, then click **Accept**.
You'll be redirected back to Rootly with a success message confirming the connection.
Your Jira Cloud instance is now connected to Rootly.
### Installing Additional Instances
If your organization uses multiple Jira Cloud instances, you can connect them separately.
A Jira Cloud **instance** is not the same as a Jira **project**. An instance is a separate domain (for example, `company.atlassian.net`). You can have multiple projects within one instance — most organizations have a single instance with multiple projects.
To add another instance:
1. Go to **Integrations** and search for **Jira Cloud**
2. Click **Set up another instance**
3. Follow the same authorization flow
Make sure you're logged into the correct Jira instance in your browser before starting the authorization flow.
### Setting Up the Jira Webhook
To enable **Jira → Rootly sync**, you must configure a webhook in Jira. This allows Rootly to receive events when Jira issues are created or updated. Without this step, changes in Jira won't reflect back in Rootly.
In Jira, navigate to **Settings → System → WebHooks**.
Click **Create a WebHook**.
Give it a descriptive name (for example, "Rootly Webhook Listener") and ensure the status is set to **Enabled**.
In Rootly, go to **Integrations → Jira → Configure** and copy the webhook URL. Paste it into the **URL** field in Jira.
To limit which projects send events to Rootly, add a JQL filter under **Issue related events**. Leave this blank to receive events from all projects.
Choose the Jira events you want Rootly to receive — at minimum, select **issue created** and **issue updated**.
Ensure **Exclude body** is **not** checked. Jira may enable this by default, but Rootly requires the full event payload to process events correctly.
Click **Create** to save your webhook configuration.
Your Jira webhook is now configured for bidirectional sync.
## Verify Installation
Once connected, confirm the integration is working end-to-end:
1. **Check integration status** — The Jira tile in Rootly should show **Connected**.
2. **Test Rootly → Jira** — Create a test incident and verify that a Jira issue is created in the expected project.
3. **Test Jira → Rootly** — Create or update a Jira issue, then check the [Alerts page](https://rootly.com/account/alerts) in Rootly to confirm the event arrived.
If events appear on the Alerts page, your webhook is configured correctly.
## Workflows
**Setup fast and effortless**
Automatically create and manage Jira issues at incident start using pre-configured settings
Use workflows for conditional or advanced Jira issue automation
***
### Smart Defaults
Smart Defaults let you automatically generate a Jira issue whenever an incident begins — without building a workflow. New Rootly accounts have Smart Defaults enabled automatically. Existing accounts have it off by default to avoid conflicting with existing workflows.
To configure Smart Defaults, go to **Integrations → Jira → Configure**.
Configure webhooks in your Jira Admin using this endpoint to allow updates made in Jira to reflect back in Rootly.
See [Setting Up Jira Webhook](/integrations/jira/jira#setting-up-the-jira-webhook) for detailed steps.
This section controls how Jira tickets are created from Rootly incidents.
Automatically create a Jira ticket in the specified project as soon as an incident is declared in Rootly.
The Jira project where tickets will be created. If you need to route tickets to different projects based on conditions, disable this and use custom workflows instead.
The type of Jira issue to create. Options are pulled from the project specified in Project Key.
The initial status of the new ticket. Options are pulled from the selected project and issue type.
The Summary field of the Jira ticket. Defaults to `{{ incident.title }}`. Supports Liquid syntax.
The Description field of the Jira ticket. Defaults to `{{ incident.summary }}`. Supports Liquid syntax.
Assign the Jira ticket to a user by email address. If blank, the ticket is assigned to the incident creator. Supports Liquid syntax.
Automatically create a bookmark to the Jira ticket in the incident's Slack channel for quick access.
Automatically update the matching Jira ticket whenever the incident is updated. This is one-way: changes flow from Rootly to Jira only.
This section controls how Jira subtasks are created from Rootly action items.
Automatically create a Jira subtask under the parent Jira ticket every time a new action item is created in Rootly.
Leave this field **blank**. Jira subtasks can only be one type. This field will be expanded in a future release.
The initial status of the new subtask. Options are pulled from the project specified in Project Key.
Automatically update the matching Jira subtask whenever an action item is updated. This is one-way: changes flow from Rootly to Jira only.
Automatically set the Jira subtask priority to match the action item priority in Rootly.
Use Smart Defaults when you want instant, built-in Jira issue automation without touching workflows. Build a workflow when you need conditions, custom triggers, multiple actions, or more advanced issue routing.
***
### Custom Workflows
Custom workflows give you full control over when and how Jira issues are created or updated. You can filter by severity, service, environment, and more — or chain multiple Jira actions together in a single workflow.
Open **Rootly → Workflows → Create Workflow** and choose the workflow type that matches your use case.
Triggers define when the workflow runs. Choose the event that should create or update a Jira issue.
| Trigger | What it does |
| ------------------------------- | -------------------------------------------------------- |
| **Incident Created** | Creates a Jira issue as soon as a new incident is opened |
| **Incident Updated** | Fires when fields like severity or status change |
| **Incident Status Changed** | Triggers when the incident moves to a specific status |
| **Incident Commander Assigned** | Fires once someone takes ownership |
| **Manual Trigger** | Run manually from the UI when needed |
Choose the trigger that fires only when you actually need a Jira issue. Avoid creating issues earlier than necessary.
Conditions let you control when the workflow should run after it's been triggered. This keeps your Jira project clean by limiting automation to the incidents that matter.
Common condition setups:
* **Severity-based** — Only create Jira issues for SEV-1 or SEV-2 incidents
* **Team or service filters** — Only fire for incidents impacting specific teams or services
* **Incident type** — Ensure the workflow only runs when the Kind is set to Incident
* **Environment** — Trigger only for customer-facing or production-impacting incidents
Use conditions to avoid unnecessary Jira issues and keep the workflow focused.
Actions are the steps that run when the workflow fires. Click **Add Action**, then search for **Jira** to see the available actions.
#### Create Jira Issue
Creates a new Jira issue for an incident or retrospective.
Optional label for this action. Does not affect behavior.
The Jira project where the issue will be created.
The type of Jira issue to create (for example, Bug, Task, Story). Options are pulled from the selected project.
Title of the Jira issue. Supports Liquid syntax (for example, `{{ incident.title }}`).
Detailed description. Supports Liquid syntax (for example, `{{ incident.summary }}`).
Priority of the Jira issue (for example, High, Medium, Low).
Initial status of the issue. Options are pulled from the selected project and issue type.
Jira labels to categorize the issue. Supports multiple values.
Optional due date. Supports Liquid syntax or fixed dates.
The reporter for the Jira issue. Defaults to the incident creator. Supports Liquid syntax.
The assignee for the Jira issue. Supports Liquid syntax.
Prevents the workflow from stopping if this action fails.
Toggle this action on or off, useful when testing.
Use Rootly's [Liquid Variable Explorer](https://rootly.com/account/help/liquid-explorer) to test variables before using them in your workflow.
#### Update Jira Issue
Updates an existing Jira issue. You must reference the issue using `{{ incident.jira_issue_id }}` in the **Jira Issue to Update** field.
This action only works if a Jira issue has already been created and linked to the incident.
The Update Jira Issue action also works inside [Action Item Workflows](/workflows/action-item-workflows). When paired with the `Action Item Updated` trigger, it's the canonical way to enrich Jira tickets created via **Export to ticketing** with incident context (Rootly URL, severity, services, etc.) — see [Linking Exported Tasks Back to the Incident](/incidents/action-items/adding-action-items-via-web-ui#linking-exported-tasks-back-to-the-incident). In an action item workflow, use `{{ action_item.jira_issue_id }}` instead of the incident-side variable.
#### Create Jira Subtask
Creates a subtask under an existing Jira issue. Reference the parent issue using `{{ incident.jira_issue_id }}` in the **Parent Jira Issue** field. The **Project Key** must match the one used to create the parent issue.
This action is intended for action items or sub-incidents.
Give your workflow a descriptive name (for example, "Create Jira Issue on SEV-1 Incident"), then click **Create Workflow**.
***
### Action Reference
Creates a new ticket in a Jira project. You must select the **Project Key** and **Issue Type** for the ticket to be created correctly.
This action can be used for both incidents and action items. For action items, using **Create Jira Subtask** is recommended if your team uses subtasks — but if not, this action works as well.
The Jira project where the issue will be created.
The type of Jira issue to create. Options are pulled from the selected project.
The title of the Jira issue. Supports Liquid syntax (for example, `{{ incident.title }}`).
The description of the Jira issue. Supports Liquid syntax (for example, `{{ incident.summary }}`).
Assign the Jira issue to a user by email. Supports Liquid syntax.
Updates an existing ticket in Jira. You must reference the issue in the **Jira Issue to Update** field using `{{ incident.jira_issue_id }}`.
This action only works if a Jira issue has already been created and linked to the incident.
Reference to the existing Jira issue. Use `{{ incident.jira_issue_id }}` to dynamically target the issue linked to the current incident.
Updated title of the Jira issue. Supports Liquid syntax.
Updated description. Supports Liquid syntax.
Transition the issue to a new status. Options are pulled from the selected project and issue type.
Reassign the Jira issue to a different user. Supports Liquid syntax.
Creates a subtask under an existing Jira issue. Intended for **action items** or **sub-incidents**. The **Project Key** must match the one used when creating the parent issue.
Reference to the parent Jira issue. Use `{{ incident.jira_issue_id }}` to link the subtask to the current incident's issue.
Must match the project used to create the parent issue.
Title of the subtask. Supports Liquid syntax.
Description of the subtask. Supports Liquid syntax.
Assign the subtask to a user by email. Supports Liquid syntax.
***
### Jira Native Field Mapping
Some Jira fields behave differently than standard custom fields. This section explains how to correctly map Rootly fields to Jira's **native** fields.
These mappings go in the **Custom Fields Mapping** section of the Jira action, not the API Payload section.
Jira's native Labels field uses a different syntax than custom label-type fields.
**Map Rootly services to Jira Labels:**
```json theme={null}
"customfield_12345": {{ incident.service_slugs | join: ","}}
```
**Map a Rootly custom multi-select to Jira Labels:**
```json theme={null}
"customfield_10033": {{ incident.custom_fields | find: 'custom_field.slug', 'your_custom_field_slug' | get: 'selected_options' | map: 'value' | join: "," }}
```
Replace `customfield_12345` with your actual Jira field ID. Find field IDs in **Jira Settings → Issues → Custom Fields**.
Jira's native Team field is stored as a custom field but only allows a single team selection.
**Map a static Jira Team ID:**
```json theme={null}
"customfield_10001": ""
```
**Map Rootly's first team dynamically:**
```json theme={null}
"customfield_10001": "{{ incident.raw_groups[0] | get: 'description' }}"
```
This example assumes you store the corresponding Jira Team ID in the Rootly team's description field. Adjust based on how your teams are configured.
***
### Custom Fields Mapping
The **Custom Fields Mapping** section lets you map Rootly incident data to Jira custom fields dynamically.
#### What You Need
| Item | Where to Find It |
| ------------------- | --------------------------------------------------------------------------------------------------- |
| **Jira Field ID** | Jira Settings → Issues → Custom Fields → Click field → ID in URL (for example, `customfield_12345`) |
| **Field Type** | Same location, check the field type (text, select, multi-select, etc.) |
| **Rootly Property** | Use the [Liquid Variable Explorer](https://rootly.com/account/help/liquid-explorer) |
For detailed instructions on finding Jira field IDs, see [Atlassian's documentation](https://confluence.atlassian.com/jirakb/how-to-find-id-for-custom-field-s-744522503.html).
#### Field Type Mappings
```json theme={null}
// Rootly native field → Jira text
"customfield_12345": "{{ incident.functionalities }}"
// Rootly custom field → Jira text
"customfield_12345": "{{ incident.custom_fields | find: 'custom_field.slug', 'your-slug' | get: 'selected_options' | map: 'value' }}"
```
Note the `{ "value": ... }` wrapper required by Jira:
```json theme={null}
// Rootly team name → Jira single select
"customfield_12345": { "value": "{{ incident.raw_groups | first | get: 'name' }}" }
// Rootly custom field → Jira single select
"customfield_12345": { "value": "{{ incident.custom_fields | find: 'custom_field.slug', 'your_slug' | get: 'selected_options' | map: 'value' }}" }
```
**Simple approach (Rootly custom multi-select):**
```json theme={null}
"customfield_12345": {{ incident.custom_fields | find: 'custom_field.slug', 'your_slug' | get: 'selected_options' | to_values }}
```
**Manual array building (Rootly native fields):**
```liquid theme={null}
{% assign functions = incident.functionalities %}
{% assign array = "" %}
{% for function in functions %}
{% assign item = '{"value":"' | append: function | append: '"}' %}
{% assign array = array | append: item | append: "," %}
{% endfor %}
{% capture final_array %}[{{ array | remove_last: ',' }}]{% endcapture %}
"customfield_12345": {{ final_array }}
```
For Jira custom fields of type "Labels" (different from the native Labels field):
```json theme={null}
// Rootly services → Jira custom labels
"customfield_12345": {{ incident.service_slugs | to_json }}
// Rootly custom multi-select → Jira custom labels
"customfield_10033": {{ incident.custom_fields | find: 'custom_field.slug', 'your_slug' | get: 'selected_options' | map: 'value' | to_json }}
```
```json theme={null}
"customfield_26117": {{ incident.custom_fields | find: 'custom_field.slug', 'your_slug' | get: 'selected_options.value' }}
```
Must use ISO 8601 format:
```json theme={null}
// Rootly incident start time → Jira datetime
"customfield_10030": "{{ incident.started_at | date: '%FT%T%:z' }}"
// Rootly custom datetime → Jira datetime
"customfield_26218": "{{ incident.custom_fields | find: 'custom_field.slug', 'your_slug' | get: 'selected_options.value' | date: '%Y-%m-%dT%H:%M:%S.%d%z' }}"
```
**Single user:**
```json theme={null}
{% assign jira_email = incident.roles | find: 'incident_role.slug', 'incident-commander' | get: 'user.email' %}
"customfield_20825": { "id": "{{ team.jira_users | where: 'email', jira_email | first | get: 'account_id' }}" }
```
**Multiple users:**
```json theme={null}
{% assign jira_email = incident.roles | find: 'incident_role.slug', 'incident-commander' | get: 'user.email' %}
"customfield_20825": [{ "id": "{{ team.jira_users | where: 'email', jira_email | first | get: 'account_id' }}" }]
```
#### How to Test Your Mapping
1. Create a test incident in Rootly
2. Run your workflow manually
3. Check the Jira issue to verify fields are populated correctly
4. If errors occur, go to **Workflows → Your Workflow → ... → View Runs** to see the error details
***
### API Payload
The **API Payload** section provides direct access to Jira's REST API for advanced field updates not available through Custom Fields Mapping.
API Payload uses Jira's [update issue REST API](https://developer.atlassian.com/server/jira/platform/updating-an-issue-via-the-jira-rest-apis-6848604/). Fields use verb-based operations: `set`, `add`, and `remove`.
#### When to Use API Payload
| Use Case | Use API Payload |
| ------------------------ | ----------------------------------- |
| Set priority dynamically | Yes |
| Add comments | Yes (Update Jira Issue action only) |
| Link issues together | Yes |
| Set native Labels field | Yes |
| Set Components field | Yes |
| Map custom fields | No, use Custom Fields Mapping |
#### API Payload Examples
```liquid theme={null}
{% if incident.severity_slug == 'sev0' %}
{ "priority": [ { "set": { "name" : "High" } } ] }
{% elsif incident.severity_slug == 'sev1' %}
{ "priority": [ { "set": { "name" : "Medium" } } ] }
{% elsif incident.severity_slug == 'sev2' %}
{ "priority": [ { "set": { "name" : "Low" } } ] }
{% endif %}
```
Add a comment to an existing Jira issue. Only works with the **Update Jira Issue** action.
```json theme={null}
{
"comment": [
{
"add": {
"body": "Incident {{ incident.title }} has been updated. Current status: {{ incident.status }}"
}
}
]
}
```
Comments can only be added to existing issues. Use this with the Update Jira Issue action, not Create.
**"Relates to" link:**
```json theme={null}
{
"issuelinks": [
{
"add": {
"type": { "name": "Relates", "outward": "relates to" },
"outwardIssue": { "id": "{{ incident.jira_issue_id }}" }
}
}
]
}
```
**Custom "Action item for" link:**
```json theme={null}
{
"issuelinks": [
{
"add": {
"type": { "name": "Action", "outward": "action item for" },
"outwardIssue": { "id": "{{ incident.jira_issue_id }}" }
}
}
]
}
```
```json theme={null}
{
"labels": [{ "set": ["incident", "production", "{{ incident.severity }}"] }]
}
```
```liquid theme={null}
{% assign components = incident.services %}
{
"components": [
{
"set": [
{% for component in components %}
{ "name": "{{ component }}" }{% unless forloop.last %},{% endunless %}
{% endfor %}
]
}
]
}
```
Component names must match exactly between Rootly and Jira. If a component doesn't exist in Jira, the update will fail.
#### API Payload Verbs
| Verb | Description | Example |
| -------- | ------------------------- | ------------------------------------------------ |
| `set` | Replace the current value | `{ "labels": [{ "set": ["label1"] }] }` |
| `add` | Add to current values | `{ "comment": [{ "add": { "body": "text" } }] }` |
| `remove` | Remove specific values | `{ "labels": [{ "remove": "old-label" }] }` |
***
### Best Practices
* **Name workflows clearly.** Use names like `Create Bug on High-Priority Incident` or `Update Jira Issue on Resolution` so the intent is obvious.
* **Keep logic simple.** Avoid overly complex conditions or chained automations — simpler workflows are easier to debug.
* **Test in a sandbox project.** Before applying to production, trigger test incidents to verify issues are created and updated as expected.
## Syncing Jira Changes Back to Rootly
1. Jira sends events to Rootly via webhook
2. Events appear as alerts on Rootly's **[Alerts page](https://rootly.com/account/alerts)**
3. Alert workflows process these events and create or update incidents
***
### Create an Alert Workflow
Go to **Workflows → Create Workflow** and select **Alert** as the workflow type.
Select **Alert Created** as the trigger. This fires whenever a new alert arrives in Rootly — including events from Jira.
Filter to only process Jira alerts so the workflow doesn't fire on unrelated alert sources. You can filter by source and by label:
* Set **Source** equals `Jira`
* Use label filters to narrow by event type or project:
* `event:jira:issue_created` — responds to new Jira issues
* `event:jira:issue_updated` — responds to Jira issue updates
* `project_key:YOUR_PROJECT` — (optional) limits to a specific Jira project
For more targeted filtering, use the **Payload** condition with JSON path syntax (for example, `$.issue.fields.issuetype.name`). You can preview your syntax using the [JSON Path Explorer](https://rootly.com/account/help/json-path-explorer).
Only a single payload field can be filtered at a time. Use label conditions as much as possible before falling back to payload filtering.
Choose **Create Incident** or **Update Incident** from the action picker depending on whether you want to open a new incident or update an existing one.
***
### Sync Actions
Creates a new Rootly incident from a Jira alert.
Use `{{ alert.data.* }}` to reference Jira fields when populating incident properties:
| Incident Field | Jira Source |
| -------------- | ------------------------------------------- |
| Title | `{{ alert.data.issue.fields.summary }}` |
| Summary | `{{ alert.data.issue.fields.description }}` |
**Link back to Jira** — Add this to Custom Field Mapping so Rootly knows which Jira issue this incident came from. This mapping is required if you later want to update the incident when the Jira issue changes.
```json theme={null}
{
"jira_issue_id": "{{ alert.data.issue.id }}",
"jira_issue_url": "https://your-instance.atlassian.net/browse/{{ alert.data.issue.key }}"
}
```
Updates an existing Rootly incident based on a Jira update. Rootly needs to know which incident corresponds to the incoming Jira event — configure these fields to match them:
| Field | Value |
| ------------------ | --------------------------- |
| Attribute to Match | `jira_issue_id` |
| Attribute Value | `{{ alert.data.issue.id }}` |
***
### Field Mapping Examples
Use Custom Field Mapping to dynamically set incident properties from Jira data.
Maps Jira priority levels to Rootly severity IDs. Adjust the priority names to match your Jira configuration.
```json theme={null}
{
{% if alert.data.issue.fields.priority.name == 'Highest' %}
"severity_id": "SEV0"
{% elsif alert.data.issue.fields.priority.name == 'High' %}
"severity_id": "SEV1"
{% elsif alert.data.issue.fields.priority.name == 'Medium' %}
"severity_id": "SEV2"
{% else %}
"severity_id": "SEV3"
{% endif %}
}
```
Maps Jira workflow statuses to Rootly incident statuses. Replace the Jira status names with your actual values.
```json theme={null}
{
{% if alert.data.issue.fields.status.name == 'To Do' %}
"status": "in_triage"
{% elsif alert.data.issue.fields.status.name == 'In Progress' %}
"status": "active"
{% elsif alert.data.issue.fields.status.name == 'Done' %}
"status": "resolved"
{% else %}
"status": "cancelled"
{% endif %}
}
```
Valid Rootly statuses: `in_triage`, `active`, `resolved`, `closed`, `cancelled`
Sets a Rootly custom field to a fixed value. Replace `form_field_id` with your actual field ID.
```json theme={null}
{
"form_field_selections_attributes": [{
"form_field_id": "YOUR_FIELD_ID",
"value": "Production"
}]
}
```
Pulls a value from a Jira custom field and sets it on the Rootly incident. Inspect the alert payload to find the correct field path.
```json theme={null}
{
"form_field_selections_attributes": [{
"form_field_id": "YOUR_FIELD_ID",
"value": "{{ alert.data.issue.fields.customfield_10001 }}"
}]
}
```
Find the correct JSON path by inspecting alert payloads on the **Alerts** page in Rootly.
For single or multi-select Rootly custom fields, use `selected_option_ids` instead of `value`.
```json theme={null}
{
"form_field_selections_attributes": [{
"form_field_id": "YOUR_FIELD_ID",
"selected_option_ids": ["option_id_1", "option_id_2"]
}]
}
```
***
## Troubleshooting
**Issue:** After completing OAuth, Jira doesn't show under Connected Apps.
**Solutions:**
* Ensure you completed the full OAuth consent flow without navigating away
* Confirm your Jira user has **admin** or **manage apps** permissions
* Log out of other Jira accounts and retry authorization
* Revoke the app in Jira (**Settings → Apps → Manage Apps**) and reconnect
**Issue:** Jira connects but no projects appear in Rootly.
**Solutions:**
* Verify your Jira account has **Browse Projects** permission
* Check project-level permissions for **Create Issues**, **Edit Issues**, and **Add Comments**
* Re-authenticate to refresh your permission scopes
**Issue:** Integration connects but Rootly can't create issues in Jira.
**Solutions:**
* Verify your Jira user has: Create Issues, Edit Issues, Assign Issues, Add Comments
* Check for required custom fields in Jira that aren't being populated by Rootly
* Confirm the issue type exists in the selected project
* Review Jira workflow validators that may block external issue creation
**Issue:** Jira events don't show on Rootly's Alerts page.
**Solutions:**
* Verify the webhook URL in Jira matches the one from Rootly
* Ensure **Exclude body** is NOT checked in the Jira webhook settings
* Confirm the webhook status is **Enabled**
* Check that your JQL filter (if used) includes the project you're testing with
### Debugging Workflows
To view error details, locate the workflow in Rootly, then select **... → View Runs → View**.
| Error | Cause | Fix |
| -------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------- |
| `issue_id cannot be null.` | The Jira issue you're trying to update doesn't exist yet | Ensure the Create action runs before the Update action |
| `"customfield_12345": "Custom Field is required."` | A required Jira custom field isn't being populated | Add a mapping for the field, or make it optional in Jira |
| `unexpected token at '{ "customfield_10032": }'` | Custom mapping syntax is invalid | Fix your JSON syntax |
| `Specify a valid project ID or key` | The selected Project Key isn't available in the Jira instance | Reselect the Jira instance, then reselect the Project Key |
| `The issue type selected is invalid.` | The selected issue type doesn't exist in the project | Reselect the Project Key, then reselect the Issue Type |
***
### Debugging Sync
| Error | Cause | Fix |
| -------------------------------- | ---------------------------------- | ------------------------------------------------ |
| `unknown attribute for Incident` | Invalid field name or wrong syntax | Verify the field is enabled for workflow updates |
| `unexpected token` | Invalid JSON in custom mapping | Check your JSON syntax |
View error details: **Workflows → Your Workflow → ... → View Runs → View**
## Uninstall
To remove the Jira integration:
1. Go to **Configuration → Integrations** and find **Jira**
2. Click **Connected** to reveal the disconnect option
3. Click **Disconnect**
Disconnecting Rootly does **not** remove the webhook from Jira. To stop Jira from sending events, you must also delete the webhook in Jira under **Settings → System → WebHooks**.