JIRA Development Cookbook: Develop and customize plugins, program workflows, work on custom fields, master JQL functions, and more to effectively customize, manage, and extend JIRA

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 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>

<report key="demo-report" name="My Demo Report" ....>
...
</report>

The following are the pre-requisites for running the Atlassian plugin SDK:

With these steps executed properly, we have a development environment for JIRA plugins.

The next step is to create a Skeleton plugin, import it into your IDE, and start writing some code! Creating the Skeleton plugin, deploying it, and so on, is explained in detail in the following recipes.

Even though the aforementioned steps will work in most cases, we will come across scenarios where the setting up of the development environment is not that straightforward. For example, there are extra settings needed for Maven if the machine is behind a firewall. You might even have a local Maven version already installed. In this section, we will see some useful tips on similar cases.

<settings>
  .
  <proxies>
   <proxy>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy.demo.com</host>
      <port>8080</port>
      <username>demouser</username>
      <password>demopassword</password>
      <nonProxyHosts>localhost|*.demosite.com</nonProxyHosts>
    </proxy>
  </proxies>
  .
</settings>

Make sure you have the Atlassian Plugin SDK installed and a version of JIRA 4.x running on your local machine.

A skeleton plugin is nothing but a set of directories and sub directories along with a pom.xml (Maven Project Object Model) file and some sample Java and XML files in the appropriate folders.

Here is a snapshot of how the project will look like in Eclipse. It also shows the design view of the default atlassian-plugin.xml file:

As you can see, there is a pom.xml at the root level and a src folder. A sample LICENSE file and a README file are also created for you at the root level.

Under the src folder, you will find out two folders, main and test, with identical folder structure. All your main Java code goes under the main folder. Any JUnit tests you write will go into the same location under the test folder. There is an additional folder, it, under the test folder where all the integration tests will go!

You will find the plugin descriptor under src/main/resources with sample values already populated in it. The values in the preceding screenshot are populated from the pom.xml. In our case, the plugin key will be populated as com.jtricks.demo:demoplugin when the plugin is built.

There are two more folders under the src/test. src/test/resources, which will hold any resources required for unit tests or integration tests, and the src/test/xml folder can hold the XML data from any other JIRA instance. If the XML is supplied, the SDK will use it to configure the JIRA instance before running the integration tests.

So, that is our plugin Skeleton. All that is pending is some useful Java code and proper module types in the atlassian-plugin.xml file!

Sometimes, for the geeks, it is much easier to run a single command to create a project without bothering about the step-by-step creation. In this section, we will quickly see how to do it. We will also have a look at how to create an Eclipse project if you opt out of installing m2eclipse.

atlas-create-jira-plugin -g my_groupID -a my_artefactId -v my_version -p my_package –non-interactive

atlas-create-jira-plugin -g com.jtricks.demo -a demoplugin -v 1.0 -p com.jtricks.mypackage –non-interactive

atlas-mvn eclipse:eclipse

Make sure you have the development environment set up, as we discussed earlier. Also the skeleton plugin should now have the plugin logic implemented in it.

Installing a JIRA plugin using Atlassian Plugin SDK is a cake walk. Here is how it is done:

If you already have a local JIRA installed or if you want to manually install your plugin for some reason, all you need to do is to package the plugin JAR and copy it across to the JIRA_Home/plugins/installed-plugins directory.

You can package the plugin using the following command:

atlas-mvn clean package

Use atlas-mvn clean install if you also want to install the package plugin into your local repository.

There is only one single command that does the whole thing: atlas-run. When you execute this command, it does the following:

Now, if you look at your target folder, you will see a lot of new folders which were created for the virtual JIRA installation! The two main folders are the container folder, which has the Tomcat container setup, and the jira folder, which has the JIRA WAR along with the JIRA home setup!

You will find the database (HSQLDB), indexes, backups, and attachments under /target/jira/home. And you will see your jira-webapp at /target/container/tomcat6x/cargo-jira-home/webapps/jira.

If you have any JSPs that need to be put under the webapp, you will have to copy it to the appropriate folder under the aforementioned path!

There's more to this.

<properties>
    <jira.version>4.1.2</jira.version>
    <jira.data.version>4.1</jira.data.version>
</properties>

atlas-create-home-zip

<productDataPath>${basedir}/src/test/resources/generated-test-resources.zip</productDataPath>

You can make changes to the plugin and re-deploy it while the JIRA application is still running. Here is how we do it:

Now, there is one thing you need to keep an eye on! Not all the plugin modules can be redeployed like this prior to JIRA 4.4. The following is a list of the plugin modules that can be reloaded with pi in JIRA 4.0.x:

If your plugin module is not there in the preceding list or if the changes doesn't seem to be reflected, press Ctrl + C in the command window running atlas-run and re-run the atlas-run command. That will re-deploy the plugin and restart JIRA.

Post JIRA 4.1, SDK supports reloading of more modules, but whether it works or not depends on what the module does internally.

JIRA 4.4+ supports reloading of all the plugin modules.

It is also possible to run the plugin in debug mode and point your IDE's remote debugger to it.

Following are the steps to do this in Eclipse:

Make sure you have the plugin development environment set up and the skeleton plugin created!

You might have noticed that there are two sample test files, one each for unit tests and integration tests, created under the src/test/java/your_package/ and src/test/java/it folders.

Once you have it ready, it is time to write some tests and run those tests to make sure things work as expected!

The first step is to write some tests! We recommend you to use some powerful testing frameworks like JUnit in collaboration with mocking frameworks like PowerMock or Mockito. Make sure you have the valid dependencies added on to your pom.xml.

Let us now make a huge assumption that you have written a few tests!

Following is the command to run your unit tests from the command line:

atlas-unit-test

The normal Maven command atlas-mvn clean test also does the same thing. If you are running the integration tests, the command to use is:

atlas-integration-test

Or the Maven command: atlas-mvn clean integration-test.

Once we are on to the stage of running tests, we will see it failing at times. There comes the need for debugging. Checkout the *.txt and *.xml files created under target/ surefire-reports/ which has all the required information on the various tests that are executed.

Now, if you want to skip the tests at the various stages, use –skip-tests. For example, atlas-unit-test --skip-tests will skip the unit tests.

You can also use the Maven options directly to skip the unit/integrations tests or both together.

The atlas-unit-test command merely runs the related Maven command: atlas-mvn clean test in the backend to execute the various unit tests. It also generates the outputs into the surefire-reports directory for reference or debugging.

The atlas-integration-test does a bit more. It runs the integration tests in a virtual JIRA environment. It will start up a new JIRA instance running inside a Tomcat container, set up the instance with some default data including a temporary license that lasts for three hours, and execute your tests!

How does JIRA differentiate between the unit tests and integration tests? This is where the folder structure plays an important role. Anything under the src/test/java/it/ folder will be treated as integration tests and everything else will be treated as unit tests!

There is more to it.