Changing the project key format

Editing a project key

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

Jira provides the ability to specify the format of project keys within the system. This allows you to restrict the format of a project key, when a project key is created or edited.

A project key format is defined via a regular expression 'rule' that governs the valid project key format. By default, the Jira project key configuration requires two or more uppercase alphabetical characters — based on the regular expression ([A-Z][A-Z]+).

On this page:

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_2013R2D2MY_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).

If you have integrated Jira with Bamboo, do not change Jira's default project key format as Bamboo only supports this key format.

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:

Pattern Requested

Expression needed

Resulting Issue IDs

Comments

XXYY, where X indicates two fixed letters, Y represents two fixed digits

([A-Z]{2}[0-9]{2})

TQ09-01, TQ09-02, etc.

[A-Z] Any character from A to Z
{2} Matches the preceding character 2 times exactly
[0-9] Any character (i.e.digit) from 0 to 9

XZ+, where X indicates one fixed letter, Z+ represents one or more letters, digits or underscore characters

([A-Z][A-Z_0-9]+)

ACAT_51-1, AAA5-1330, A_20_A091-15, etc.

[A-Z] Any characters from A to Z
[A-Z_0-9] Any character from A to Z, 0 to 9 or the underscore character.
+ specifies [A-Z_0-9] as one or more characters from A to Z, 0 to 9 or the underscore character.

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

Last modified on Dec 9, 2021

Was this helpful?

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