How to Develop a Plugin for Atlassian Jira

• Read more about how to gain specific insights about your projects that Atlassian developers did not foresee.

• Learn about obstacles overcome while developing a plugin to extract custom project metrics from Atlassian Jira 7.12.3.

This is where the Jira plug-in mechanism comes in handy as it enables you to crunch through Jira’s repository for your own purposes.

This is where the Jira plug-in mechanism comes in handy as it enables you to crunch through Jira’s repository for your own purposes.

The following is a lengthy and quite technical blog post about obstacles overcome while developing a plugin to extract custom project metrics from Atlassian Jira 7.12.3.

• Introduction
• Getting started
• User Experience
• Connect the UI to Jira Data
• Unit Tests
• Wired Tests 1
• Wired Tests 2
• Accelerate the Cycle

You may have come to this page seeking a solution to one of the following error messages:

The article below records the steps I took to overcome the above issues. I don’t claim that it is the only way to solve them, just that it worked for me. Unfortunately, if you are new to Atlassian plugin development the learning curve can be very steep and the documentation can be hard to find. I hope I can save you a few hours or days of searching for the correct information. References to some relevant Atlassian documentation can be found at the end.

My sincere thanks to several Zuhlke colleagues who worked on the solution with me: Mirko Sciachero, Giovanni Asproni, Michael Dickens and Michael Scott.

Integration/wired tests are run from a complementary plugin installed within the same environment.

Both plugins have dependencies on multiple Java libraries. A Java application satisfies its dependencies at runtime by calling its class loader to obtain them. Standard class loaders delegate to their parents first, and only start searching the locations on their class path if the parent is unable to load the required resource or class.

However, in the case of Jira it’s different. Jira wants to avoid every plugin loading copies of the same class, as this could easily increase the amount of memory used for class storage by a few orders of magnitude. It uses the OSGi framework, which comes with Spring, to provide a cache of already-loaded classes (called Felix) and to satisfy all dependencies from this cache.

This has important implications for the plugin configuration. Felix only loads classes permitted by the plugin configuration. This configuration is composed of instructions in the atlassian-plugin.xml file (a resource), the project POM, and some Atlassian defaults computed at build time.

The result is that it is very easy to encounter NoClassDefFound exceptions even though the required class is on the class path. Whenever this happens, it is worth checking the plugin configuration for missing package-import statements.

Getting started

Installing the tools

I am working on a MacBook Pro, so I have installed:

• Java 8 JDK from Oracle
• XCode from the App Store (this provides, inter alia, a command-line git client, which you will need – but there are other ways to obtain one)
• IntelliJ IDEA direct from the Jetbrains site (I prefer a paid-for license, but the free community edition would do)
• The Atlassian SDK – it turns out that Homebrew is the preferred way to install this, as the pkg installer makes unwarranted assumptions about your version of Java, Python and more

Start your project

The first thing to do is to decide how you’re going to version-control your work. I am using git with an in-house Bitbucket service, so I created a repository via the Web UI on bitbucket and cloned it to my workspace.

Use the sequence of instructions in the Hello World tutorial to create a plugin skeleton – but select your values for Maven group ID, Maven artifact ID, Maven version and Java package according to your real needs. For example (your inputs in bold):

You can now open (no need to import) the workspace in IDEA in order to configure README.md and .gitignore files appropriately. NB the Atlassian tool atlas-create-jira-plugin will create a README file (without an extension) – not to be confused with the markdown file README.md, which github or bitbucket servers will display on the project’s home page.

Before starting to modify anything, commit your initial checkpoint to version control. The easiest way is to open a terminal window in IDEA and enter the following two commands. Subsequent commits are more easily performed within the IDE, using CMD-K.

$ git add .
$ git commit -m 'Initial version'

Things to look out for

• Make sure that the correct version of Java is used both to run your IDE and to run Jira (see above)
  • If you need multiple versions of Java JDK on your machine, consider the use of jEnv to manage the version in use (sorry Windows users – not available for you)
     
• Configure IDEA via its preferences dialog to use atlas-mvn instead of the default bundled mvn executable
  • Maven home directory: /Applications/Atlassian/atlassian-plugin-sdk-6.3.12/apache-maven-3.2.1 (or similar)
     
• If not automatically set, configure the IDEA project SDK to match your version of Java
  • Right-click the top level of the hierarchy under the Project Browser and select “open module settings”
  • Alternatively, click the prompt at the top of any Java source window if it warns you that the project SDK has not been set
     
• Use the latest version of Jira both for the testkit and for Jira itself by adjusting the properties values at the bottom of the pom.xml file (I used 7.12.3 for both)
   
• Add JVM arguments to the maven-jira-plugin in the POM to increase the amount of heap
  • See complete plugin configuration under “Final configuration” below
     
• Look out for the scope of dependencies in the Maven POM – most artifacts should be “provided” or possibly “test” (e.g. com.google.code.gson:gson should be “provided”)
  • Search the target folder after executing atlas-run, atlas-package or atlas-integration-test to see which versions of libraries have been provided
  • Only specify “compile” scope for packages that Jira does not provide, but that your main plugin depends on (atlassian-spring-scanner-annotations appears to be an exception to this rule)
  • Give “runtime” scope to the dependency on atlassian-spring-scanner-runtime
     
• Add the following property values to the POM:

      <junit.version>4.11</junit.version>
      <felix.framework.version>4.2.1</felix.framework.version>
      <gemini.blueprint.version>2.0.5.BUILD-atlassian-m002</gemini.blueprint.version>

• Set the version of the junit dependency to ${junit.version}
• Add the following dependencies to support integration testing:
  • com.atlassian.plugins.rest:atlassian-rest-module:3.2.18:provided
  • com.atlassian.sal:sal-api:3.1.0:provided
  • org.eclipse.gemini.blueprint:gemini-blueprint-core:${gemini.blueprint.version}:provided
  • com.atlassian.jira.tests:jira-testkit-client (just uncomment)
  • com.atlassian.jira:jira-tests:${jira-version}:test
  • org.slf4j:slf4j-log4j12:1.7.9:test
  • junit:junit-dep:${junit-version}:test
     
• Do not let out-of-date tutorial documentation mislead you into adding a dependency on jira-func-test – this seems to be incompatible with Jira 7
• In IDEA, if the source folders are not identified automatically, you may have to right-click the POM file and select “Maven -> import as Maven project” or “Maven -> reimport”
   
• No Import-Package section should be needed in the main plugin’s atlassian-plugin.xml, because the imports are specified in the maven-jira-plugin configuration. However, you will need it in the test plugin (see below)
   
• The fastdev console (see illustration below) is deprecated – if you enable it in the POM, you get lots of verbose warnings.
  • FastDev Console (FDC) would clash with QuickReload (qr) so you can only enable one or the other
  • Only if you have enabled FDC will you be able to initiate integration tests from the Web UI – this is useful if you wish to remote-debug the plugin code on the server. This is the only circumstance under which I found it useful to enable FDC
  • Whether you enable qr or FDC, running the atlas-package command will reload both the custom plugin and its plugin-tests plugin. However, in the FDC case, attempting to run the integration tests from the Web UI after a reload causes a server crash, while in the qr case it does nothing at all (the client receives a 404 error from the server because it tries to invoke a FastDev API)
  • However, there is a workaround – see Speeding up Plugin Testing at the end of this article.
  • Import-Package may specify ‘;version=”0″‘ if you don’t care which version of the dependency is required – normally you would not specify a version
     
• Import-Package should usually specify ‘;resolution:=”optional”‘ – this ensures that the plugin will not fail to load just because some dependency is not available at the time
• 
  Before you can use the IDE effectively, it’s necessary to execute atlas-run, atlas-package or atlas-integration-test at least once. This downloads the required dependencies using the Maven dependency resolution mechanism.

Below, I specify jira.project.sidebar.plugins.navigation as the location where the new menu item should appear. This corresponds to the left-hand menu displayed when the user has navigated to a specific project. I have been unable to find a consolidated list of Jira user interface locations (called sections) where web items, pages, panels and so on can be inserted. Here are some you may find useful:

• General Navigation UI Locations
• Project Settings UI Locations
• Issue view UI Locations
• New issue view UI Locations
• Administration UI Locations

Atlassian also recommends a third-party utility called Web fragments to find sections/locations.

Assuming you wish to use an icon that resembles those of the existing menu items, create this as e.g. arrows.png and store it in the folder src/main/resources/images before you begin. Note that it is extremely difficult to discover in Atlassian’s published documentation how to access an image you have added to the above folder. The correct URL for a Jira web resource is shown below.

Alternatively, define the icon as a SVG drawing embedded in a stylesheet, as the system icons are. Such icons are referenced from within atlassian-plugin.xml using a style reference, so you would omit the advanced setup from the web item in the dialog below, and instead edit the file directly afterwards. See below.

As an alternative to an icon element containing a link to a web resource image file, stylesheet icons are referenced like this (e.g. the “reports” icon):

Connect the UI to Jira Data

Access to Jira Data

At this point we have to provide additional source files: the Velocity template and the context provider class mentioned in the module configuration above. Suggested initial, extremely simple implementations are shown below.

The Velocity template is a recipe for generating a chunk of HTML that the web application server inserts in a web page. As you can see in the example below, it obtains variable text from context variables. In this case, aside from the built-in variables such as $i18n, which is an object capable of returning localised text for any given key (and which should of course be used for all the field labels instead of hard-coding them), we need a variable named $project. The context provider class (in this example, MetricsInfoImpl) is named in the web-panel module defined earlier. It has to provide a public method getContextMap, which returns the context information in the form of key-value pairs. Values can be complex objects – Velocity is clever enough to dereference the required attribute or property by repeatedly calling get… until it has descended to the desired level (e.g. $project.lead.name).

MetricsInfoImpl.java

There are numerous ways to get at information in Jira. Where the desired information is related to a project, the UserProjectHistoryManager turns out to be the most straightforward. There is another class named ProjectManager, which is easier to use in some circumstances – particularly where you already know the project key or you want a list of all projects in the system. However, in this case, we just want the currently selected project.

The annotation @Scanned tells the Atlassian Spring scanner to scan the class at build time. From https://www.j-tricks.com/tutorials/atlassian-spring-scanner-and-nosuchbeandefinitionexception:

• Anything in the constructor needs the @ComponentImport annotation and the class needs a @Scanned annotation
• You can use the components using ComponentAccessor, without the annotations:

    YourComponent yourComponent = ComponentAccessor.getComponent(YourComponent.class);

• But make sure that your component class itself has the required annotations to publish the class as a component: @Component and @ExportAsService, as required.

It is therefore probably a good idea to add the @Scanned annotation to the MyPluginComponentImpl class too, for the sake of consistency.

The full specification of the maven-jira-plugin in pom.xml:

Start the Server

At this point, you should be able to execute atlas-clean followed by atlas-run or atlas-debug. Note that starting the server takes a minute or two, and you’ll probably notice a series of stack traces complaining about missing jar files. Provided that you don’t find the string “failed to load” in the output, there is nothing to worry about. Point your browser at http://localhost:2990/jira and log in with admin/admin.

If things are going wrong, check the log files in these locations:

• target/container/tomcat8x/cargo-jira-home/logs
• target/jira/home/log

Don’t forget to commit your work!

Unit Tests

Automated Testing

So far, we have only used the very rudimentary unit and integration tests generated by the Atlassian tools. In order to perform proper test-driven development (TDD), these need to be extended. In general, there should be a thorough unit test of each custom Java module and a simpler integration test of the same, which tests the “happy day” scenarios as well as one or two of the principal failure modes.

Of course the MetricsInfoImpl class was developed using TDD, although I presented the finished code above as a fait accompli.

Unit Tests

All unit tests are located in the src/test/java source folder under the package ut.path.to.your.package. In this example, the package name is ut.com.zuhlke.training.jira (generated automatically by the initial atlas-create-jira-plugin command). These tests run both under the IDE and under Maven whenever the software is built. I will present one happy-day test case to show how the whole thing works.

The unit tests have to emulate the context in which the plugin will run. This makes the setup quite verbose. Jira uses the mockito framework to make it easy to mock the environment – you just need to know what parts of the environment to mock!

Start by creating the Java class MetricsInfoImplUnitTest and writing a failing test:

This fails to compile, because the objects userProjectHistoryManager, applicationUser and jiraHelper are undefined. Add some mocks to satisfy these requirements (above the first test case):

Run the test to prove that it fails. Surprisingly perhaps, it passes – because of the defensive code in the implementation class, which I inserted following the failure of this test. So let’s add another assertion:

assertEquals("Project", project, contextMap.get(PROJECT));

This adds another import and requires us to add another mock object. This one is provided in quite a different manner. Just above the test case, add the following:

final String projectKey            = "SAM";
final String projectName           = "SampleProject";
final MockProject project          = new MockProject(10001L, projectKey, projectName);

The following imports are added automatically (you may have to respond to the IDE’s prompt with ALT-ENTER):

import static com.zuhlke.training.jira.api.MetricsInfo.PROJECT;
import com.atlassian.jira.project.MockProject;
import static org.junit.Assert.assertEquals;

Rather satisfyingly, the test now runs and fails. The context map has returned null when the object with the key PROJECT was requested. So a little more initialisation is needed at the start of the test case:

This adds another import:

import static com.atlassian.jira.security.Permissions.PROJECT_ADMIN;

The test now passes. Just to be sure that we can access properties of the returned object, add the following to the end of the test case:

final Project contextProject = (Project) contextMap.get(PROJECT);
assertEquals("Project Name", project.getName(), contextProject.getName());

The IDE adds the import:

import com.atlassian.jira.project.Project;

Wired Tests 1

Integration Tests

All integration tests are located under the package it.path.to.your.implementation – in this case, it.com.zuhlke.training.jira. These tests can only be run using the command atlas-integration-test or using the deprecated FastDev Console (see above).

Configuration for wired tests

Before you can use the context provider class in a wired test, you will have to import it to the test plugin as a component. And before you can do that, you’ll have to add annotations to export it appropriately. Add the following annotations to the MetricsInfoImpl class:

@ExportAsService({MetricsInfo.class})
@Named("metricsInfo")

Add the following annotations to its constructor function:

@Inject
@Autowired

The IDE will insert the following imports:

Then add a component-import statement to the file src/test/resources/atlassian-plugin.xml:

Trivial Wired Test

We can now start using this class in wired tests. Start by creating the Java class MetricsInfoImplWiredTest. Annotate the class as follows:

@RunWith(AtlassianPluginsTestRunner.class)

This test runner requires a constructor with parameters corresponding to one or more of the component-imports quoted in the file src/test/resources/atlassian-plugin.xml. If you’re using an IDE, auto-generate the constructor and then change its signature to add the parameters, binding them to private final fields:

You should now have these imports:

import com.atlassian.plugins.osgi.test.AtlassianPluginsTestRunner;
import com.atlassian.sal.api.ApplicationProperties;
import org.junit.runner.RunWith;

Now use the IDE code generator to create your first test:

The following imports are added:

import org.junit.Test;
import static org.junit.Assert.assertTrue;

This test case simply verifies that the parameters passed to the test class constructor conform to the expected type, proving that you have wired everything up correctly. To run the test, you need to make sure that the local Jira server is not running (type CTRL-D into its console if it is still up, and wait up to a minute for it to shut down). Then, at the root of your workspace, enter the command atlas-integration-test.

Wired Tests 2

Non-trivial wired test

Assuming that the test passes, add a second test. First define a constant just below the opening brace of the MetricsInfoImplWiredTest class:

final static String userName      = "admin";

Below the first test case, add the second:

The assertTrue import is deleted and the following imports are added:

import com.atlassian.jira.project.Project;
import java.util.Map;
import static org.junit.Assert.*;

This test will fail: the context map is empty. To make the test pass, you will have to set up certain preconditions and pass the correct parameters to the getContextMap call. Firstly, you’ll have to get hold of the UserProjectHistoryManager object used by the module under test. So add a method to the MetricsInfo interface:

UserProjectHistoryManager getUserProjectHistoryManager();

The following import is added to the interface class’s source file:

import com.atlassian.jira.user.UserProjectHistoryManager;

Implement the method in MetricsInfoImpl.java:

Next, the test class needs a few more constants:

final static String projectName   = "SampleProject";
final static String projectKey    = "SAM";
final static String projectType   = "business";

It also needs a few more fields:

private final Backdoor backdoor;
private final JIRAEnvironmentData environmentData;
private final UserManager userManager;
private final ApplicationUser applicationUser;
private final JiraHelper jiraHelper;
private final UserProjectHistoryManager userProjectHistoryManager;

These fields have to be initialised in the constructor (or inline):

The following imports are added:

import com.atlassian.jira.component.ComponentAccessor;
import com.atlassian.jira.plugin.webfragment.model.JiraHelper;
import com.atlassian.jira.testkit.client.Backdoor;
import com.atlassian.jira.testkit.client.JIRAEnvironmentData;
import com.atlassian.jira.testkit.client.util.TestKitLocalEnvironmentData;
import com.atlassian.jira.user.ApplicationUser;
import com.atlassian.jira.user.UserProjectHistoryManager;
import com.atlassian.jira.user.util.UserManager;

As the comment (above) says, you will have to create a few resources before this constructor can execute successfully.

src/test/resources/localtest.properties

jira.protocol = http
jira.host = localhost
jira.port = 2990
jira.context = /jira
jira.edition = all

jira.xml.data.location = ../../../test-classes/xml

src/test/resources/xml/.keepme

This file is empty – it merely ensures that the xml directory is committed to source code control.

src/test/resources/atlassian-plugin.xml

The plugin-tests plugin now requires more import-packages than its parent plugin. So add the following section to the plugin-info statement:

At this point, the test should still be failing for the same reason as before (because the project is null, not because of an error thrown in the constructor).

You’re now equipped to initialise all the required bits and pieces to enable the test to pass. Add before and after functions for your tests like this:

The following imports are added:

import org.junit.After;
import org.junit.Before;

The test should now pass.

NB (don’t do this now, but note for future use): if you add a constructor argument of type MyPluginComponent as well, you can call its public methods to provide additional help with the setup and teardown functions. You can also use the ProjectManager instance returned by the ComponentAccessor to create and delete project categories, issue types and more, which the backdoor will then be able to add to projects. For example (assuming you have declared constant strings for categoryName, categoryDesc, testIssueType and testIssue):

If you add issue types and project categories in the setup method, remember to remove them in the teardown method – or in this example, in deleteSampleData().

Accelerate the Cycle

Speeding up Plugin Testing

In order to avoid the need to re-start the entire application server for each integration test cycle, I developed a plugin for Jira 7 that allows the old FastDev test console to be used with the new QuickReload feature. This is based on a suggestion from Christophe Merlotti.

Just insert the following under the existing pluginArtifact in the POM:

References

All source code developed in the course of this workshop can be found under https://github.com/zuhlke/example-jira-plugin.

Resources you may find useful include:

• https://developer.atlassian.com/server/jira/platform/integrating-with-jira-software-server/
• https://developer.atlassian.com/server/jira/platform/integrating-with-jira-server
• https://developer.atlassian.com/server/jira/platform/java-apis/
• https://docs.atlassian.com/software/jira/docs/api/7.12.3/
• https://developer.atlassian.com/server/framework/atlassian-sdk/set-up-the-atlassian-plugin-sdk-and-build-a-project/
• https://developer.atlassian.com/server/framework/atlassian-sdk/create-a-helloworld-plugin-project/
• https://developer.atlassian.com/server/framework/atlassian-sdk/faq and child pages
• https://developer.atlassian.com/server/framework/atlassian-sdk/managing-dependencies/
• https://developer.atlassian.com/server/jira/platform/web-resource/
• https://community.atlassian.com/t5/Questions/Atlassian-Plugin-Test-Console-and-QuickReload/qaq-p/371152
• https://developer.atlassian.com/server/framework/atlassian-sdk/adding-resources-to-your-project/
• https://developer.atlassian.com/server/jira/platform/downloadable-add-on-resources/
• https://developer.atlassian.com/platform/marketplace/declaring-marketing-assets-for-server-apps/
• https://developer.atlassian.com/server/framework/atlassian-sdk/troubleshooting
• https://developer.atlassian.com/server/framework/atlassian-sdk/dependency-issues-during-plugin-initialisation/