Jira Cloud

FireHydrant can create tickets in Jira for each of your incidents, with linked tickets for follow-ups to prioritize after the incident. This way, all actions proposed during an incident are tracked in your existing project management workflows for estimation and scheduling.

All steps in this document are required unless otherwise noted.

Prerequisites

  • You'll need to be an Owner in FireHydrant to configure integrations
  • You need a service account/user in Jira with the following permissions:
    • Project Permissions
      • Browse Projects
    • Issue Permissions
      • Assign Issues
      • Close Issues
      • Create Issues
      • Edit Issues
      • Link Issues
      • Move Issues
      • Schedule Issues
    • Other Permissions
      • Read all Jira ticket types to be used with FireHydrant
      • Read all Jira fields and custom fields to be mapped in FireHydrant

📘

Note:

FireHydrant recommends using a generic Jira Cloud service account rather than an individual named user to avoid problems if the named employee were to depart the organization.

Installing Jira Cloud integration

🚧

Note:

Ensure you are currently logged into Jira as the service account and not in your personal account, otherwise the connection will be established with your personal account.

Integrations page Jira cloud

Finding the Jira tile in integrations

  1. Go to the Integrations page and search for the Jira Cloud integration. You can also view our Jira Marketplace listing, which lists the same instructions.
  2. Click the '+', and then click Authorize Application. This will take you to Jira where you can authorize FireHydrant's application. Follow through the on-screen prompts.

Configuring webhook to FireHydrant

To see updates to your tickets reflected in FireHydrant, you must configure an outbound webhook from Jira back to FireHydrant.

Jira integration settings page with generated webhook URL

Jira integration settings page with generated webhook URL

  1. Once you finish installing Jira, you should be taken back to the Jira integrations page, where you should see a Webhook URL. Copy this URL.
  2. In Jira, configure a Webhook listener for FireHydrant using the copied URL. This is under Settings > System > WebHooks. On this screen, click "+".
  3. Set this webhook for the projects you plan to use with FireHydrant (or all issues), and then check the Issue created and Issue updated boxes.
Creating a new webhook in Jira

Creating a new webhook in Jira

Individual account linking

When creating Incident tickets via Runbook step, the Reporter of the Jira ticket will be set to the default authorized user on the account (e.g., whichever account was logged in when setting up the Jira integration).

However, for individual Follow-Up tickets created during incidents, FireHydrant will try to set the Reporter to the person who created the Follow-Up. To correctly do this, users must authorize FireHydrant to create tickets as them in their settings. If users do not link their Jira and FireHydrant accounts, they can still create Follow-Ups, but FireHydrant will fall back to the default authorized user as the Reporter in that instance.

Linking a user's FireHydrant account with their Jira account

Linking a user's FireHydrant account with their Jira account

To connect FireHydrant and Jira accounts, each individual will need to:

  1. Go to their User Settings and click on their organization.

  2. Click Link on the Jira Cloud row.

  3. The next page that opens gives you the option to let FireHydrant access your Atlassian account. After you click Accept, FireHydrant can correctly associate action items and tickets that you have created with your user ID in Jira Cloud.

📘

Note:

Once a user has linked their FireHydrant account to Jira account, creating Follow-Ups linked to Jira projects will set the user as the Reporter. Subsequently, the user will need appropriate permissions for the Jira project in which they're trying to create a ticket.

Configuring Projects

Creating a Jira mapping in Jira Cloud settings

Creating a Jira mapping in Jira Cloud settings

Before using the Jira integration, you'll need to configure a mapping for each Jira project you'd like FireHydrant to interact with so it knows what types of issues, issue states, or relationships to use when creating Jira tickets.

  1. From the Jira integration page in FireHydrant, scroll down to the Projects section and click '+ Add Project.'
  2. A modal will pop up for you to select which Jira project to configure. Once you've chosen one, the project will be created, and you'll be taken to the project settings page with the following tabs.

Incident Tickets

These settings will be necessary to create incident tickets in this Jira project but can be ignored if you only plan to use this project for Follow-Ups.

  1. Incident Default Issue Type - This is the issue type we'll use for incident tickets. Many FireHydrant users may create specific "Incident" issue types in Jira.
  2. Milestone Mappings - These are the Jira ticket statuses we'll use in Jira to correspond to the FireHydrant incident's Milestone.
    1. Any Active incident in FireHydrant corresponds to the Started, Detected, Acknowledged, Investigating, Identified, and Mitigated milestones.
    2. Any Inactive incident in FireHydrant corresponds to the Resolved, Retrospective Started, and Retrospective Completed milestones.

Follow Ups

These settings will be necessary for creating Follow-Ups in this Jira project but can be ignored if you only plan to use this project for incident tickets.

For example, many FireHydrant organizations will have a specific "Incidents" project where FireHydrant creates incident tickets. Then they may configure separate projects for different engineering teams to create Follow-Ups.

These are the available fields:

  • Default follow-up relationship to incident ticket - This is the type of relationship to associate the new follow-up ticket to your incident ticket if one exists. The relationship originates with the new task (outward relationship in Jira parlance).
  • Follow-up default issue type - The type of issue we'll create in your Jira project for Follow-Ups
  • Follow-up status mappings - Maps the FireHydrant Follow-Up status to selected Jira issue statuses. FireHydrant's terminology uses "Open," "In Progress," and "Done" to refer to a ticket's overall state.

Field Mapping

Jira is complex and highly configurable, so sometimes custom mappings need to be made between FireHydrant's incident fields and Jira's ticket fields.

You will need to configure field mappings if you have any custom required fields, otherwise FireHydrant will not be able to create tickets in your project(s).

To learn more about field mapping, visit Jira Field Mapping.

Removing projects

To avoid unexpected problems, before you delete a configured Jira project, ensure that you have accounted for any Runbook steps and linked incidents and action items that reference the project.

Go to the Jira Cloud integration settings to remove a configured Jira project from the integration. Under Projects, click Edit next to the project you wish to remove, then select Delete Project tab and then Delete permanently. Confirm the action.

🚧

Note:

If you delete a Jira project configuration, this will impact any Runbook steps that were pointing toward that project. Even if you re-add the same project in a new configuration, those Runbook steps will need to be removed and re-added, as each "connection" or "project" is unique and does not carry over between deletions/recreations.

Default Ticketing Project

For any operations that require creating a Jira ticket, FireHydrant will use the Project selected (e.g., in the Runbook step, in the dropdown when creating a Follow-Up, etc.).

But if those don't exist or are not specified, FireHydrant can/will fall back to a Default Project you configure. In addition, if you are creating Follow-Ups via emoji in Slack, this Default Project will also be used.

This can be configured in Settings > Ticketing settings > Default project.

Setting a default project in ticketing settings

Setting a default project in ticketing settings

Alert Routing

Like Alerting & Monitoring providers, Jira has "alert routing" capabilities, which allow FireHydrant to take action on inbound webhooks from the Jira instance automatically.

This allows, for example, the creation of Jira tickets in certain projects or matching specific parameters to start incidents in FireHydrant or notify certain Slack channels automatically.

To learn more about how it works, visit our Alert Routing documentation. Below is an example showing a typical use case where any ticket created in an "Incidents" project automatically starts an incident on FireHydrant.

ACIR = Acme Company Incident Response

ACIR = Acme Company Incident Response

Parameter Mappings

The table below shows the available parameters you can filter on and how to access them via Liquid templating.

Parameter NameJira Webhook BodyNotes
Jira: Status Categoryrequest.body.issue.fields.status.statusCategory.keyThe key of the status category for the issue's status
Jira: Statusrequest.body.issue.fields.status.nameThe Jira status of the created issue.
Jira: Project Type Keyrequest.body.issue.fields.project.projectTypeKeyProject type key of the project the issue was created in. For example, software.
Jira: Project Keyrequest.body.issue.fields.project.keyKey of project issue was created in
Jira: Project Namerequest.body.issue.fields.project.nameName of project issue was created in
Jira: Priorityrequest.body.issue.fields.priority.namePriority of created issue
Jira: Descriptionrequest.body.issue.fields.descriptionURL to alert page in PagerDuty
Jira: Created Atrequest.body.issue.fields.createdWhen the ticket was created in ISO 8601 formatted datetime. For example:
2024-01-23T14:25:05.774-0700
Jira: Summaryrequest.body.issue.fields.summaryThe Summary field within Jira (usually the title)
Jira: API URLrequest.body.issue.selfThe URL for this specific Jira ticket included as the self parameter. Usually comes in the format of: https://[your-workspace].atlassian.net/ rest/api/2/[issue_id]
Jira: IDrequest.body.issue.idThe Jira issue ID. Number is generated and assigned by Jira on issue creation.

The following table maps our overall Alert Routing mapping object - these parameters are standard across all Alerting/Monitoring integrations and are derived from above parameters.

Parameter NameJira Webhook BodyNotes
Alert Summaryalert.summaryThe same as Jira: Summary above.
Alert Descriptionalert.descriptionThe same as Jira: Description above.
Alert PriorityN/AMaps to nothing for Jira.
Alert Statusalert.statusIf the ticket is done in Jira, then this parameter is resolved. Otherwise, it is opened.
Alert Associated InfrastructureN/AMaps to nothing for Jira. There is no way to associate Jira projects with specific Catalog components currently.

Next Steps