Atlassian JIRA, as we all know, is primarily an issue tracking and project management system. Since version 7.0, JIRA also comes in different flavors, namely JIRA Core, JIRA Software, and JIRA Service Desk,each packaged to cater to the needs of its various user categories. JIRA Core focuses on business teams, JIRA software on software teams and JIRA service desk on IT and service teams.
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, much more powerful than these prepackaged flavors! These extra capabilities can take JIRA to the next level, in addition to its core 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,add-ons, also referred to as plugins. JIRA has given the power to its users to write add-ons 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 such as jira-config.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 is add-ons. And that is where we start our cookbook, before we move on to the in-depth details.
So, what is a JIRA add-on? JIRA itself is a web application written in Java. But that doesn't mean you need to know Java to write an add-on, though in most cases you will need to. You might also end up writing a simple descriptor file to add a few links here and there. If that makes the non-Java developer in you happy, watch out for the different plugin modules JIRA supports.
There are two frameworks for writing JIRA add-ons: Atlassian Connect and the Plugins2 framework.
Atlassian Connect add-ons are essentially web applications that operate remotely over HTTP. But they run only on Atlassian Cloud and are well documented at https://developer.atlassian.com/static/connect/docs/latest/guides/introduction.html, hence they are outside the scope of this book.
A Plugins2 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. Hence using velocity templates is recommended over JSPs. You can find more details on writing velocity templates at http://velocity.apache.org/engine/1.7/user-guide.html#velocity-template-language-vtl-an-introduction.
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 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:
Developing the plugin.
Deploying it into local JIRA.
Testing the plugin functionality.
Making changes and redeploying 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.
The following is a sample atlassian-plugin.xml 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, in addition to the key and name. When a plugin is loaded, all the unique modules in it are also loaded.
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 the preceding 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 Marketplace to see if someone else has already done the dirty work for you!
Atlassian Marketplace 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://marketplace.atlassian.com/plugins/app/jira for more details.
A common scenario that people encounter while deploying the 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.