J Tricks - Little JIRA Tricks
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>

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>

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">

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!


mohammed italy
06/09/2011 1:42am

thank you for this page , i made my jira link and this link drive you to a form i made in jira . i want to know the code to put in my plugin to get data from this form , i already wrote in my class request.getParameter ("param") to get data but now i don't know the code to write in myform.vm to send this data to another vm file
thank you in advance

06/09/2011 1:49am

You should write a webwork plugin instead of writing a standard JSP form to make things easier. You will find more details about webwork in JIRA at http://confluence.atlassian.com/display/JIRA/JIRA+Webwork+Actions.

There is also a plugin with examples of implementing webwork actions, thanks to Matt. You can find it at https://plugins.atlassian.com/plugin/details/17189

mohammed italy
06/09/2011 8:48am

thank you for your answer .
i have an old jira 3.13 it does not support jsp i think that is why i did the form with velocity macro

06/09/2011 10:57am

Mohammed, JIRA 3.13 will also support jsps. Having said that, you can use velocity templates also with webwork1. The way the action classes and action forwarding works is same!

xu jin
06/10/2011 12:21am

hello, i also have 3.13 and i want o create a jira plugin from eclipse not with sdk in DOS , i already download maven2 plugin in my eclipse. now i can create a maven plugin in my eclipse the problem is that : when i do "run as maven package" maven made my jar but when i do "run as maven install " he installs the jar but not in the directory WEB-INF/lib of jira but in other directory , so i must copy the jar and paste it in my WEB-INF/lib of jira .
i want to know if i can do something to not do copy and paste... thank you

mohammed italy
06/10/2011 8:52am

thank you so much i found the plugin that you linked me so helpful , i hope to not come back with another question again ... i want only to know if there is some code to know how the make a search in jira mail issues , and thank you again you are so helpful
Long and happy life j-tricks :D

06/10/2011 11:37am

@Mohammed Glad we could help. Check out http://confluence.atlassian.com/display/JIRA041/Updating+JIRA+Plugins+for+JIRA+4.0#UpdatingJIRAPluginsforJIRA4.0-NewSearching to know about searching!

@xu mvn install will install the ajr into your local repository, not into JIRA WEB-INF/lib and there is no way to get around it. I guess the only option is to use the plugin SDK if you need that!

06/15/2011 1:40am

hi i have this error in my plygin :
my atlassian-plugin.xml :
<webwork1 key="HelloWorld" name="Hello World Action Example" i18n-name-key="action.hello.world.name">
<description key="action.hello.world.desc">Webwork plugin example that prints hello world. Can also specify a name to say hello to.</description>
<resource type="i18n" name="i18n" location="com.consoft.jira.plugin.ShowInformation" />
<action name="com.consoft.jira.plugin.ShowInformation" alias="ShowInformation">
<view name="input">/templates/formjsp.jsp</view>
<view name="success">/templates/formjsp.jsp</view>

<web-section key="example1" name="Example Section" i18n-name-key="section.example.one.name" location="system.admin" weight="105">
<description key="section.example.one.desc">Example section in the admin page with example links</description>
<label key="Mail test" />

<web-item key="hello_world" name="Greet world link" i18n-name-key="item.hello.world.name" section="system.admin/example1" weight="20">
<description key="item.hello.world.desc">Static link to the HelloWorld action with no name parameter.</description>
<label key="mail search" />
<link linkId="hello_world">/secure/ShowInformation.jspa</link>
<condition class="com.atlassian.jira.plugin.webfragment.conditions.UserLoggedInCondition" />

my formjsp.jsp
<form method="get" action="/secure/ShowInformation.jspa" >
<input type="submit" value="search" ; font-weight:bold ; background-color:#C0C0C0; color:Black">

the error :
HTTP Status 404 - /templates/formjsp.jsp

type Status report

message /templates/formjsp.jsp

description The requested resource (/templates/formjsp.jsp) is not available.
when i click on link it shows me this error i dont know where i have the error
my jira is 3.13

06/15/2011 8:08am

Hello Med,

Where have you put the jsp file?

It shouldn't be a part of the plugin. Instead, jsps should be part of the war. In this case you must have the file under atlassian-jira/templates folder!

06/15/2011 2:49pm

should i put it under atlassian-jira/template of jira directory in my case C:\JIRA-Enterprise-3.13.1\atlassian-jira\template ?? if yes , i have other subdirectories there , can i put them there wherever? and the last question should i call them as i did with .vm files ?

06/15/2011 11:19pm


The path you give in the atlassian-plugin.xml should be relative to atlassian-jira folder. So it should be templates folder and not the existing template folder. Since there is no templates folder, you will have to create one. Alternatively, give some path with more meaningful name, create that directory structure and put the file there.

For jsps and vms, the action forwarding works similar but the content is rendered using different syntax as you would know. Check out the examples in the links provided in the first few comments.

06/20/2011 1:03am

hi there,
thank you for this tutorial . i just want to ask if there some way to make a search in my issue , i mean i have for example 5 issue and i want to retrieve them and make another actions on them .
thank you in advance

06/21/2011 1:12am

@alcantar searching can be done using JqlQueryBuilder as described at http://confluence.atlassian.com/display/JIRA041/Updating+JIRA+Plugins+for+JIRA+4.0#UpdatingJIRAPluginsforJIRA4.0-NewSearching. You just need to use the appropriate JQL. Hope it helps.

07/28/2011 2:49am

Perfect, exactly what I was looking for.
Very usefull.


11/22/2011 1:58pm

Hi there, I was wondering if it was possible to change an interface item. We'd like to modify the way watching appears on the issue screen. for example, instead of seeing Watchers (0), we would like to see something like:

Watchers, then a button that says "click here to edit watchers" that links to the same location as the number of watchers thats' currently there. Is this possible Mr. Tricks?

11/22/2011 4:30pm

@Joe You can modify the templates/jira/issue/block/peopleblock.vm file residing under WEB-INF/classes and add the description alongside the link!

11/22/2011 6:45pm

Hmm - I'm not able to find that file under there. In fact, I do not even see a "block" folder under the issue folder?

11/22/2011 6:54pm

Hey there,

Yeah, it looks like that folder does not exist on version 4.4?

11/22/2011 8:54pm

Oh, you are on JIRA 4.4? In JIRA 4.4, they have it as a separate plugin. It is in the jira-view-issue-plugin-4.4.3.jar!

viewissue/peopleblock.vm file!

You will have to modify the file in that jar!

11/22/2011 8:59pm

Hi! Thanks for getting back to me so quickly.

So it looks like that file is in atlassian-bundled-plugins.zip. Do i need to extract that file, extract the jar, make the changes, jar it back up and then add it back to the zip file? :) Craziness. :)

Joe Caputo
11/22/2011 9:22pm

I love this site. Best resource for jira plugin development bar none.

11/23/2011 5:14am

@Joe That's right. Unzip, make changes in jar, zip it ;)

And thanks for your kind words :)

05/18/2012 2:39am

Hello, Jobin.

Do You have any idea wether it is possible to put any "security" on these menus. I want to put menu in top navigation bar, but I want it to be visible just for people who are in certain grup (because others won't have access to target of these links, so why bother them anyway?:))

05/18/2012 5:23am

Yes, you can do it with the help of conditions as mentioned here: https://developer.atlassian.com/display/PLUGINFRAMEWORK/Web+Item+Plugin+Module

But I don't think there is an in built condition for "Is User in Group" verification. You might end up in writing one!

You can find available conditions here: http://docs.atlassian.com/software/jira/docs/api/latest/com/atlassian/jira/plugin/webfragment/conditions/AbstractJiraCondition.html

I suggest you go for one of the existing conditions if possible!

05/21/2012 1:32am

wow, thanks. I think I will start with global permissions, because our customers does not have some global permissions that our employees do and then see wether I need to actually write my own condition.
Thanks for help, this site is cool and also jira cookbook is on the way :)

07/10/2013 10:04am



Your comment will be posted after it is approved.

Leave a Reply

J tricks - Little JIRA Tricks