Adding New Links in the JIRA UI

6/5/2011

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!

29 Comments

mohammed italy

6/8/2011 09:42:52 pm

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

J-Tricks

6/8/2011 09:49:42 pm

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

6/9/2011 04:48:15 am

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

J-Tricks

6/9/2011 06:57:22 am

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

6/9/2011 08:21:59 pm

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

6/10/2011 04:52:56 am

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

J-Tricks

6/10/2011 07:37:09 am

@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!

Med

6/14/2011 09:40:24 pm

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" />
<actions>
<action name="com.consoft.jira.plugin.ShowInformation" alias="ShowInformation">
<view name="input">/templates/formjsp.jsp</view>
<view name="success">/templates/formjsp.jsp</view>
</action>
</actions>
</webwork1>

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

<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" />
</web-item>

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

</form>
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

J-Tricks

6/15/2011 04:08:31 am

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!

Med

6/15/2011 10:49:12 am

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 ?

J-Tricks

6/15/2011 07:19:02 pm

Med,

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.

alcantar

6/19/2011 09:03:35 pm

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

J-Tricks

6/20/2011 09:12:42 pm

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

Chris

7/27/2011 10:49:39 pm

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

Thanks!

Joe Caputo link

11/22/2011 08:58:26 am

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?

J-Tricks

11/22/2011 11:30:34 am

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

Joe Caputo link

11/22/2011 01:45:48 pm

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?

Joe Caputo link

11/22/2011 01:54:10 pm

Hey there,

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

J-Tricks

11/22/2011 03:54:15 pm

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!

Joe Caputo link

11/22/2011 03:59:43 pm

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 04:22:43 pm

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

J-Tricks

11/23/2011 12:14:52 am

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

And thanks for your kind words :)

Uldis

5/17/2012 10:39:29 pm

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?:))

J-Tricks

5/18/2012 01:23:35 am

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!

Uldis

5/20/2012 09:32:36 pm

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

priyam link

7/10/2013 06:04:18 am

thanks

Nandhini

3/16/2015 11:51:30 pm

Iam new to JIRA SDK,I am trying to create tab named req , in which it consists of two sub tabs searchreq and createreq, now i have to display two different page(vm files) in two different sub tabs, please find below my code...
atlassian-plugin.xml:
<webwork1 key="demo-action" name="JTricks Demo Action" i18n-name-key="j-tricks-demo-action.name">
<description key="j-tricks-demo-action.description">The JTricks Demo Action Plugin</description>
<actions>
<action name="com.jtricks.jira.webwork.JTricksDemoAction" alias="JTricksDemoAction">

<view name="input">/templates/j-tricks-demo-action/jtricksdemoaction/input.vm</view>
<view name="input">/templates/j-tricks-demo-action/jtricksdemoaction/in.vm</view>

</action>

<web-section name="ReqSection" i18n-name-key="Req-Section.name" key="Req-Section" location="Requirements-Menu-link" weight="1000">
<description key="Req-Section.description">The ReqSection Plugin</description>
</web-section>


<web-item name="Requirements Menu" i18n-name-key="Requirements-Menu.name" key="Requirements-Menu" section="system.top.navigation.bar" weight="1000">
<description key="Requirements-Menu.description">Requirements Plugin</description>
<label key="Requirements-Menu.label"/>
<link linkId="Requirements-Menu-link"/>
</web-item>



<web-item name="Create Requirement" i18n-name-key="Create-Requirement.name" key="Create-Requirement" section="Requirements-Menu-link/Req-Section" weight="1000">
<description key="Create-Requirement.description">Create Requirement Plugin</description>
<label key="Create-Requirement.label"></label>
<link linkId="Create-Requirement-link">/secure/JTricksDemoAction!default.jspa</link>
</web-item>



<web-item name="Search Requirement" i18n-name-key="Search-Requirement.name" key="Search-Requirement" section="Requirements-Menu-link/Req-Section" weight="1000">
<description key="Search-Requirement.description">Search Requirement Plugin</description>
<label key="Search-Requirement.label"></label>
<link linkId="Search-Requirement-link">/secure/in.jspa</link>
</web-item>

JTricksDemoAction.java:

public class JTricksDemo extends JiraWebActionSupport {
private static final Logger log = LoggerFactory.getLogger(JTricksDemo.class);
@Override
public String doExecute() throws Exception {
return SUCCESS;
}
}

The issue is, only the "/secure/JTricksDemoAction!default.jspa" executes fine,
other than this, "/secure/in.jspa" or "/secure/JTricksDemoAction!in.jspa" links results in 404 and 500 error,
How to display my second tab" ".

As I am new to this, i dont know how to write the Java class to call different VM files and manipulates,I searched in several sites but there is no tutorial for support :(

J-Tricks

3/21/2015 03:43:26 am

/secure/JTricksDemoAction!in.jspa will look for a method doIn() in the action class.

You need to define a doCommand() method in your action class and invoke it by calling /secure/JTricksDemoAction!command.jspa

You will find more tutorials in the JIRA Development Cookbook!

Yagnesh

6/30/2016 05:43:37 pm

I am facing some issues in web item creation here : https://answers.atlassian.com/questions/39238874/web-item-doesnt-work-as-expected-in-jira-7.1.8

Could you please address

Your comment will be posted after it is approved.

Adding New Links in the JIRA UI

Leave a Reply.

Author

Categories

Archives