As a newbie in plugin development for atlassian products suite, I faced many obstacles and challenges while developing a simple plugin, from setting up the development environment, reading APIs to setting up the fast development process. So, I decided to write this simple, step-by-step, and descriptive blog for future plugin developers to take advantage of my endeavor and experience with atlassian plugin development.

In this blog I will cover- Setting up the development environment out of:

Atlassian Product – Plugin Development process

• Step 1: Setting up the development environment
• Step 2: Creating a skeleton plugin (we called it mirketa plugin)
• Step 3: Adding plugin modules
• Step 4: Deploying a JIRA plugin
• Step 5: Making changes to and redeploying a plugin
• Step 6: Using FastDev for fast and easy plugin development
• Step 7: Testing and debugging

Atlassian JIRA, as we all know, is originally 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 is the best player in the market.

So what are these changes and customizations? How can we convert the JIRA we know into a product we need? Or maybe just add extra features 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.

What is a JIRA plugin?

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.

You can find more details on writing Velocity templates at
http://velocity.apache.org/engine/releases/velocity-1.7/user-guide/
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:

1. Developing the plugin
2. Deploying it into local JIRA
3. Testing the plugin functionality
4. Making changes and redeploying the plugin if required

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.mirketa.demo” name=Mirketa 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=”Mirketa” url=”https://www.mirketa.com”/>
</plugin-info>
1 or more plugin modules . . .
</atlassian-plugin>

The Mirketa 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=mirketa-demo-report” name=”My Mirketa Demo Report” ….>
..
</report>
The plugin key in the preceding case will be com.mirketa.demo, and the complete module key will be com.mirketa.demo:mirketa-demo-report.

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.

Setting up the development environment
Now that we know what a plugin is, let’s aim at writing one! The first step in writing a JIRA plugin is to set up your environmentif you haven’t done that already. In this blog, I will see how to set up a local environment.
To make our plugin development easier, Atlassian provides the Atlassian plugin software development kit (SDK). It comes along with Maven and a preconfigured settings.xml file to make things easier.
The Atlassian plugin SDK can be used to develop plugins for other Atlassian products, including Confluence, Crowd, and so on, but we are concentrating only on JIRA.

Following are the prerequisites for running the Atlassian plugin SDK:

1. The default port 2990 for the SDK should be available. This is important because different ports are reserved for different Atlassian products.
2. JDK should be installed and Java version 1.6.x is required.
   The SDK is not yet compatible with Java 1.7.
3. Make sure the JAVA_HOME environment variable is set properly and the java -version command outputs the correct Java version details.

How to setup it…
Following are the steps to set up our development environment:

1. Once we have installed Java and the port 2990 is ready, we can download the latest version of Atlassian plugin SDK from https://developer.atlassian.com/ display/DOCS/Getting+Started.
2. Install the SDK by following the instructions provided on the Atlassian Developer Documentation page, depending upon the operating system. Let’s call this directory SDK_HOME.
3. Add the SDK’s bin directory into the environment Path variable.
4. Create a new environment variable, M2_HOME, pointing to the apache-maven
   directory in your /SDK_HOME/atlassian-plugin-sdk directory. SDK version 4.x and above doesn’t need this step.
5. A lot of commonly used dependencies are already available in the repository folder embedded in the SDK. To use this, edit the settings.xml file under M2_HOME/conf/ by modifying the localRepository attribute to point to the embedded repository folder. By default, it will use the USER_HOME/.m2/ repository directory.
6. Install the IDE of your choice. Atlassian recommends Eclipse, IntelliJ IDEA, or NetBeans, as they all support Maven.

With the preceding steps executed properly, we have a development environment for JIRA plugins. The next step is to create a skeleton plugin, import it in to your IDE, and start writing some code! Creating the skeleton plugin, deploying it, and so on, is explained in detail in the forthcoming recipes of this chapter. So, ready, set, go…

Using Maven
If you are a developer, in many cases you will have Maven already installed in your local machine. In that case, point the M2_HOME environment variable to your local Maven, and update the respective settings.xml file with the repository details in the default settings.xml file that ships with the Atlassian plugin SDK. Or, you can simply add the following lines to the existing settings.xml file:
<pluginRepository>
<id>atlassian-plugin-sdk</id>
<url>file://${env.ATLAS_HOME}/repository</url>
<releases>
<enabled>true</enabled>
<checksumPolicy>warn</checksumPolicy>
</releases>
<snapshots>
<enabled>false</enabled>
</snapshots>
</pluginRepository>
Configuring IDEs to use the SDK

If you are using IntelliJ IDEA, configuring it to use the SDK is an easy job because IDEA integrates Maven out of the box. Just load the project by selecting the pom.xml file! See https://developer.atlassian.com/display/DOCS/ Configure+IDEA+to+use+the+SDK for more details.
If you are using Eclipse, make sure you have m2eclipse installed. This is because Eclipse integrates Maven through the Sonatype m2eclipse plugin. You can find more details on configuring this at
https://developer.atlassian.com/display/DOCS/Set+Up+ the+Eclipse+IDE+for+Linux for Linux,

or

https://developer.atlassian.com/ display/DOCS/Set+Up+the+Eclipse+IDE+for+Windows for Windows.
If you are using Netbeans, check out https://developer.atlassian.com/display/ DOCS/Configure+NetBeans+to+use+the+SDK on how to configure it to use the SDK.

Troubleshooting
If you see Maven download errors such as “Could not resolve artifact”, make sure you verify the following:

1. Entry in Maven’s settings.xml file is correct. That is, it points to the correct repositories.
2. Proxy configuration is done if required.
3. Antivirus in the local machine is disabled and/or firewall restrictions removed if none of the above works! Seriously, it makes a difference.

Stay tuned for the next update; next I will cover how to create a plugin skeleton and adding plugin modules.