Changing the project key format

Before you begin

• Ensure that you choose a supported project key format. Only formats that meet all of the following rules are supported:
  
  • The first character must be a letter,
  • All letters used in the project key must be from the Modern Roman Alphabet and upper case, and
  • Only letters, numbers or the underscore character can be used.
    Examples:
    • Examples of supported keys: PRODUCT_2013, R2D2, MY_EXAMPLE_PROJECT.  
    • Examples of unsupported keys: 2013PROJECT (first character is not a letter), PRODUCT-2012 (hyphens are not supported).
• You cannot configure the issue key pattern, as Jira expects this key to conform to specific rules. By default, Jira issue keys (or issue IDs) are of the format <project key>-<issue number>, e.g. ABC-123. For example, you can't show the issue number before the project key.
• If a number of issues have already been created in your Jira installation, then changing the project key format is not recommended. If you must change the project key pattern after issues have already been created, use a regular expression that allows a more 'permissive' project key pattern than the current one (e.g. use a regular expression which will still be valid for existing project keys defined in your Jira installation).

Configuring the project key format

The jira.projectkey.pattern property allows Jira administrators to specify a Perl5 regular expression value that defines the rule for a valid project key. Further information on Perl5 is available here.

This property and its regular expression value can be defined through the Advanced Settings page. This is described below.

Step 1. Configure a pattern for your project key syntax

1. Navigate to the Jira Advanced settings page, as described on Configuring advanced settings.
2. Find the jira.projectkey.pattern property and click its value to modify it. Below is a list of common examples and patterns:

Please note:

• Jira prepends the regular expression specified with '^' and closes it with '$' for an exact matching rule within the system.
• The project key only supports uppercase characters, as stated above. Hence, for simplicity, use uppercase characters in your expressions as Jira will convert any lowercase characters to uppercase ones.

Step 2. Test your regular expression

A variety of tools allow searching using a Regular Expression. Most text editors will allow a Regular Expression search. There are also a variety of websites available to for testing a Regular Expression available from an Internet search.

(Optional) Step 3. Customize the project key description and warning

In addition to the project key format, you can also customize the following properties in the jira-config.properties file:

• jira.projectkey.description — a configurable description (to match the project key pattern) displayed on project creation
• jira.projectkey.warning — if Jira detects that the project key entered does not match the jira.projectkey.pattern, it will throw the error message defined in jira.projectkey.warning. You can change this error message, so that when a user keys in the wrong format, they will be informed of the correct pattern to use.

Related topics

• Changing the maximum project key length — You can change the maximum characters allowed for a project key. Navigate to the General Configuration page of the Jira administration console, as described on Configuring Jira application options, and change the Maximum project key size field.
• Defining a project
• Editing a project key
• Configuring advanced settings