JIRA 5.x Development Cookbook: This book is your one-stop resource for mastering JIRA extensions and customizations

As we saw in the previous chapter, the JIRA plugin development process is probably an easier task than we expected it to be. With the help of Atlassian Plugin SDK, developers can spend more time worrying about the plugin logic than on the troublesome deployment activities. And yes, after all, it is the plugin logic that is going to make an impact!

This chapter details how the various components fit into JIRA's architecture and how JIRA exposes the various pluggable points. We will also look at an overview of JIRA's system plugins to find out how JIRA uses the plugin architecture to its own benefit, followed by some useful recipes.

It is best to learn the intricacies of system architecture with the help of a diagram. For the benefit of a brief but meaningful explanation on the JIRA architecture, let us have a quick look (or a long stare, whichever you are more comfortable with!) at the following diagram:

JIRA is a web application built using the MVC architecture. It is fully written in Java and is deployed as a WAR file into a Java Servlet Container such as Tomcat.

The majority of the JIRA core functionality revolves around the JIRA Utility and Manager Classes, which thus becomes the heart of JIRA. It also interacts with a lot of third-party components, which we saw earlier, to deliver powerful functionalities such as workflows, permissions, user management, and searching.

As with any other web application, let us start with the incoming requests. Users interact with JIRA using web browsers, but there are other ways to interact with JIRA, such as using the Jelly scripts or by making remote calls...

Let us briefly see the different types of plugin modules supported in JIRA5. All these modules are various extension points, using which we can not only add new functionalities in to JIRA, but also extend some of the existing functionalities.

Let us group them based on functionality instead of seeing them all together!

Let us also quickly see how to deal with the Plugins1 and Plugins2 versions.

Before we go on to the details, it is essential to understand the importance of both these versions. Pre 4.x, JIRA used to support only the Plugins1 version. So why do we need the Plugins2 version?

The key motive behind version2 plugins is to keep the plugins as a bundle isolated from the other plugins and the JIRA core classes. It makes use of the OSGi platform (http://www.osgi.org/) to achieve this. While it keeps the plugins isolated, it also gives you a way to define dependencies between plugins, leaving it to the plugin developer's convenience. It even lets you import or export selected packages within the plugin giving increased flexibility.

The fact that the version2 plugins are deployed as OSGi bundles also means that the plugins are dynamic in nature. They may be installed, started, updated, stopped, and uninstalled at any time during the running of the framework...

In this section, we will see a brief overview of the JIRA system plugins.

A lot of JIRA's functionality is written in the form of plugins. This not only showcases what we can achieve using plugins, but also helps us, as developers, to understand how the various pieces fit together.

If it is the atlassian-plugin.xml file that describes the plugin functionalities, JIRA maintains the information in *.xml files placed under WEB-INF/classes. You will also find the related classes in the exploded folders under WEB-INF/classes.

Let us have a quick look at the various system plugin XMLs that can be found in WEB-INF/classes and the functionality they support:

So, we are in to coding. If you are familiar with JIRA plugin development or have been using them prior to JIRA 5, one thing you might have noticed is that there are quite a few versions of every plugin out there! There are not many plugin versions that work on all JIRA versions. You might also know the reason behind this: JIRA has been evolving a lot in terms of its APIs.

With JIRA 5, Atlassian has introduced stable and core APIs, and with great interest, the development community read the following blog written by Rich Manalang: http://blogs.atlassian.com/2012/03/stable-apis-yes-we-have-them/

The earlier atlassian-jira dependency, which was used in JIRA plugins prior to JIRA 5, is now replaced by two different dependencies: jira-api and jira-core. jira-api (aka the stable API) is a set of classes or interfaces that will not be changed without prior notice. Atlassian will maintain binary compatibility for these classes and interfaces.

jira-core, on the other hand,...

As we discussed earlier, more and more standard functionalities are pushed into bundled plugins as opposed to the JIRA core product. There is no better way to showcase the plugin architecture, I must admit! But that does make the life of high end users who want to modify those functionalities a bit difficult.

Let me take a once simple scenario such as "I want to display the description before the issue details in the View Issue page."

This used to be pretty easy, because all you needed to do was to modify the relevant JSP file and that's it! But now, the View Issue screen rendering is done by jira-view-issue-plugin and it is an Atlassian system plugin. Although the actual work is simple—we only need to modify the atlassian-plugin.xml file—making those changes effective is not as simple as editing the jira-view-issue-plugin-xxx.jar file from the JIRA_Home/.plugins/bundled-plugins folder.

Let us see why!

If you are moving to JIRA 4.x+ from JIRA 3.13.x or earlier versions, one of the important differences is the introduction of v2 plugins. While designing the upgrade to JIRA 4.x+, it makes perfect sense to sometimes migrate the plugins from v1 to v2, although it is not a mandatory step. In this recipe, we will see how to convert a version1 plugin to a version2 plugin.

It is often required to add static resources such as JavaScript files, CSS files, and so on in to our plugins. To enable JIRA to serve these additional static files, they should be defined as downloadable resources.

The web resources plugin module, like the resource module we just saw, allows for the defining of downloadable resources. The difference is that the web resources are added at the top of the page in the header with the cache-related headers set to never expire.

An additional advantage of using the web resources module is that we can specify the resources to be included in specific contexts within the application.

One of the best things about JIRA, if you have a valid license, is that you get to see the source code. You can see it, modify it, break it… err? In this recipe we will modify it, because you have the license to do it!

Most of the time, plugin developers will find themselves writing new actions in JIRA to introduce new functionality. Usually these actions are invoked from new web-item links configured at different places in the UI. It could also be from customized JSPs or other parts of the JIRA framework.

New actions can be added to JIRA with the help of the webwork plugin module.

There are so many user stories for this one! How do you override some of the JIRA built-in actions? How do you do some additional stuff in the JIRA built-in action? Like doing some crazy things immediately after logging work on a ticket, or doing some innovative validations on some of those actions.

Extending the existing JIRA action is an answer to all these questions. Let us see in detail how to do that.

We have seen plugins that are great in terms of functionality but come with a big list of configuration steps. Its much like a treadmill; a great asset but very hard to assemble!

Is there a way we can handle these configurations automatically (like creating custom fields, adding options, creating listeners, services, and so on), when the plugin is installed? The answer is "Yes".