Flexible Terminology

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.

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.

REST API docs

Resources

api/2/terminology/entries

Enables customizing the default words "epic" and "sprint".

Methods

Get all terminology entries EXPERIMENTAL GET /rest/api/2/terminology/entries

Returns the list of all defined names for the default words "epic" and "sprint".

STATUS application/json

Set terminology entry EXPERIMENTAL POST /rest/api/2/terminology/entries

Changes an epic/sprint name from {"originalName"} to {"newName"}. The {"newName"} will be displayed in Jira instead of {"originalName"}.

{"originalName"} must be equal to the values returned by the "GET /terminology/entries/originalNames" REST point.

{"newName"} can only consist of alphanumeric characters and spaces e.g. {"newName": "iteration number 2"}.

{"newName"} must be between 1 to 100 characters. It can't use the already defined {"newName"} values or restricted JQL words .

To reset {"newName"} to the default value, enter the {"originalName"} value as the value for {"newName"}. For example, if you want to return to {"originalName": "sprint"}, enter {"newName": "sprint"}.

Request

Example

{
  "originalName": "sprint",
  "newName": "iteration",
  "newNamePlural": "iterations"
}

Schema

{
  "id": "https://docs.atlassian.com/jira/REST/schema/terminology#",
  "title": "Terminology",
  "type": "object",
  "properties": {
    "originalName": { "type": "string" },
    "newName": { "type": "string" },
    "newNamePlural": { "type": "string" } },
  "additionalProperties": false
}

Responses

STATUS 400 Returned if the provided data isn't valid.

STATUS 403 Returned if the user doesn't have admin permissions.

STATUS 404 Returned if the feature is turned off via a feature flag.

Get terminology entry EXPERIMENTAL GET /rest/api/2/terminology/entries/{originalName}

Returns epic or sprint name as specified in the {originalName} path param.

STATUS 404 Returned if there is no epic or sprint name defined in the {originalName}