Guide - JIRA help links


JIRA 6.2.5 and later.

This page describes how JIRA links to outside help resources. These methods allow JIRA to utilise the user's locale and JIRA version to decide what documentation to link to without having to hard code the URL. They also allow plugin writers to customise JIRA's help URLs, and generate their own help URLs.

In Java code, you can do something like this.


In a JavaServer Page (JSP), you can just use the Webwork tags to avoid having to add getters to your action.

<a href="<ww:help-url key='jira101'/>" title="<ww:help-title key='jira101'/>">JIRA 101</a>

This section is for plugin writers using or changing JIRA's core help URLs (which will point to JIRA's core help documentation). Plugin writers wanting to have their own independent help URLs should look at the next section.

To use JIRA's core HelpUrls, you simply need to inject the following code into your component, and you can start using it. 

HelpUrls urls;
return urls.getUrl("jira101").getTitle();

The link's names, titles and URLs are pulled from resources provided by plugins. For example system-helppaths-plugin.xml defines a help resource of
# Prefixes

# Section: JIRA 101
jira101.url=JIRA 101
jira101.title=JIRA 101

The properties ending in .ondemand are used to override the values that are used in stand-alone installations (hosted on your own server, and the variable docs.version corresponds to the JIRA version that is running. So when you ask HelpUrls for the jira101 you will get one of the following.

Where  URL Title Version of JIRA
JIRA 101 6.2.x
Cloud JIRA 101 Not applicable

It is possible for plugins to extend and adapt the help URLs used in core JIRA. For example:

<atlassian-plugin key="example" name="Brenden's Example" plugins-version="2">
	<resource type="helpPaths" location="HelpPaths" name="help"/>
# Prefixes

# Section: JIRA 101

When this plugin is installed, JIRA will generate the following Help URLs:

User Locale BTF URL BTF Title OD URL OD Title
Locale.ROOT Get online help about JIRA 101 Get online help about JIRA Studio 101
Locale.ENGLISH Get online help about JIRA 101 Get online help about JIRA Studio 101
 JIRAをはじめ に関するオンライン ヘルプの参照
JIRAのメーカーの紹介 に関するオンライン ヘルプの参照


  • The url-prefix property will change the URL of every Help path in JIRA. This is useful for relocating documentation onto a different domains or onto an internal JIRA server.
  • The files have to be encoded in ISO-8859-1 with non-latian characters encoded using native2ascii or some similar tool. This is a requirement of JIRA language packs.
  • The url-prefix will have ${docs.version} or ${doc.version} replaced with JIRA's current documentation version. This is the version that JIRA uses to reference its documentation (e.g. 6.2.1, 6.2.2, 6.2.x == 062; 6.3.1, 6.3.2, 6.3.x == 063).
  • Properties that end in .ondemand will only be visible when running in a JIRA Cloud instance.
  • The title of a URL is not rendered directly. It is passed through the translation.

This section is about plugins providing their own Help URLs independent of JIRA's core help URLs. See the previous section if you would like to use or customise JIRA's core help URLs.

A plugin may wish to provide their own HelpUrls to their own documentation. The HelpUrlsParser takes a Properties instance and returns a HelpUrls. For example:

HelpUrlsParser parser;
HelpUrls urls = parser.load(loadHelpProperties());
return urls.getUrl("servicedesk.intro").getTitle();

For plugins that are versioned independently of JIRA (JIRA Agile, ServiceDesk, etc) it makes sense to use your own instance of HelpUrls so that your help links point to the documentation for a particular version of your plugin. Here is an example properties file in such a plugin.
# Prefixes

# Section: Intro pages
servicedesk.intro.title=Introduction to ServiceDesk

Notice the use of the ${} property, used to refer to the plugin version that is currently running. To make sure the property gets substituted with the correct plugin version at build time a bit of Maven gymnastics is required:

1. Configure the docsversion-maven-plugin in your pom.xml so that the property value gets set correctly.

                <!-- name of property used in -->

2. Enable resource filtering to get Maven to interpolate your resource files by adding this to your pom.xml (you may want to include/exclude specific files. See the Maven documentation on filtering). 


After this infrastructure is in place you can use your HelpUrls to create links that are versioned for your plugin. Using the above example would yield the following help links.

Where URL Title Version
Server ServiceDesk Intro 1.x
Cloud ServiceDesk Intro Not applicable

HelpUrls and HelpUrlsParser was introduced in JIRA 6.2.4. Before then the HelpUtil class provided similar functionality. For example:

  • HelpUtil.getInstance() or new HelpUtil(): Returns JIRA's core Help URLs.
  • new HelpUtil(Properties): Returns the Help URLs within the passed properties.

HelpUtil now delegates all functionality off to HelpUrls and HelpUrlsParser as appropriate.

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport