Extending Jira help links

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 app writers to customise Jira help URLs and generate their own help URLs.

HelpUrls and HelpUrlsParser

In Java code, you can do something like this.

1
2
this.helpUrls.getHelpUrl("jira101").getUrl();

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

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

Jira help links

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

1
2
@Inject
HelpUrls urls;
...
return urls.getUrl("jira101").getTitle();

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

help-paths.properties

1
2
# Prefixes
url-prefix=https://docs.atlassian.com/jira/docs-${docs.version}/
url-prefix.ondemand=https://confluence.atlassian.com/display/Cloud/

# Section: Jira 101
jira101.url=Jira 101
jira101.url.ondemand=Get+a+feel+for+Jira
jira101.title=Jira 101
jira101.title.ondemand=Jira+Cloud

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.

It is possible for apps to extend and adapt the help URLs used in Jira. For example:

atlassian-plugin.xml

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

help-paths_ja_JP.properties

1
2
# Prefixes
url-prefix=https://docs.atlassian.jp/jira/docs-${docs.version}/

# Section: Jira 101
jira101.title=Jiraをはじめ
jira101.title.ondemand=Jiraのメーカーの紹介

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

User Locale - Locale.ROOT

BTF URL - https://docs.atlassian.com/jira/docs-062/Jira+101

BTF Title - Get online help about Jira 101

OD URL - https://confluence.atlassian.com/display/AOD/Jira+Studio+101

OD Title - Get online help about Jira Studio 101

User Locale - Locale.ENGLISH 

BTF URL - https://docs.atlassian.com/jira/docs-062/Jira+101

BTF Title - Get online help about Jira 101 

OD URL - https://confluence.atlassian.com/display/AOD/Jira+Studio+101

OD Title - Get online help about Jira Studio 101

User Locale - Locale.JAPAN

BTF URL - https://docs.atlassian.jp/jira/docs-062/Jira+101

BTF Title - Jiraをはじめ に関するオンライン ヘルプの参照

OD URL - https://confluence.atlassian.com/display/AOD/Jira+Studio+101

OD Title - Jiraのメーカーの紹介 に関するオンライン ヘルプの参照

Notes

• 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 HelpPaths.properties 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 current documentation version. This is the version that Jira uses to reference its documentation (for example 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 online.help.for.topic translation.

Usage within apps

Apps might provide their own HelpUrls to their own documentation. The HelpUrlsParser takes a Properties instance and returns a HelpUrls. For example:

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

For apps that are versioned independently of Jira, like Jira Agile or Service Management, 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 app. Here is an example properties file in such an app.

sd-help-links.properties

1
2
# Prefixes
url-prefix=https://docs.atlassian.com/servicedesk/docs-${servicedesk.docs.version}/
url-prefix.ondemand=https://confluence.atlassian.com/display/Cloud-SD/

# Section: Intro pages
servicedesk.intro.url=Help+Intro
servicedesk.intro.title=Help+Intro

Notice the use of the ${serviceDesk.docs.version} property, used to refer to the app version that is currently running. To make sure the property gets substituted with the correct app 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.

pom.xml

1
2
<plugin>
    <groupId>com.atlassian.maven.plugins</groupId>
    <artifactId>docsversion-maven-plugin</artifactId>
    <version>1.0</version>
    <executions>
        <execution>
            <id>set-docs-version-property</id>
            <phase>initialize</phase>
            <goals>
                <goal>set-property</goal>
            </goals>
            <configuration>
                <!-- name of property used in sd-help-links.properties -->
                <property>servicedesk.docs.version</property>
            </configuration>
        </execution>
    </executions>
</plugin>

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). 

1
2
<resource>
    <directory>src/main/resources</directory>
    <filtering>true</filtering>
</resource>

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

HelpUtil

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

• HelpUtil.getInstance() or new HelpUtil(): Returns Jira 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.