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 help desk 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 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 through 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. 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 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.

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. Using Velocity templates is therefore recommended over JSPs.

Note

You can find more details on writing Velocity templates at http://velocity.apache.org/engine/releases/velocity-1.5/user-guide.html#velocity_template_language_vtl:_an_introduction.

The plugin descriptor, the only mandatory part of a plugin, is an XML file that 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. 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:

• Developing the plugin

• Deploying it into local JIRA

• Testing the plugin functionality

• Making changes and redeploying the plugin if required

Each of these steps 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 from the preceding sample, 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 the preceding case will be com.jtricks.demo, and the complete 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

Atlassian Marketplace is a one-stop shop where you can find the entire list of commercial and open source plugins that people around the world have written. See https://marketplace.atlassian.com/plugins/app/jira for more details.

Troubleshooting

A common scenario that people encounter while deploying a 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 your or another third-party's plugin! The same applies to individual plugin modules.