We’re planning to introduce custom Agile terminology in Jira. This will allow Jira admins to change Sprints and Epics to any other terms they choose, and get the updated terms displayed both in Jira and Marketplace apps. This feature aims to meet the growing need for custom Agile terms, usually needed by organizations introducing Agile at Scale frameworks, like SAFe, where sprints are called iterations and epics—features.
In this EAP, you can test the APIs to manage terminology, as well as the mechanism used to update the terms in your app.
Feature overview
Here’s a summary of what’s available in this EAP:
- Adjusting your app’s code to new terminology (available)
You can mark supported terms in your code with % tokens, and have Jira automatically replace them with new terms when needed.
- Managing terminology through Java and REST APIs (available)
You can view current terminology, change it, or be notified about the changes.
- Changes are visible around Jira (partially available)
Right now, you’ll see both old and new terms, depending on where they come from. Eventually, the terms will also be replaced in custom field names and issue types, and everywhere else in Jira.
- Managing terminology through Jira UI (not available)
Admins will be able to change terminology directly in Jira, but this is planned for future milestones. We plan to have a page in the Jira administration where admins see the original terms and can provide their new singular and plural forms.
Limitations
- Terminology changes will apply only to the default English language.
Note
We are still working on this feature and not everything works as it should. To see terminology changes you made, you need to clear browser’s cache. If you want to test gadgets you must also restart Jira.
Adjusting your app’s code to work with terminology changes
To adjust your app’s code to work with this feature, you will need to update occurrences of Agile terms in i18n resource files. Those are resources with type set to i18n in atlassian-plugin.xml:
<resource type="i18n" name="mypluginprops" location="com.example.mypluginname"/>
Marking terms with % tokens
To get your terms replaced with the new ones, updated by Jira admins, you need to surround them in your code with % tokens, for example sprint → %sprint%. The strings will be replaced by Jira at the time of loading your app.
- We’ll keep the capitalization of original terms wherever possible
- We’ll handle articles, changing them where appropriate (see below)
Supported terms and their tokenized version
- sprint → %sprint%
- sprints → %sprints%
- epic → %epic%
- epics→ %epics%
Handling articles
We will change the articles so they work with the new term. For example, if you used Epic before and switched to Feature, we will update the articles like in the following example:
Original:
Field that will help you regroup issues under an %Epic% or under a theme.
Updated:
Field that will help you regroup issues under a Feature or under a theme.
Other implementations
With the access to Java and REST APIs, you can also implement your own mechanism to replace the Agile terms. We’re especially interested in hearing why our mechanism is not the best solution for your app.
Managing terminology through Java and REST APIs
You can use APIs to view current terminology, change it, or be notified about the changes. The Java extension points described below are in the com.atlassian.Jira.i18n.terminology package.
For list of new classes and methods, see Managing terminology through Java and REST APIs
Feedback we’re looking for
We’re especially interested in these questions:
- What do you think about our mechanism for replacing strings in your code?
- How does this change impact your app?
If you have any other comments, questions, or concerns, just comment on this post. We’ll get our best people to answer.
Downloading this EAP
For the complete list of changes and download links, see Preparing for Jira 8.15.