How To Handle Project Key Pattern Change

Still need help?

The Atlassian Community is here for you.

Ask the community

This information applies to JIRA versions older than 6.1. For JIRA versions 6.1 and newer see Editing a Project Key. See JRA-2703 - Getting issue details... STATUS   for additional information regarding project key changes in JIRA 6.0 and older.


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.

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:

External Links: All links to the old issue ids from external systems (using the complete JIRA url) will not redirect.

tip/resting Created with Sketch.

Internal Links: The automatic linking in the text within JIRA (descriptions, comments etc.) will work, as the comment is changed in the XML backup.

XML files can be considerably large and opening the files in text editors can be extremely slow. Searching and replacing using perl is recommended due to its capability to handle large files.

The search and replace procedure can replace any string in the complete JIRA data which matches the project key pattern. This may lead to undesirable results.


  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 the files. An example for 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 
  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:

tip/resting Created with Sketch.

External Links: All links to the old issue ids from external systems (using the complete JIRA url) will redirect.

Internal Links: The automatic linking in the text within JIRA (descriptions, comments etc.) will not work, as the comment is not changed in the bulk move.

Issue Numbers: The bulk move will not retain the issue numbers and random numbers will get assigned to the new issue ids. For example if you are moving an issue SOURCE-1234 to another project DEST, it is not guaranteed that the new issue id will be DEST-1234.

The search can return a maximum of 1000 results by default. If the number of issues are more than 1000 please increase the limit as described here or restrict the search to do it in batches of 1000 by adding additional filter criteria. Increasing this number over 1000 can cause significant performance problems on larger instances if they are being actively used due to the number of search results returned by each query.


  1. Modify the atlassian-jira/WEB-INF/classes/ 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.

Last modified on Nov 6, 2018

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.