JIRA includes a plugin system that enables developers to write plugins which enhance JIRA's functionality in various ways.
On this page:
A Plugin Overview
A JIRA plugin is a single JAR containing code, a plugin descriptor (XML) and usually some Velocity template files to render HTML.
The plugin descriptor is the only mandatory part of the plugin. It must be called atlassian-plugin.xml and be located in the root of your JAR file.
Each plugin consists of one or more plugin modules. These are of different types (for example a report, or a portlet) and each has an individual XML element describing it. Each module is described below together with the XML element required for it.
Here is a sample of the descriptor with highlighted elements:
<!-- the plugin key must be unique, think of it as the 'package' of the plugin -->
<atlassian-plugin key="com.atlassian.plugin.sample" name="Sample Plugin" plugins-version="2">
<!-- a short block describing the plugin itself -->
<plugin-info>
<description>This is a brief textual description of the plugin</description>
<!-- the version of the plugin -->
<version>1.1</version>
<!-- the versions of the application this plugin is for -->
<application-version min="3.0" max="3.0"/>
<!-- details of the plugin vendor -->
<vendor name="Atlassian Software Systems Pty Ltd" url="http://www.atlassian.com"/>
</plugin-info>
. . . 1 or more plugin modules . . .
</atlassian-plugin>
Each plugin has a plugin key which is unique among all plugins (eg "com.atlassian.plugin.sample"). Semantically this equates to the package of a Java class. Each module within the plugin also has a module key which is unique within the plugin (eg "myreport"). Semantically this equates to the class name of a Java class.
The plugin key + module key are combined to make the complete key of the plugin module (combining the examples above, the complete key would be "com.atlassian.plugin.sample:myreport"). Note: a : is used to separate the plugin key from the module key.
Each plugin is either of type "Plugins1" or "Plugins2". For details, please see Differences between Plugins1 and Plugins2.
JIRA Plugin Module Types
The following types of plugin modules are supported by JIRA
| Module Type | Since version... | Documentation | Description |
|---|---|---|---|
| portlet | 3.0 | Portlet Plugin Module | Add new portlets to JIRA. Deprecated - please use Gadgets |
| gadget | 4.0 | Gadget Plugin Module | Add a "Gadget" (portlet) to JIRA's dashboard |
| report | 3.0 | Report Plugin Module | Add new reports to JIRA |
| customfield-type | 3.0 | Custom Field Plugin Module | Add new types of fields to JIRA |
| customfield-searcher | 3.0 | Custom Field Plugin Module | Add new types of field searchers to JIRA |
| project-tabpanel | 3.0 | Project Tab Panel Plugin Module | Add new tabs to the Browse 'Project' screen |
| component-tabpanel | 3.10 | Component Tab Panel Plugin Module | Add new tabs to the Browse 'Component' screen |
| version-tabpanel | 3.10 | Version Tab Panel Plugin Module | Add new tabs to the Browse 'Version' screen |
| issue-tab panel | 3.0 | Issue Tab Panel Plugin Module | Add new tabs to the View Issue screen |
| issue-operation | 3.4 | Issue Operations Plugin Module | Add new operations to the View Issue screen |
| resource | 3.5 | Downloadable Plugin Resources | Downloadable resources from within any plugin |
| web-resource | 3.7 | Web Resource Plugin Module | Downloadable resources from within any plugin |
| servlet | 3.5 | Servlet Plugin Module | A standard Java servlet deployed within a JIRA plugin |
| servlet-context-listener | 4.0 | Servlet Context Listener Plugin Module | Deploy Java Servlet context listeners as a part of your plugin |
| servlet-context-param | 4.0 | Servlet Context Parameter Plugin Module | Set parameters in the Java Servlet context shared by your plugin's servlets, filters, and listeners |
| servlet-filter | 4.0 | Servlet Filter Plugin Module | Deploy Java Servlet filters as a part of your plugin |
| webwork | 3.1 | Webwork plugin module | XWork/Webwork actions and views bundled with a plugin, enabling user interaction |
| component | 3.0 | Component Plugin Module | Adds components to JIRA's component system |
| component-import | 4.0 | Component Import Plugin Module | Accesses Java components shared by other plugins |
| module-type | 4.0 | Module Type Plugin Module | Dynamically adds new plugin module types to the plugin framework |
| rest | 4.0 | REST Plugin Module Type | Exposes services and data entities as REST APIs |
| rpc-soap | 3.0 | RPC Endpoint Plugin Module | Deploys a SOAP service within JIRA |
| rpc-xmlrpc | 3.0 | RPC Endpoint Plugin Module | Deploys an XML-RPC service within JIRA |
| jqlfunction | 4.0 | JQL Function Plugin Module | Adds a new function to JIRA's Advanced Search (JQL) |
| search-request-view | 3.7 | Search Request View Plugin Module | Add a new view in the Issue Navigator |
| user-format | 3.13 | User Format Plugin Module | Implements custom behaviours for user details. |
| workflow-condition | 3.0 | Workflow Plugin Modules | Add new conditions to the JIRA workflow |
| workflow-validator | 3.0 | Workflow Plugin Modules | Add new validations to the JIRA workflow |
| workflow-function | 3.0 | Workflow Plugin Modules | Add new post functions to the JIRA workflow |
| web-item | 3.7 | Web Fragments | Add new links into the JIRA web interface |
| web-section | 3.7 | Web Fragments | Add new tabs/sections into the JIRA web interface |
Built-in JIRA system plugins
A number of functions and areas within JIRA 3 are shipped as built in plugins. These can also be useful for plugin developers who want to know more about how to create their own plugins, as they showcase the functionality that can be built.
The system plugins are referenced from the following files (located in /WEB-INF/classes:
- system-workflow-plugin.xml - the built in workflow conditions, validators and functions.
- system-customfieldtypes-plugin.xml - the built in custom field types.
- system-project-plugin.xml - the built in project tab panels (ie roadmap, change log and popular issues).
- system-reports-plugin.xml - the built in system reports (ie time tracking and developer workload reports).
- system-portlets-plugin.xml - all of the built in system portlets.
and in other system-*-plugin.xml files in that directory.
Setting up a Plugin Project
Please refer to How to Build an Atlassian Plugin using the Atlassian Plugin SDK to set up your development environment and create a plugin template.
Deploying a JIRA Plugin
Please see Managing JIRA's Plugins for instructions on how to deploy a JIRA plugin.
Comments (27)
Sep 16, 2004
William Crighton says:
I have a group of modules I'm extending JIRA with and they all fit into a JIRAEx...I have a group of modules I'm extending JIRA with and they all fit into a JIRAExtensions.jar, which to make available I've just copied into <jira dir>/WEB-INF/lib, and restarted the app server. Now, I believe I can make some of the modules plug-ins with the instructions above and just put the atlassian-plugin.xml in the root of the jar file. Will I still 'deploy' the same way, by copying the jar to the WEB-INF/lib directory, or will I need to do something else with it? Also, I'm hoping to leave the plug-in and non-plug in modules side-by-side in the resulting jar file - will this work still?
Sep 16, 2004
Mike Cannon-Brookes says:
Yes - the plugin JAR simply needs to be put into WEB-INF/lib (or anywhere else i...Yes - the plugin JAR simply needs to be put into WEB-INF/lib (or anywhere else in the WAR classpath).
And yes, you can include other classes into this JAR at the same time.
Oct 18, 2004
Mike Aizatsky says:
Can resources be part of plugin?Can resources be part of plugin?
Jan 03, 2005
Mike Cannon-Brookes says:
Resource serving has just been added to the plugin system, and will be released ...Resource serving has just been added to the plugin system, and will be released first with Confluence 1.3. There is a brief guide to these in the Confluence plugins intro, see the resources of type "download".
Oct 18, 2004
Mike Aizatsky says:
Test plugin also uses another format for velocity plugin declaration: window...Test plugin also uses another format for velocity plugin declaration:
Which one is right?
Oct 18, 2004
Mike Cannon-Brookes says:
Velocity resources should always be specified using the <resource>> tag...Velocity resources should always be specified using the <resource>> tag. Where did you see the template tag used?
Oct 18, 2004
Mike Aizatsky says:
Can you please add javadocs for methods in WorkflowPluginFactory and similar?Can you please add javadocs for methods in WorkflowPluginFactory and similar?
Oct 18, 2004
Mike Cannon-Brookes says:
JavaDocs and a full tutorial of how to write workflow plugins is coming. For no...JavaDocs and a full tutorial of how to write workflow plugins is coming.
For now, Vincent Massol has written an excellent tutorial on his blog about how to write a workflow plugin properly.
Sep 11, 2007
David Israel Laks says:
Hello, Recently I create a plugin for Jira 3.10, and I have one Jar file and 2 ...Hello,
Recently I create a plugin for Jira 3.10, and I have one Jar file and 2 Jsps files. I like to add these jsps in the jar file, I can access the jsps files to download, but the action don't work with the same url, can you help me to resolve this problem?
Regards,
David Laks
Jan 15, 2008
Vincent Thoulé says:
Hi David, I have already to find a way to access embedded JSP in a JAR, and did...Hi David,
I have already to find a way to access embedded JSP in a JAR, and did not find a way to do it. I successed to implemented action coded through Velocity page. (See my plugin source ).
I think, a such feature will be possible by overriding WebWork engine ?!
If you success to find a way to do it, let us know !
Rgds
Jan 31, 2008
Malathi Thangavelu says:
HI We have created few plugins, Please let me know what all has to be taken care...HI
We have created few plugins, Please let me know what all has to be taken care / modified, while copying those files from olderversion of jira to a newer version ?
We have also checked the atlassian upgrade guidelines, but didn't get the solution.
Please let me know whether any code change is required for compatibility ?
Thanks
Feb 04, 2008
Jonathan Nolen says:
I've written up some notes about the upgrade process hereI've written up some notes about the upgrade process here
Feb 25, 2008
Ben says:
I was planning on writing a plugin that allows for all issues within specific co...I was planning on writing a plugin that allows for all issues within specific components to be automatically displayed to all members of a certain user group while still having the ability to assign only certain users the rights to that project.
For example: if the issue falls under the component named Installer and i set it to where only administrators can see the issue, i still want anyone in the user group Developers able to see the issue by default because it handles under the Installer component.
When i looked i could not find any documentation on this idea, does anyone know where i would start looking for something along these lines?
Jul 23, 2008
Vojta Micka says:
Hi, I have a problem. I want to make a plugin, but I don't know whitch modul's t...Hi, I have a problem. I want to make a plugin, but I don't know whitch modul's type I have to use. I need modul's type, which display a plugin, on the right under the "Open Issue" and look similar, like this: http://dlg.uloz.to/5a85e42ff8f09807e0a60bc6c8573f8f/599946/plugin.png
Thank you very much, for every help...
Dec 31, 2008
Kazimierz Pogoda says:
I would like to have some "plugin finalization" in my Component Plugin Module. T...I would like to have some "plugin finalization" in my Component Plugin Module. The code fragment which should be fired each time JIRA stops, or even better - fired when plugin is disabled. I have tried with several techniques (PicoContainer lifecycle, StateAware interface, etc.) without success. Could you give me some hints?
Jan 14, 2009
Brad Baker says:
Its the ModuleDescriptor that is told of enabled/disabled events. Unfortunately...Its the ModuleDescriptor that is told of enabled/disabled events. Unfortunately ComponentModuleDescriptor (the guy who help loads component plugins) is StateAware BUt it is not replaceable. So you cant know when you are going away eg (disabled) nor can you know when Pico has removed you as a component (no lifecycle event in PICO either).
I wish I had a better answer. Hopefully the new Atlassian Plugins 2.0 will have better answers to this question.
Apr 01, 2009
Royce Wong says:
I wrote a couple listeners (public class MyListener extends AbstractIssueEventLi...I wrote a couple listeners (public class MyListener extends AbstractIssueEventListener implements IssueEventListener), I added them through JIRA admin and they worked fine.
Now I want to bundle all of them in one plugin and I don't know which module type I should use or how to define them in atlassian-plugin.xml
Any help? Thanks in advance.
Apr 17, 2009
Anonymous says:
Please, please, please put a link to the Jira Development Kit on this page. ...Please, please, please put a link to the Jira Development Kit on this page. I was researching Jira plug-in development for several days, spending hours trying to figure out why the (incomplete) examples weren't working, getting more and more frustrated, before I found the Jira DK site buried somewhere and could finally download working source. The Maven 2 plug-in archetype isn't enough - it will build you a skeleton, but there's nothing in it, and putting the example code into that skeleton isn't trivial or documented very clearly. Being able to download the Jira Development Kit was like a breath of fresh air after being trapped in a coal mine.
Jul 23, 2009
Ben Cheikh Dhia Eddine says:
Hi, I'am developping a jira plugin, but a find a probleme to integrate jira wit...Hi,
I'am developping a jira plugin, but a find a probleme to integrate jira with eclipse, i'am oblige every time to restart tomcat server, to generate the jar plugin with maven, it's fastidious task.
Have you a solution for my problem?
Thanks.
Jul 23, 2009
Don Brown says:
If using JIRA 3.12 or earlier, this is your only option. You can make it a bit ...If using JIRA 3.12 or earlier, this is your only option. You can make it a bit easier by using hotswap and configuring Velocity to not cache templates, but you'll still restart a fair bit. We are working on a new plugin system for JIRA 4.0, which allows for much faster development.
Jul 24, 2009
Ben Cheikh Dhia Eddine says:
Thank you, i'am using jira 3.13, i'am searching a solution with jira Groovy plug...Thank you, i'am using jira 3.13, i'am searching a solution with jira Groovy plugin.
Jul 26, 2009
Don Brown says:
You can use Groovy for plugins in 3.13, but only in compiled form, meaning you w...You can use Groovy for plugins in 3.13, but only in compiled form, meaning you will still need to restart the server to pick up changes. There is the Groovy Runner plugin, which may or may not be relevant to your needs.
Aug 11
Anonymous says:
Hi, I'am developping a project tabpanel, but i like to stay in the same page (t...Hi,
I'am developping a project tabpanel, but i like to stay in the same page (tab panel ) page when i executing an action.
Thank you for your help
Aug 16
Nick Menere says:
Hi, Can you give more details on what you are trying to do? If you redirect ba...Hi,
Can you give more details on what you are trying to do?
If you redirect back to this page after your action had completed, you will be on the same page. I guess it comes down to how you are executing your code.
If it is a webwork action, it will be as simple as:
//return this from you action return getRedirect("/secure/BrowseProject.jspa");Cheers,
Nick
Aug 28
Matt Doar says:
I'm not sure where this information should go, but the names of velocity templat...I'm not sure where this information should go, but the names of velocity template files have to be unique across all plugins. This is easy to do if you have a directory structure in place, e.g.
templates/com/example/jira/plugin/myplugin/view-text.vm
but many plugins seem not to.
Oct 08
Rosie Jameson [Atlassian Technical Writer] says:
Thanks, we will update the docs (http://jira.atlassian.com/browse/JRA-19362)Thanks, we will update the docs (http://jira.atlassian.com/browse/JRA-19362)
Nov 20
Jeff Kirby says:
Sorry...commented on wrong page... In Jira 3.13 you'll need to use window.Sy...Sorry...commented on wrong page...
In Jira 3.13 you'll need to use