Configuring Jira Multi-Project

If you have not yet set up a Jira integration with FireHydrant, refer to the following documents first:

• Integrating with Jira Cloud
• Integrating with Jira Server (On-Premise)

If you are an organization using the Legacy Jira integration setup, refer to the migration docs below.

Configuring Jira Projects

Note: If you'd like to use our integration with a Jira project that has required custom fields, there are additional steps outlined in this document.

Before using the Jira integrations, you'll need to configure mappings for all of your Jira projects so FireHydrant knows what types of issues, issue states or relationships to use when creating tickets in Jira.

From the FireHydrant’s Jira integration page, scroll down to the Projects section and click '+ Add Project'.

On the next screen, select which Jira project to configure mappings for. Once you do, several other dropdown fields will appear.

Incident Tickets

• Default Issue Type for Incidents: This is the type of issue we'll create in your Jira project for incidents
• Issue Status For Active Incidents: Which status in Jira maps to an open incident in FireHydrant
• Issue Status For Inactive Incidents: Which status in Jira maps to a resolved incident in FireHydrant

Other Tickets

• Default Issue Type for Tasks: This is the type of issue we'll create in your Jira project for tickets that are tasks.
• Default Issue Type for Follow Ups: This is the type of issue we'll create in your Jira project for tickets that are follow ups
• Issue Status For In Progress Tickets: The status in Jira that maps to the In Progress status for tickets in FireHydrant
• Issue Status For Done Tickets: The status in Jira that maps to the Done status for tickets in FireHydrant
• Issue Status For Open Tickets: The status in Jira that maps to the Open status for tickets in FireHydrant
• Default Task & Follow Up Relationship to Incident Ticket: This is the type of relationship to relate the new ticket to your incident ticket. The relationship originates with the new task (outward relationship in Jira parlance).

Note: A lot of the above is for a legacy feature allowing for Tasks to have corresponding Jira tickets. We will fully remove this capability at some point as we establish a clear distinction between mid-incident Tasks, which live in FireHydrant, and post-incident Follow-Ups, which can have linked Jira tickets. Once we do this, the settings/names and documentation will adjust accordingly.

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.

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.

Default Ticketing Project

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

But if for some reason those don't exist or are not specified, FireHydrant can/will fallback to a Default Project you configure.

If you would like this behavior as a failsafe, you can configure this in Incident response > Ticketing settings.

Migrating to Jira Multi-Project

In February 2022, FireHydrant added multi project support for its Jira Cloud and Jira Server integrations. Previously, all incidents and action item related Jira tickets were routed to a single Jira project.

To take full advantage of the Jira multi project feature's flexibility, users will need to modify their existing configuration in the following ways:

• Configure additional projects in the Jira Cloud or Jira Server integration settings
• Modify existing runbooks or create new runbooks to use the new ticketing platform-specific incident ticket creation steps

Migration steps

In order to migrate from "global" ticketing project configuration to per-project configuration, you must create a configuration for each ticketing project you wish to use.

• You can do this manually - in this case, just follow the guide above.
• Alternatively, you can automate this through scripting and our API. See the rest of this guide for information on that.

Prerequisites

This guide uses the following tools:

• curl for making http requests
• jq for manipulating json

Additionally this guide assumes you have a valid API key for FireHydrant set in the FH_BOT_TOKEN environment variable.

Migration overview

We can break this down into three parts:

1. Determine the appropriate configuration parameters from the legacy global config.
2. Create configurations for each project you wish to use:
3. Get the IDs of the projects you wish to use.
4. Create a configuration for each project use configuration parameters from the first step.
5. Validate projects as necessary.

Pagination limits

Note: Jira has a default pagination limit. If you have a large number of projects you may need to add per_page and page parameters to the url to return all of your projects.

Here is an example url with pagination parameters:

https://api.firehydrant.io/v1/ticketing/projects?providers=jira_onprem&per_page=100&page=1

Getting global config

You can get the current global config via:

curl -v -H "Authorization: Bearer $FH_BOT_TOKEN" 'https://api.firehydrant.io/v1/integrations/connections?connection_type=Integrations::JiraOnprem::Connection' | jq '.data[0].details' | jq 'del(.webhook_url, .api_base_url, .api_username)'

This will output something like:

{
  "jira_issue_type_id": "10006",
  "jira_issue_link_type_id": "",
  "in_progress_issue_status_id": "3",
  "open_issue_status_id": "10000",
  "done_issue_status_id": "10002",
  "jira_task_issue_type_id": "10004",
  "jira_follow_up_issue_type_id": "10004"
}

Note that if you don't have values for some of these fields (as in jira_issue_link_type_id above), you must determine valid values for each missing item as the next step will require them. Ask your jira admin if needed.

It can be helpful to store this configuration information in a file:

curl -v -H "Authorization: Bearer $FH_BOT_TOKEN" 'https://api.firehydrant.io/v1/integrations/connections?connection_type=Integrations::JiraOnprem::Connection' | jq '.data[0].details' | jq 'del(.webhook_url, .api_base_url, .api_username)' > global_config.json

You should also get the connection id for your jira connection:

curl -v -H "Authorization: Bearer $FH_BOT_TOKEN" 'https://api.firehydrant.io/v1/integrations/connections?connection_type=Integrations::JiraOnprem::Connection' | jq '.data[0].id'

This will yield something like:

"0ea94efb-f8da-4be3-bf2b-df72354e6e16"

Get projects without config

Get all the projects without a config:

curl -v -H "Authorization: Bearer $FH_BOT_TOKEN" 'https://api.firehydrant.io/v1/ticketing/projects?providers=jira_onprem' | jq '.data | .[] | select(.config == null)'

This will yield objects for each project that doesn't already have a configuration, eg

{
  "id": "a440bd74-95a4-443a-9866-f1f476654872",
  "name": "Basic - Jira Server (on premise)",
  "config": null
}
{
	...
}
...

Create new configurations

For each of the projects needing configuration from above, create a new project configuration using the global config:

curl -v -H "Authorization: Bearer $FH_BOT_TOKEN" -H "Content-Type: application/json" -X POST 'https://api.firehydrant.io/v1/ticketing/projects/a440bd74-95a4-443a-9866-f1f476654872/provider_project_configurations' -d @./global_config.json

Note the use of the project id and the config json file saved from above.

Validation

Once you've configured your projects, you can use them in Runbook steps to validate they work as expected. The status/health checks for your integration will also start to monitor the configured projects to help determine if they are usable by FireHydrant.

Next steps

Now that you've configured your project(s), you can look at several of the capabilities that FireHydrant provides:

• You can create a Jira incident ticket automatically for each incident created on FireHydrant.
• Create follow-ups in Jira directly from FireHydrant, both from the UI and from Slack.

For troubleshooting, visit our Troubleshooting Jira Issues article.