Road to custom Agile terminology, part 1

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.

4 Likes

Quick comments:

  • I think it’s a mistake to not address languages explicitly in this API. If Jira is configured to use a non-English language, what does this API return? Also, the API allows changing terminology; what happens if you do so when Jira is configured to a non-English language?
  • This API feels like it embodies a special-case of a larger problem. For example, what happens when you (Atlassian) need to introduce other kinds of user-configurable terminology and the original names overlap? Is there a need for a namespacing/context property too?
  • Will the string macro approach work properly in all scenarios? What happens, for example, if the configurable term sits at the beginning of a sentence? ("%sprint% list" will become “sprint list” rather than “Sprint list”.) I realise that apps can combine strings in code, but it quickly becomes cumbersome if the terminology appears in many i18n strings.
2 Likes

Hi @TomaszPrus, this is a very interesting feature from Atlassian. We have had a few requests for this functionality for our apps over the years, however not enough that would warrant immediate implementation.

A few questions / concerns:

  1. We don’t use the i18n transformer for performance reasons. Our javascript is built with webpack and the output is far too large for the internationalisation transformer to parse. This is a serious consideration for larger DC customers. Would you consider an API to provide us with the terminology for us to apply on our own?

  2. There is currently no public API which is the canonical place to get (specifically Jira Software) custom issue types. This has been a major pain point for Easy Agile over the years. Is there any possibility you could provide an API which lists the details of the Jira Software custom issue types, their IDs and any custom naming for them all in one place?

Thanks

Dave

4 Likes

Hi @edave

Unless I’m missing something, for your #2, there’s both a Java API and a REST API for getting custom and/or built-in issue types and their info.

There’s a REST API call that “Returns a list of all issue types visible to the user”:
GET /rest/api/2/issuetype

If you mean the Java API, then you can use getIssueTypes()

Or did you mean some other kind of API?

For your #1, they list the API reference in this article for you to be able to Get and Post terminology:

For list of new classes and methods, see Managing terminology through Java and REST APIs

Granted, a lot of it is still Experimental.

I hope this helps.

Hi @gustav.taxen, thanks for your input! Regarding specific points:

  1. Any terminology settings apply, and will continue to apply in the foreseeable future, to English only. The API will likely be extended if we decide to support other languages at a future date.
  2. As above, this can be addressed when needed by extending the API and treating the existing methods as a special case (e.g. with locale defaulting to English and namespaces defaulting to “agile.terminology”).
  3. We do take existing capitalization into account. The same goes for modifying indefinite articles (“a” vs “an”), though this is English-specific and likely won’t be possible for most other langueges, if we extend Terminology support to them.

Karol

Hi @edeve,

  1. There’s both a REST and Java API to read current nomenclature settings, as detailed in the “Managing terminology through Java and REST APIs” paragraph. Feel free to ask if you have any specific questions.
  2. ManagedCustomFieldsService allows you to get information about Software-specific custom fields. Adding information on custom naming is definitely something we might consider in the future.

I hope this addresses your concerns.

Karol

Thanks for your answers!

I suspect it won’t be long before you have a situation where you want to (or even need to) update this API…

Given that Atlassian has a policy of not using versioning when making breaking changes to syntax and/or semantics in their REST APIs, this means that:

  • Jira will now blend English and non-English terminology in the most important parts of its UI. (It always did in the past, but this makes the problem worse.)
  • When you discover that this is a problem (which is likely to happen soon, I think) you will immediately break all apps that use this API when you try to fix it.

Wouldn’t it be better to try to deal with terminology and internationalisation properly from the outset?

Or, preferably, if you do want flexibility in making changes to your REST APIs as you go, introduce proper versioning and deprecation mechanisms into your deployment processes?

1 Like