Adapting Jira for SAFe in Agile Software Projects

01 Nov, 2017
Xebia Background Header Wave

Agile software projects that are managed with the SAFe framework need the right tools. The popular Jira can be configured to implement a new “SAFe” language. That makes it possible to combine the "Epic" issue type of Jira with SAFe's "Features". SAFe – the Scaled Agile Framework is one of the most commonly used frameworks to scale agile development (SwissQ Trends and Benchmarks Report Schweiz). Atlassian Jira is one of the most commonly used tools to implement agile planning and tracking systems (SwissQ Trends and Benchmarks Report Schweiz).

However, there is a mismatch between these two: Jira uses some (agile) concepts not compatible with SAFe (or the other way round). It starts with the element types, goes on to the setup and ends with the reporting functionality. There are a few plugins available to circumvent some of the issues but these are mostly pricey. This is part one in a series of blog entries describing problems and solutions around Jira and SAFe as well as suggesting some approaches to solve common, basic problems.


Problem: Terms mismatch

Jira – at least in the default configuration – knows two types of backlog elements for agile endeavors: Epic and Story. These two elements are issue types within Jira. Due to its roots – Jira started as a support ticket tracking system – the agile extension (Greenhopper offers a possibility to create sprints and epics) was originally exactly that: an extension. This extension was incorporated into Jira but the overall concept of an extension was kept.

Epics are special issue types in Jira

Only the issue type Epic (and there is exactly one issue type of issue type Epic) can have direct children, linked via an “Epic-Link” (e.g. stories) which might be aggregated for further processing or reporting and convenient handling. There is no standard way to enhance any other issue type with the same functionality as the Epics have. In addition, the issue type Epic should not be renamed; that might cause problems within Jira; and it is actually blocked by default.

Jira Standard Requirements Model Jira Standard Requirements Model

SAFe defines a more complex structure for backlog elements: Epics, Capabilities, Features and Stories (plus all of these might be functional or enabler, see

The lowest-level element in SAFe above the Story is the Feature element. And to make things worse, Epics in SAFe might occur on several different levels.

SAFe 4.5 Requirements Model (Scaled Agile Inc 2017) SAFe 4.5 Requirements Model (Scaled Agile Inc 2017)

In order to keep the reporting features of Jira and the convenience of Epics available in the backlog view, Stories need to be direct children of Epics (via Epic-Link). Then, however, there is a wording mismatch between Jira and the SAFe framework, which might result in naming conventions like “ART-Epic” or “Solution-Epic” and “Portfolio-Epic” (ART = Agile ReleaseTrain, Solution and Portfolio are the levels in SAFe). But this is not really a working solution. First there are still Epics in SAFe on these levels as well and second, it’s hard for people not to get confused; during trainings and in everyday handling of Jira and SAFe.


Solution: Translate Epics to Features


The described solution only works in Atlassian Jira Server, not the Cloud version.

Even though all mentions of "Epic" are replaced in the language files the term "Epic" is still used in JQL – Jira Query Language (advanced) Queries.


The solution to persuade Jira to speak SAFe is to use a special language or translation to enable Jira to use the correct Term for Jira “Epic” and SAFe “Feature”. To achieve this, there are two steps necessary:

  1. Create a custom language file where the term “Epic” is replaced by “Feature”
  2. Persuade Jira to apply this change of terms even for the locked custom fields of “Epic-Link”, “Epic-Color” and “Epic-Label” (and the issue type Epic itself)

Create your own language files

The main idea is to translate all “Epic” terms into “Feature” terms. This is only relevant for the “software” part of Jira. Therefore, only the Jira Software language pack needs to be adjusted. In the Jira Software language pack there is one i18n file ( containing all terms for the “agile extension” of Jira and therefore the key-value-pairs for everything “Epic” related.

However, if there is no “core” language pack for the selected language, Jira defaults to the default language configured by the administrator. This is good if the country you are in has only one language and this language is configured as the default; however the country I’m in has at least three languages. Therefore, the example includes the Jira Core language pack as well.

The following is a step-by-step manual how to achieve this. I chose the de_CH language pack as a starting point and my target language is de_MS; due to my current customer:

  • Go to
  • Download the translations for your preferred language (Jira Core and Jira Software)
    • (if your language is one of the languages bundled with Jira, you can extract the jar files from your current installation of Jira; just search for “language” in the Jira install directory (/WEB-INF/application-installation/jira-software-application/ and /WEB-INF/atlassian-bundled-plugins/)
  • Extract the Jira Software .jar file using any unpacker
    • Navigate in the folder resulting from the Jira Software language .jar to actions:
    • Edit properties. This file contains key-value-pairs for placeholders in Jira UI and their corresponding translations.
    • Replace "Epic" with "Feature" where needed (maybe better not changing values like “epicRank”)
    • Adjust the atlassian-plugin.xml in the root folder to correspond to the country extension selected (in my case "MS"). It has to be a valid country extension!
    • Change all file names in all subfolders from e.g. de_CH to de_MS (so that the file name reflects your selected language and country selection)
  •  Extract the Jira Software .jar file using any unpacker
    • Adjust the atlassian-plugin.xml in the root folder to correspond to the country extension selected (in my case "MS")
    • Change all file names in all subfolders from e.g. de_CH to de_MS (so that the file name reflects your selected language and country selection)

Translate the Custom Fields of Jira

There are three fields in Jira Software and the Epic issue type itself which might not get renamed with the approach above. For these there is a special process needed.

Atlassian describes the solution to translate custom fields:

After unlocking the custom fields and translating them as well, the only missing part is the issue type “Epic” itself. The issue type “Epic” can be translated to Feature as well. Go to the definition of the issue types, and select to translate them. Translate Epic to Feature (don’t forget a description).

Additional hint

There is a way to show the key for most text fields in Jira so it can be found in the i18n key-value-pair files. Just add “i18ntranslate=on” to the URL in the browser to show the keys on the current page and every page to follow.

To turn it back off add “i18ntranslate=off”.

(To add an URL-parameter like that use either “?” if this is the only parameter or “&” if this is just another parameter and there is already a “?”).


The creation of a new “SAFe” language in Atlassian Jira allows Jira to “speak” the SAFe language and keep its special treatment of the standard issue type “Epic” with the naming conventions of SAFe’s “Feature”.

Stay tuned for the next blog entry in this series:

  • Persuading Jira to speak SAFe (this entry)
  • Persuading Jira to play SAFe
  • Persuading Jira to report SAFe
  • Persuading Jira to behave




Get in touch with us to learn more about the subject and related solutions