Workflows

Rootly gives you two ways to automate Jira issue creation and updates. Smart Defaults provides instant, zero-configuration automation. Custom Workflows let you add conditions, multiple actions, and advanced routing logic.

Automation Options

Smart Defaults

Setup fast and effortlessAutomatically create and manage Jira issues at incident start using pre-configured settings

Custom Workflow

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.

Webhook

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 for detailed steps.

Jira webhook URL configuration in Rootly

Jira Ticket for Incidents

This section controls how Jira tickets are created from Rootly incidents.

Jira ticket configuration panel for incidents

Create Jira ticket for all new incidents

toggle

Automatically create a Jira ticket in the specified project as soon as an incident is declared in Rootly.

Project Key

select

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.

Issue Type

select

The type of Jira issue to create. Options are pulled from the project specified in Project Key.

Issue Status

select

The initial status of the new ticket. Options are pulled from the selected project and issue type.

Title / Summary

string

The Summary field of the Jira ticket. Defaults to {{ incident.title }}. Supports Liquid syntax.

Description

string

The Description field of the Jira ticket. Defaults to {{ incident.summary }}. Supports Liquid syntax.

Default Assignee

string

Assign the Jira ticket to a user by email address. If blank, the ticket is assigned to the incident creator. Supports Liquid syntax.

Auto-bookmark Jira ticket in Slack

toggle

Automatically create a bookmark to the Jira ticket in the incident’s Slack channel for quick access.

Update Jira ticket when incident is updated

toggle

Automatically update the matching Jira ticket whenever the incident is updated. This is one-way: changes flow from Rootly to Jira only.

Jira Ticket for Action Items

This section controls how Jira subtasks are created from Rootly action items.

Jira subtask configuration for action items

Create Jira subtask ticket for action items

toggle

Automatically create a Jira subtask under the parent Jira ticket every time a new action item is created in Rootly.

Subtask Type

select

Leave this field blank. Jira subtasks can only be one type. This field will be expanded in a future release.

Subtask Status

select

The initial status of the new subtask. Options are pulled from the project specified in Project Key.

Update Jira subtask ticket for action items

toggle

Automatically update the matching Jira subtask whenever an action item is updated. This is one-way: changes flow from Rootly to Jira only.

Match action item priority

toggle

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.

Create a new workflow

Open Rootly → Workflows → Create Workflow and choose the workflow type that matches your use case.

Workflow type selection showing Incident, Retrospective, and Pulse options

Configure triggers

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.

Add conditions

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.

Workflow conditions panel showing filter options

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.

Add a Jira action

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.

Name

string

Optional label for this action. Does not affect behavior.

Project Key

select

The Jira project where the issue will be created.

Issue Type

select

The type of Jira issue to create (e.g., Bug, Task, Story). Options are pulled from the selected project.

Summary / Title

string

Title of the Jira issue. Supports Liquid syntax (e.g., {{ incident.title }}).

Description

string

Detailed description. Supports Liquid syntax (e.g., {{ incident.summary }}).

Priority

select

Priority of the Jira issue (e.g., High, Medium, Low).

Status

select

Initial status of the issue. Options are pulled from the selected project and issue type.

Labels

array

Jira labels to categorize the issue. Supports multiple values.

Due Date

string

Optional due date. Supports Liquid syntax or fixed dates.

Reporter (email address)

string

The reporter for the Jira issue. Defaults to the incident creator. Supports Liquid syntax.

Assignee (email address)

string

The assignee for the Jira issue. Supports Liquid syntax.

Skip on Failure

toggle

Prevents the workflow from stopping if this action fails.

Enabled

toggle

Toggle this action on or off, useful when testing.

Use Rootly’s Liquid Variable 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.

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.

Name and save the workflow

Give your workflow a descriptive name (e.g., “Create Jira Issue on SEV-1 Incident”), then click Create Workflow.

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.

Labels (Native Jira Field)

Jira’s native Labels field uses a different syntax than custom label-type fields.Map Rootly services to Jira Labels:

"customfield_12345": {{ incident.service_slugs | join: ","}}

Map a Rootly custom multi-select to Jira Labels:

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

Team (Native Jira Field)

Jira’s native Team field is stored as a custom field but only allows a single team selection.Map a static Jira Team ID:

"customfield_10001": "<jira_team_id>"

Map Rootly’s first team dynamically:

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

Advanced tab for custom field mapping in Jira action

What You Need

Item	Where to Find It
Jira Field ID	Jira Settings → Issues → Custom Fields → Click field → ID in URL (e.g., `customfield_12345`)
Field Type	Same location, check the field type (text, select, multi-select, etc.)
Rootly Property	Use the Liquid Variable Explorer

For detailed instructions on finding Jira field IDs, see Atlassian’s documentation.

Field Type Mappings

Text and Paragraph Fields

// 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' }}"

Single Select Fields

Note the { "value": ... } wrapper required by Jira:

// 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' }}" }

Multi-Select Fields

Simple approach (Rootly custom multi-select):

"customfield_12345": {{ incident.custom_fields | find: 'custom_field.slug', 'your_slug' | get: 'selected_options' | to_values }}

Manual array building (Rootly native fields):

{% 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 }}

Labels Fields (Custom)

For Jira custom fields of type “Labels” (different from the native Labels field):

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

Number Fields

"customfield_26117": {{ incident.custom_fields | find: 'custom_field.slug', 'your_slug' | get: 'selected_options.value' }}

Date/Time Fields

Must use ISO 8601 format:

// 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' }}"

User Fields

Single user:

{% 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:

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

Create a test incident in Rootly
Run your workflow manually
Check the Jira issue to verify fields are populated correctly
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. 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

Set Priority Based on Severity

{% 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 Comments

Add a comment to an existing Jira issue. Only works with the Update Jira Issue action.

{
  "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.

Link Issues Together

“Relates to” link:

{
  "issuelinks": [
    {
      "add": {
        "type": { "name": "Relates", "outward": "relates to" },
        "outwardIssue": { "id": "{{ incident.jira_issue_id }}" }
      }
    }
  ]
}

Custom “Action item for” link:

{
  "issuelinks": [
    {
      "add": {
        "type": { "name": "Action", "outward": "action item for" },
        "outwardIssue": { "id": "{{ incident.jira_issue_id }}" }
      }
    }
  ]
}

Set Native Labels Field

{
  "labels": [{ "set": ["incident", "production", "{{ incident.severity }}"] }]
}

Set Components Field

{% 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" }] }`

Debugging

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

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.

Overview & General

CLI & Developer Tools

Communication & Collaboration

Alerting & Monitoring

Observability & APM

Documentation & Knowledge Management

Issue & Project Management

Video Conferencing

Development & CI/CD

Status & Communication

Data & Analytics

AI & Automation

Infrastructure & Security

Calendar & Scheduling

Service Catalogs

Automation Options

Smart Defaults

Custom Workflow

Smart Defaults

Custom Workflows

Create Jira Issue

Update Jira Issue

Create Jira Subtask

Jira Native Field Mapping

Custom Fields Mapping

What You Need

Field Type Mappings

How to Test Your Mapping

API Payload

When to Use API Payload

API Payload Examples

API Payload Verbs

Debugging

Best Practices

Overview & General

CLI & Developer Tools

Communication & Collaboration

Alerting & Monitoring

Observability & APM

Documentation & Knowledge Management

Issue & Project Management

Video Conferencing

Development & CI/CD

Status & Communication

Data & Analytics

AI & Automation

Infrastructure & Security

Calendar & Scheduling

Service Catalogs

​Automation Options

Smart Defaults

Custom Workflow

​Smart Defaults

​Custom Workflows

​Create Jira Issue

​Update Jira Issue

​Create Jira Subtask

​Jira Native Field Mapping

​Custom Fields Mapping

​What You Need

​Field Type Mappings

​How to Test Your Mapping

​API Payload

​When to Use API Payload

​API Payload Examples

​API Payload Verbs

​Debugging

​Best Practices

Automation Options

Smart Defaults

Custom Workflows

Create Jira Issue

Update Jira Issue

Create Jira Subtask

Jira Native Field Mapping

Custom Fields Mapping

What You Need

Field Type Mappings

How to Test Your Mapping

API Payload

When to Use API Payload

API Payload Examples

API Payload Verbs

Debugging

Best Practices