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).
- Examples of supported keys:
- 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
- Navigate to the Jira Advanced settings page, as described on Configuring advanced settings.
- Find the
jira.projectkey.patternproperty 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 | ( | TQ09-01, TQ09-02, etc. |
|
XZ+, where X indicates one fixed letter, Z+ represents one or more letters, digits or underscore characters | ( | ACAT_51-1, AAA5-1330, A_20_A091-15, etc. |
|
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 creationjira.projectkey.warning— if Jira detects that the project key entered does not match thejira.projectkey.pattern, it will throw the error message defined injira.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