Integrating with Jira Cloud
FireHydrant can create tickets in Jira for each of your incidents, with linked tickets for actions to be performed during the incident, and follow ups for later. This way all of the actions proposed during an incident are tracked in your existing project management workflows for estimation and scheduling.
Note: To configure FireHydrant’s Jira Cloud integration requires a Jira Cloud administrator and a user with a FireHydrant owner role. FireHydrant recommends creating the Jira Cloud integration using a generic service account Jira user to prevent potential problems arising from a Jira admin’s departure and subsequent account decommissioning.
Setting up Jira Cloud integration
Setting up integration requires authorizing our OAuth2 application in Jira Cloud. (FireHydrant is an OAuth2 application, available in the Atlassian Marketplace.) You can choose the type of tickets you want to create and then configure your target project(s).
To get started:
- A FireHydrant organization admin must add our Jira Cloud integration.
- A Jira Cloud administrator must authorize the Fire Hydrant integration in Jira Cloud. 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. The Jira Cloud service account used to authorize the integration must have the minimum functional permissions. Ability to:
- Read all Jira projects to be used with FireHydrant.
- Read all Jira ticket types to be used with FireHydrant.
- Read all Jira fields and custom fields to be mapped in FireHydrant.
- Read, create, and edit issues in the projects to be used with FireHydrant.
Configuring webhooks
To see updates to your tickets reflected in FireHydrant, add a Webhook to Jira. In FireHydrant access the Jira Cloud integration settings, and copy the Webhook URL.
In Jira Cloud, have your Jira administrator configure a Webhook listener for FireHydrant using the copied URL.
Project configuration
Note: If you are using OAuth for individual Jira user authentication from FireHydrant, in order for FireHydrant users to be able to create tickets in Jira projects configured in FireHydrant, they will need to have corresponding permissions in Jira to access the projects.
Next you’ll want to configure how FireHydrant should interact with your Jira Cloud projects. From the FireHydrant’s Jira integration configuration, navigate to the Projects section. From here you can define the default behavior on a per project basis, for example the default issue type for FireHydrant incidents, actions items, and relationships between linked issues.
Removing a configured project
Note: 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.
To remove a configured Jira project from the integration, go to the Jira Cloud integration settings. Under Projects click Edit next to the project you wish to remove, then select Delete Permanently. Confirm the action.
Configuring Jira custom field mappings
If you have Jira custom fields that you wish to populate with FireHydrant incident data, please refer to the custom field configuration document.
Setting a default project
Next configure a default project for your organization. This will act as a fallback in the event that a FireHydrant Jira ticket creation request request cannot communicate with the specified Jira project. To set a default project go to Organization > Account Overview. From the Account Overview page, choose to Edit the Organization section. On the Default project for tickets entry select a default project, then click Save organization.
If in the future you disconnect this integration, you will need to reconfigure the default project if you decide to reenable it.
Creating Jira Cloud issues from a Runbook
Note: The default behavior is to allow only a single top-level incident ticket per FireHydrant incident. There is no limitation on linked action items tickets. If your organization requires multiple top-level incident tickets per incident, please create a support ticket to request that this functionality be enabled for your organization.
In order to trigger a Jira Cloud issue creation from a new incident, you'll need to add a Runbook step and specify the Jira project destination.
From the Runbook step menu navigate to Jira Cloud and select Create a Jira Cloud Issue. Select the Jira project destination from the configured project list, and optionally adjust the default populated fields.
Now you're ready to create action items in FireHydrant and sync them to Jira.
Troubleshooting integration issues
You can check the health status of a Jira Cloud integration from the Jira Cloud integration configuration tab. Choose to edit the integration, then review the Connection Health section on the configuration details.
he configuration details.