Configuring terminology
To help you follow Agile best practices, Jira Data Center provides Flexible Terminology feature since version 8.17. It enables admins to change generic Jira Data Center terms: sprint and epic. This helps you keep consistent naming of sprints and epics between Jira and the Agile at Scale Frameworks, including SAFe (Scaled Agile Framework) and LeSS (Large-Scale Scrum Framework).
Terminology changes apply to any variant of English. Regardless of the framework you follow, or the terminology you choose, you can quickly implement changes across your instance.
The new terms will replace the original ones in the outputs:
- Issue type names
- Issue screens
- Reports
- Epic-related field names (Epic Name, Epic Color, Epic Status, Epic Link)
- Basic and advanced search results
- API outputs
Jira will keep the capitalization of original terms whenever it's possible. The new terms won’t be applied to the inputs for:
- advanced search results (JQL queries), where you should use the original terms “sprint” and “epic”, as well as the original names of the epic-related fields
- API queries (JQL).
You can learn more about the limitations to the application of the new terms in the following sections.
Defining terms
Bef
Terminology change broadly affects your instance. That’s why, before you begin, we recommend:
- backing up your database and important directories prior to submitting terminology changes
- making these changes during planned downtime or low-user hours, so that users don't get confused by the new names
To view and manage your terms:
- In the upper-right corner of the screen, select Administration
> System.
- Under the User Interface (left-side panel), select Terminology.
- Select Change terminology.
- Define new singular and plural forms of your terms.
- Select Change names.
- Review the new terms and select Change to confirm them.
You can define singular and plural forms of your new terms according to the following rules:
You can’t swap names of epics and sprints.
The new terms must be no longer than 40 characters and can contain only letters, numbers, and spaces.
- Terms must be unique. For example, epics and sprints can’t both be called “Potatoes”.
All fields must have a value with at least one character.
Changing names may override translated terms in UK and US English.
Adjusting terms across Atlassian products
Admins have control over Jira terms and can define them globally without third-party apps. But, there are some things you need to consider for other products.
Advanced Roadmaps
Whenever you change the term "sprint" in Jira, it will also be changed in Advanced Roadmaps. However, the term "epic" won't refresh automatically. You need to update the level name separately. To do this, go to Plans > Administration > Hierarchy levels.
Jira Align
Your Jira connector doesn’t sync platform terminology, so you need to update terms in Jira Align separately. To set the new terms for the terms “sprint” and “epic” in Jira Align, go to Admin > Platform Technology.
Limitations
Language
Terminology changes apply only to English language variants. For other languages, Jira displays original names.
Translation of the epic issue type and epic-related fields
Flexible Terminology uses the translation of the epic issue type and epic-related fields to localize their names. As a result, all APIs will return the localized names when querying the API or saving the issue (for example, the new term). But to build the query, you should use the original terms, not the localized ones.
The new change items will be kept with translated fields’ names. So, the query about the field’s history considers all current and historical names of the field.
Your app or script may have a hardcoded reference to the issue type “epic” or to epic-related fields with the following names:
Epic Name
Epic Color
Epic Status
Epic Link
- Sprint
In such cases, these fields should be adapted to use IDs (they’re recommended) or new names.
You can do that by replacing “sprint” or “epic” with new terms, as returned by rest/api/2/terminology/entries.
If your app or script is already using custom translations for the epic issue type or epic-related fields, don’t make any changes.
Advanced search uses the original names of “sprint,” “epic,” and the epic-related fields
The Terminology feature enables the changes to the term “sprint” and to the term “epic” as the name of the issue type. Also, the new term for “epic” is applied to the names of the epic-related fields: Epic Name, Epic Color, Epic Status, and Epic Link.
As a result, you’ll see the new terms everywhere in the output: on boards, in issue screens, reports, and basic search filters.
But the input in API queries or advanced search will still require the original terms for “sprint”, “epic”, and the epic-related fields.
Here’s the example of an advanced search query: resolution = Unresolved and issuetype = Epic.
Here’s another example where advanced search requires the original terms. For illustration, the term “epic” is changed to “feature.”
Basic search works with “feature” | Advanced search requires “epic” |
|---|---|
|
|
As a result, the field Epic Link is now called Feature Link. But if you want to use this field in advanced search, you should use the original name of the field.
In the screenshot below, pay attention to the original names of the epic issue type and its related field in the search compared to the custom names of the columns.
In the search, we have Epic and Epic Link. This is the input.
But in the columns on the board (in the output), we have Feature Link and Feature Name—the epic-related fields whose names are changed according to the new term for “epic,” which is “feature” in this example.
The terms remain original in the database
Even if you set the new terms for “sprint” and “epic”, they won’t be recorded in your database. The database will still contain the original terms: “sprint” and “epic”, as well as the original names of epic-related fields.
Example 1
Here is an example query showing that the database keeps the original names of epic-related fields, while the term “epic” is changed to “feature”. (Custom field name is Jira’s internal term for the names of these fields.)
Example 3
Here's another example query showing that sometimes the database may keep both the original and customized terms for sprint, epic, and epic-related fields. This may happen when issues are updated soon after the original terms are changed.
In the screenshot, you can see that the issue TERM-9 first had the Epic Link field. But the term “epic” was changed to “feature”. So, when the issue was updated on the same day, the name of the Epic Link field changed to Feature Link. As a result, the database keeps both the original and customized names of the field.
