How to change Jira Key for synced projects in Jira Align

There are times when an organization may need to change a Jira project key after it has already been integrated with Jira Align. The steps outlined below are the ones needed to change the key instead of creating new integrations.

Let’s first look at the existing Jira Project and Jira Align settings for the integrated project.

Existing Jira Project and settings for Jira Align displaying project key

Jira Project with current key of PLTCP

Existing Jira Align settings with project key listed as PLTCP

‍

Here are the current integrated Jira work items that have synced to Jira Align. This view is within Jira Align.

‍

Below is a Jira listing of work items that are synced to Jira Align. This view is within a Jira query.

Here are some step-by-step instructions to help you.

1. The change in Jira project key begins in Jira.  

In the example screenshot below, I’ve changed the key from PLTCP to PLTCP123. The change can be used for any new key that your organization needs.

• Navigate to the Jira Project settings for the project to be updated.
• Click on the Details link to display the key information for the project.
• Type in the new key and click on the “Save Details” button at the bottom of the screen.

NOTE:  You will be presented with a dialog box stating that changing the project key will start a background re-index of the project.

2. Switch to Jira Align to rename the existing key for the Jira project renamed in step 1.

• Navigate to Administration – Jira Settings – Manage Projects tab.
• Click on the project key changed in Jira within the list of Jira projects; this will display the details of the project.
• Type in the new project key and click on “Save and Close” to update the settings.
• Changed key in Jira Align for other projects.

3. Run a new JQL Jira integration query to update keys from Jira.

In the example below, I’ve selected the Jira Project and updating and setting the query using a created parameter.

4. After the query has run, you can verify within Jira Align that the external ID’s from Jira had been successfully changed to the new project key you entered.

Final notes

All existing boards that are integrated will remain the same even after the Jira project key is changed.  There is no reference to the project key when integrating the Jira boards.

The same is true if Fixed Versions/Release Vehicles are synced between Jira and Jira Align.  There is no reference to the Jira project key when syncing this information.

In the example below, I created a scrum board in Jira and linked to Jira Align for the team.

Here you can see we created a sprint in Jira and synced to Jira Align sync sprint:

And finally, in this example we created a release vehicle and synced to Jira from Jira Align and from Jira Align down to Jira in Jira.

For more tips on how Jira Align can help your organisation, contact us for a demo.