Migrating to Jira Per-Project Configuration Using the API

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. This guide gives a high-level overview of how to do this.

Note: This will only work for "organization based" projects. "Team based" projects cannot share configuration like this. This is a constraint of Jira. 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.

Prerequisites

This guide uses the following tools:

• curl for making http requests
• jq for manipulating json

Additionally this guide assumes you have a valid bot token 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.