Introduction
Atlassian JIRA, as we all know, is primarily an Issue Tracking and Project Tracking System. What many people do not know, though, is the power of its numerous customization capabilities, using which we can turn it into a different system altogether! Maybe a helpdesk system, a user story management system, an online approval process, and a lot more. This is in addition to the issue tracking and project tracking capabilities for which JIRA, arguably, is the best player in the market.
So what are these customizations? How can we convert the JIRA we know into a product we want? Or maybe just add extra functionalities that are specific to our organization?
The answer to these questions probably can be summarized in a single word—plugins. JIRA has given the power to its users to write plugins and customize the functionality in a way they find suitable.
But is that the only way? Definitely not! JIRA itself provides a lot of customization options through its user interface, and in more demanding cases, using property files like jira-application.properties. In some cases, you will also find yourself modifying some of the JIRA core files to tweak functionality or to work around a problem. We will see more of that in the chapters to come but the best entry point to JIRA customizations are plugins. And that is where we start our cookbook, before we move on to the in-depth details.
What is a JIRA plugin?
So, what is a JIRA plugin? JIRA itself is a web application written in Java. But that doesn't mean you need to know JAVA to write a plugin, though in most cases you will need to. You might end up writing a simple descriptor file to add few links here and there. If that makes the non-Java developer in you happy, watch out for the different plugin modules JIRA supports.
A JIRA plugin is a JAR file that has a mandatory plugin descriptor and some optional Java classes and velocity templates. The velocity templates are used to render the HTML pages associated with your plugin, but in some cases, you might also want to introduce JSPs to make use of some pre-existing templates in JIRA. JSPs, as opposed to velocity templates, cannot be embedded in the plugin, but instead they should be dropped into the appropriate folders in the JIRA web application.
The plugin descriptor, the only mandatory part of a plugin, is an XML file which must be named atlassian-plugin.xml. This file is located at the root of the plugin. The atlassian-plugin.xml file defines the various modules in a plugin. The different types of available plugin modules include reports, custom field types, and so on, and these are discussed in detail in the next chapter.
The plugin development process
The process of developing a JIRA plugin can be of varying complexity depending on the functionality we are trying to achieve. The plugin development process essentially is a four step process:
Develop the plugin.
Deploy it into our local JIRA.
Test the plugin functionality.
Make changes and re-deploy the plugin, if required.
Each of these is explained in detail through the various recipes in this book!
JIRA, on start-up, identifies all the plugins that are deployed in the current installation. You can deploy multiple plugins, but there are some things you need to keep an eye on!
The atlassian-plugin.xml file has a plugin key which should be unique across all the plugins. It is much similar to a Java package. Each module in the plugin also has a key that is unique within the plugin. The plugin key combined with the module key, separated by a colon, forms the complete key of a plugin module.
Following is a sample atlassian-plugin.xml file without any plugin modules in it:
<!-- the unique plugin key -->
<atlassian-plugin key="com.jtricks.demo" name="Demo Plugin" plugins-version="2">
<!-- Plugin Info -->
<plugin-info>
<description>This is a Demo Description</description>
<version>1.0</version>
<!-- optional vendor details -->
<vendor name="J-Tricks" url="http://www.j-tricks.com"/>
</plugin-info>
. . . 1 or more plugin modules . . .
</atlassian-plugin>The plugin, as you can see, has details such as description, version, vendor-details, and so on.
When a plugin is loaded, all the unique modules in it are also loaded. The plugin classes override the system classes and so if there is an action that has the same alias name as that of a JIRA action, it is the plugin action class that will be loaded. We will see more about extending actions in the coming chapters.
Suppose you have a report module in your plugin, it will look as follows:
<report key="demo-report" name="My Demo Report" ....> ... </report>
The plugin key, in this case, will be com.jtricks.demo and the module key will be com.jtricks.demo:demo-report.
Hang on, before you start writing your little plugin for a much wanted feature, have a look at the Atlassian plugin exchange to see if someone else has already done the dirty work for you!
Atlassian plugin exchange
Atlassian plugin exchange is a one stop shop where you can find the entire list of commercial and open source plugins people around the world have written. See https://plugins.atlassian.com/search/by/jira for more details.
Troubleshooting
A common scenario that people encounter while deploying their plugin is when the plugin fails to load even though everything looks fine. Make sure your plugin's key is unique and is not duplicated in one of yours or another third-party's plugin!
The same applies to individual plugin modules.
