> ## 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 to Rootly Sync

> Create and update Rootly incidents automatically from Jira events using alert workflows, with field mapping, status sync, and custom routing logic.

When a Jira issue is created or updated, Rootly can automatically create or update a corresponding incident. This enables bidirectional sync between the two systems — Jira events flow in through the webhook you configured during installation, appear as alerts in Rootly, and are processed by alert workflows.

<Warning>
  **Webhook Required** — You must first [set up a webhook](/integrations/jira/installation#setting-up-the-jira-webhook) in Jira to send events to Rootly before this will work.
</Warning>

***

## How It Works

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

<Steps>
  <Step title="Create a new workflow">
    Go to **Workflows → Create Workflow** and select **Alert** as the workflow type.
  </Step>

  <Step title="Set the trigger">
    Select **Alert Created** as the trigger. This fires whenever a new alert arrives in Rootly — including events from Jira.
  </Step>

  <Step title="Add conditions">
    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 (e.g., `$.issue.fields.issuetype.name`). You can preview your syntax using the [JSON Path Explorer](https://rootly.com/account/help/json-path-explorer).

    <Note>
      Only a single payload field can be filtered at a time. Use label conditions as much as possible before falling back to payload filtering.
    </Note>
  </Step>

  <Step title="Add an action">
    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.
  </Step>
</Steps>

***

## Actions

<Tabs>
  <Tab title="Create Incident">
    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 }}"
    }
    ```
  </Tab>

  <Tab title="Update Incident">
    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 }}` |
  </Tab>
</Tabs>

***

## Field Mapping Examples

Use Custom Field Mapping to dynamically set incident properties from Jira data.

<AccordionGroup>
  <Accordion title="Set Severity from Jira Priority">
    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 %}
    }
    ```
  </Accordion>

  <Accordion title="Set Status from Jira Status">
    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 %}
    }
    ```

    <Info>
      Valid Rootly statuses: `in_triage`, `active`, `resolved`, `closed`, `cancelled`
    </Info>
  </Accordion>

  <Accordion title="Set Custom Field (Hardcoded)">
    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"
      }]
    }
    ```
  </Accordion>

  <Accordion title="Set Custom Field (From Jira)">
    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 }}"
      }]
    }
    ```

    <Tip>
      Find the correct JSON path by inspecting alert payloads on the **Alerts** page in Rootly.
    </Tip>
  </Accordion>

  <Accordion title="Set Multi-Select Custom Field">
    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"]
      }]
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Debugging

| 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                           |

<Tip>
  View error details: **Workflows → Your Workflow → ... → View Runs → View**
</Tip>