Overview

This KB article describes how to change the project key for bulk projects. Previously we were going to make certain project key configurations unsupported, however as in the announcement above this behaviour is planned to change. This documentation will remain here in case anyone needs to modify their project keys.

The below information relates to the options described further down in this article.

• For an example of how external links operate in JIRA, accessing https://jira.atlassian.com/browse/JRA-31392 will redirect it to a separate project as the issue was moved.
• For internal links, check the link created to another JIRA issue (GHS-1234) automatically in the comments at https://jira.atlassian.com/browse/GHS-7262.

Note that this not apply to project key charter limits, which were restricted to 10 characters in JIRA 5.x but will be configurable from JIRA 6.x onwards. See  JRA-28577 - Getting issue details... STATUS  for details. 

Before Proceeding

1. Proceeding to make the project key change can break the following integrations:
   1. Fisheye - Commits from the version control systems connected to Fisheye using the old project key
   2. Crucible - Reviews linked using the old project keys
   3. Bamboo - Linked JIRA Issues, Projects, Versions corresponding to builds
   4. Confluence - JIRA Issue references if Option 1 is followed.
   5. SVN Commits - Commits messages matching JIRA issue keys retrieved by JIRA SVN Plugin
   6. Bitbucket/GitHub Commits - Commits messages matching JIRA issue keys retrieved by JIRA DVCS Connector for Bitbucket and GitHub
2. Fully review the limitations and advantages of the options before proceeding.
3. Please make a backup of the JIRA data (as in Backing Up of JIRA Data) before performing any change as per these instructions.
4. Perform these steps on a test instance which has a copy of the production instance data. Confirm the results and then proceed to do it on the actual production instance.

Option 1 - Backup and Restore

Please note the below limitations and advantages of using this method:

Steps

1. Create an XML Backup of your data.
2. Unzip the created zip file (under JIRA Home/export) and this will yield the below two files:
   1. activeobjects.xml
   2. entities.xml
3. These two files contain all the data including administrative data for the JIRA instance.

4. Perform a search and replace of all project key patterns in both files. An example of doing this using perl is given below:

   perl -p -i -e 's/OLD-KEY-PROJECT-KEY-/NEWPROJECTKEY-/g' entities.xml
   perl -p -i -e 's/OLD-KEY-PROJECT-KEY-/NEWPROJECTKEY-/g' activeobjects.xml 

   For example, if OLD-KEY-PROJECT-KEY is CS and NEWPROJECTKEY is NEWCS, you may try the commands below to replace the project key string in the XML files:

   perl -p -i -e 's/CS/NEWCS/g' entities.xml
   perl -p -i -e 's/CS/NEWCS/g' activeobjects.xml 

5. Repeat step 4 for each of the project keys that require changing.
6. Create a new zip file using the modified XML files and place it under JIRA Home/import.
7. Restore the Data into the same JIRA instance.

Option 2 - Bulk Move of Issues

Please note the below limitations and advantages of using this method:

Steps

1. Modify the atlassian-jira/WEB-INF/classes/jira-application.properties file and remove the line containing the key jira.projectkey.pattern.
2. Disable outgoing/incoming emails from the instance as described in this article.
3. Restart JIRA.
4. Create a new project for each of the existing projects in JIRA. Please remember to use the same settings for the project configuration:
   1. Issue Type Scheme - Associating Issue Types with Projects.
   2. Issue Type Screen Scheme - Associating a Screen with an Issue Operation.
   3. Workflow Scheme - Configuring workflow schemes.
   4. Field Configuration Scheme - Associating Field Behavior with Issue Types.
   5. Notification Scheme - Creating a Notification Scheme.
   6. Issue Security Scheme - Configuring Issue-level Security.
   Please remember that the project keys for the new projects must be as per the default supported pattern ([A-Z][A-Z]+). 
5. Using the Issue Navigator search for issues belonging to one project.
6. Perform a bulk move of the issues to the newly created project (select the project name/issue type in the second screen of Move Issue operation).
7. Repeat steps 5-6 for all the projects.
8. Delete the original projects.
9. Re-Index JIRA.