Adding New Links in the JIRA UI

Often we come across scenarios where we need to add a new link in JIRA under various places in the user interface. The first thing that comes to mind is "Oh I need to modify the jsps and that means my upgrades are going to be a nightmare"! But hang on, JIRA is far better than you think!

Adding a link is JIRA can be achieved pretty easily by writing a web-section and/or web-item plugin module. And that doesn't involve writing any programming languages, including JAVA.

A Web item is a new link that can be added into various places in the JIRA UI. A link will typically go under a web section. A link can simply point to a URL or can be used to invoke an action. Whatever the link is, we can add them in to JIRA in few steps.

Firstly, Identify the web section where the new link should be added. We can create our own web sections using a web-section plugin module or identify an existing section in JIRA.

How about creating a new one? We first need to identify a location in JIRA where the new web section will be added. A list of JIRA locations can be found at Atlassian Web Fragment documentation.

Let us say, we are going to add it under the system administration screen. The web section module is added into atlassian-plugin.xml as follows:

<web-section key="jtricks-admin-section" name="JTricks Section" location="system.admin" i18n-name-key="webfragments.admin.jtricks.section" weight="900">
    <label>J Tricks</label>
    <description>J Tricks Section Descitption</description>
    <tooltip>J Tricks - Little JIRA Tricks</tooltip>
</web-section>

Here we define the location as system.admin and that puts the section under system administration page. We also have given a useful label, description and a tooltip.

A link is then added into a section created as above or into a pre-defined JIRA section. We can directly add the link to a location if it is a non-sectioned one. For sectioned locations, it is the location key, followed by a slash ('/'), and the name of the web section in which it should appear.

For example, if we want to place a link in the web section created before, the section element will have value system.admin/jtricks-admin-section.

<web-item key="jtricks-admin-link" name="JTricks Link" section="system.admin/jtricks-admin-section" i18n-name-key="webfragments.admin.jtricks.item" weight="10">
    <label>J Tricks Website</label>
    <link linkId="jtricks.admin.link">http://www.j-tricks.com</link>
</web-item>

A Web item module has a unique key. The other two important attributes of a web-item are section and weight. Section defines the web section where the link is placed as mentioned above and weight defines the order in which the link will appear.

A web item also has all the elements of a web section - condition/conditions, context-provider, description, param, resource and toolitp, details of which can be found here. In addition a web item also has a link element that defines where the web item should link to. The link could be an action, a direct link etc and can be created dynamically using velocity parameters as shown in the examples below:

<link linkId="create_link" absolute="false">/secure/CreateIssue!default.jspa</link>
<link linkId="google_link">http://www.google.com</link>
<link linkId="profile_link" absolute="false">/secure/ViewProfile.jspa?name=$user.name</link>

An icon element is used when we need to add an icon alongside the link.

<icon height="16" width="16">
    <link>/images/avatar.gif</link>
</icon>

All that is pending is to bundle the plugin descriptor into a plugin jar and deploy it. Once deployed, we can see that a new web item is created in the Web section we  have created previously under the Admin screen of JIRA. 

We can add the item under various different places just by changing the section attribute. So little to do for such a big use case!