Search icon CANCEL
Subscription
0
Cart icon
Your Cart (0 item)
Close icon
You have no products in your basket yet
Save more on your purchases! discount-offer-chevron-icon
Savings automatically calculated. No voucher code required.
Arrow left icon
Explore Products
Best Sellers
New Releases
Books
Videos
Audiobooks
Learning Hub
Newsletter Hub
Free Learning
Arrow right icon
JIRA 5.x Development Cookbook
JIRA 5.x Development Cookbook

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

eBook
R$49.99 R$294.99
Paperback
R$367.99
Subscription
Free Trial
Renews at R$50p/m

What do you get with Print?

Product feature icon Instant access to your digital eBook copy whilst your Print order is Shipped
Product feature icon Paperback book shipped to your preferred address
Product feature icon Download this book in EPUB and PDF formats
Product feature icon Access this title in our online reader with advanced features
Product feature icon DRM FREE - Read whenever, wherever and however you want
OR
Modal Close icon
Payment Processing...
tick Completed

Shipping Address

Billing Address

Shipping Methods
Table of content icon View table of contents Preview book icon Preview Book

JIRA 5.x Development Cookbook

Chapter 1. Plugin Development Process

In this chapter, we will cover:

  • Setting up the development environment

  • Creating a skeleton plugin

  • Adding plugin modules

  • Deploying a JIRA plugin

  • Making changes to and redeploying a plugin

  • Using FastDev for plugin development

  • Testing and debugging

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.

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.

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 environment—if you haven't done that already. In this recipe, we 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.

Getting ready

Following are the prerequisites for running the Atlassian plugin SDK:

  • The default port 2990 for the SDK should be available. This is important because different ports are reserved for different Atlassian products.

  • JDK should be installed and Java version 1.6.x is required.

    Note

    The SDK is not yet compatible with Java 1.7.

  • Make sure the JAVA_HOME environment variable is set properly and the java -version command outputs the correct Java version details.

How to do 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.

    Note

    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…

There's more…

If you are facing issues while downloading the dependencies using Maven, just read on.

Proxy settings for Maven

If you are executing behind a firewall, make sure you have configured proxy settings in Maven's settings.xml file. A proxy can be configured as follows:

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

Note

To find out more about proxy settings for Maven and other aspects of it, go to http://maven.apache.org/index.html.

Using local 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:

  • Entry in Maven's settings.xml file is correct. That is, it points to the correct repositories.

  • Proxy configuration is done if required.

  • Antivirus in the local machine is disabled and/or firewall restrictions removed if none of the above works! Seriously, it makes a difference.

See also

  • The Creating a skeleton plugin recipe

Creating a skeleton plugin


In this recipe, we will look at creating a skeleton plugin. We will use the Atlassian plugin SDK to create the skeleton!

Getting ready

Before beginning this recipe, make sure you have the Atlassian plugin SDK installed.

How to do it…

Following are the steps to create a skeleton plugin:

  1. Open a command window and go to the folder where you want to create the plugin.

    Note

    Make sure you use a directory without any spaces in its name, because there are known issues with the SDK not working in directory names with spaces. See https://studio.atlassian.com/browse/AMPS-126 for more details.

  2. Type atlas-create-jira-plugin and press Enter.

  3. Press 1 if you want to create a JIRA 5 plugin or 2 if you want to create a plugin for JIRA 4 or earlier versions.

    Note

    This step can be avoided if you use the atlas-create-jira5-plugin command instead of atlas-create-jira-plugin. Note the use of jira5 instead of jira!

  4. Enter the group-id information when prompted. group-id would normally be coming from your organization name and mostly resembles the Java package. Of course, you can enter a different package name as we move forward if you want to keep it separate. group-id will be used to identify your plugin along with artifact-id, for example, com.jtricks.demo.

  5. Enter the artifact-id information (the identifier for this artifact) when prompted. Do not use spaces here, for example, demoplugin.

  6. Enter the version information when prompted. The default version is 1.0-SNAPSHOT. Enter a new version if you want to change it or press Enter to keep the default version, for example, 1.0.

  7. Enter the package information when prompted. Press Enter if the package value is the same as the group-id value. If not, enter the new value here and press Enter, for example, com.jtricks.mypackage.

  8. Confirm the selection when prompted. If you want to change any of the entered values, type N and press Enter.

  9. Wait for the BUILD SUCCESSFUL message to appear.

Tip

Downloading the example code

You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com . If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.

How it works…

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

Following 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 file 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 two folders—main and test—with an 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, that is atlassian-plugin.xml, under src/main/resources with sample values already populated in it. The values shown in the previous screenshot are populated from the pom.xml file. 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 tree. The src/test/resources folder, which will hold any resources required for unit tests or integration tests, and the src/test/xml folder, which 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 some proper module types in the atlassian-plugin.xml file!

Tip

Remember, the first Maven run is going to take some time, as it downloads all the dependencies into your local repository. A coffee break might not be enough! If you have a choice, plan your meals.

There's more…

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 the next 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.

One step to your skeleton plugin

You can ignore the interactive mode by passing the parameters such as group-id, artifact-id, and so on, as arguments to the atlas-create-jira-plugin command:

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

For the example values we saw earlier, the single line command will be as follows:

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

You can pick and choose the parameters and provide the rest in an interactive mode too!

Creating an Eclipse project

If you are not using m2eclipse, just run the following command from the folder that contains the pom.xml file:

atlas-mvneclipse:eclipse

This will generate the plugin project for Eclipse and you can then import this project into the IDE. Execute atlas-mvn eclipse:clean eclipse:eclipse if you want to clean the old project and create again!

With IDEA or m2eclipse, just opening a file will do. That is, you can just import the project using the File | Import | Existing Maven Projects option, and select the relevant project.

See also

  • The Adding plugin modules recipe

  • The Deploying a JIRA plugin recipe

  • The Making changes to and redeploying a plugin recipe

Adding plugin modules


In this recipe, we will look at adding plugin modules into an existing plugin project.

Getting ready

Make sure the plugin project already exists, or create a new skeleton project as explained in the previous recipe.

How to do it…

Following are the steps to add plugin modules into an existing plugin project:

  1. Open a command window and go to the plugin project folder where pom.xml resides.

  2. Type atlas-create-jira-plugin-module and press Enter. This will show all the available plugin modules as a numbered list, as shown in the following screenshot:

  3. Select the number against the module that you are planning to add. For example, type 25 and press Enter if you want to add a simple Web Item module to the plugin.

  4. Follow the instructions to provide details required for the selected module. Some of the options may have default values.

    Note

    Some modules might also have an advanced setup. Type Y and press Enter when prompted if you want to go to Advanced Setup. If not, type N and press Enter.

  5. Once the module is completed, type Y or N and press Enter when prompted, depending on whether you want to add another module or not.

  6. Repeat the steps for every module you want to add.

  7. Wait for the BUILD SUCCESSFUL message to appear when no more modules are there to be added.

How it works…

Similar to the skeleton plugin creation, a set of directories and subdirectories are created during the process of adding plugin modules, along with a number of Java files or Velocity templates required for the selected plugin module.

It also adds the plugin module definition in the atlassian-plugin.xml file based on our inputs in step 4. A sample plugin descriptor, after adding the Web Item module, is shown as follows:

<?xml version="1.0" encoding="UTF-8"?>
<atlassian-plugin key="${project.groupId}.${project.artifactId}" name="${project.name}" plugins-version="2">
  <plugin-info>
    <description>${project.description}</description>
    <version>${project.version}</version>
    <vendor name="${project.organization.name}" url="${project.organization.url}"/>
  </plugin-info>
  <resource type="i18n" name="i18n" location="com.jtricks.demo.demoplugin"/>
  <web-item name="My Web Item" i18n-name-key="my-web-item.name" key="my-web-item" section="system.user.options/personal" weight="1000">
    <description key="my-web-item.description">The My Web Item Plugin</description>
    <label key="my-web-item.label"></label>
    <link linkId="my-web-item-link">http://www.j-tricks.com</link>
  </web-item>
</atlassian-plugin>

As you can see, a web-item module is added. You can also see a resource module, which is added automatically the first time a plugin module is created. This will be the i18n resource file for the plugin, and more key-value pairs will be added into this file when more modules are added. The file has the name {plugin-artifact-name}.properties and is created under the src/main/resources{plugin-group-folder} folder. In our example, a demo.properties file is created under the src/main/resources/com/jtricks/demo folder.

A sample property file is shown as follows:

my-web-item.label=J-Tricks
my-web-item.name=My Web Item
my-web-item.description=The My Web Item Plugin

See also

  • The Creating a skeleton plugin recipe

  • The Deploying a JIRA plugin recipe

  • The Making changes to and redeploying a plugin recipe

Deploying a JIRA plugin


In this recipe, we will see how to deploy a plugin into JIRA. We will see both the automated deployment using the Atlassian plugin SDK and the manual deployment.

Getting ready

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.

How to do it…

Installing a JIRA plugin using the Atlassian plugin SDK is a cakewalk. The following steps show how it is done:

  1. Open a command window and go to your plugin's root folder, that is, the folder where your pom.xml file resides.

  2. Type atlas-run and press Enter. It is possible to pass more options as arguments to this command. The details regarding this can be found at https://developer.atlassian.com/display/DOCS/atlas-run.

    You will see a lot of things happening as Maven downloads all the dependent libraries into your local repository. As usual, it is going to take a lot of time when you run it for the first time.

  3. If you are on Windows, and if you see a security alert popping up, click on Unblock to allow incoming network connections.

  4. When the installation is complete, you will see the following message:

    [WARNING] [talledLocalContainer] INFO: Server startup in 123558 ms
    [INFO] [talledLocalContainer] Tomcat 6.x started on port [2990]
    [INFO] jira started successfully and available at http://localhost:2990/jira
    [INFO] Type CTRL-C to exit
    
  5. Open http://localhost:2990/jira in your browser.

  6. Log in using the username as admin and password as admin.

  7. Test your plugin! You can always go to Administration | Plugins | Manage Add-ons to confirm that the plugin is deployed properly.

  8. If you already have a local JIRA installed, or if you want to manually install your plugin, all you need to do is to package the plugin JAR and install it via the Universal Plugin Manager (UPM), as described in detail at https://confluence.atlassian.com/display/UPM/Installing+Add-ons#InstallingAdd-ons-Installingbyfileupload. Or, you can copy it across to the JIRA_Home/plugins/installed-plugins directory and restart JIRA.

    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 packaged plugin into your local repository.

How it works…

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

  • Builds your plugin JAR file

  • Downloads the latest/specified version of JIRA to your local machine if it is the first time you are running the command

  • Creates a virtual JIRA installation under your plugin's /target folder

  • Copies the JAR file into the /target/jira/home/plugins/installed-plugins directory

  • Starts JIRA in the Tomcat container

Now, if you look at your target folder, you will see a lot of new folders that 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. You can also 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…

It is also possible to use a specific version of JIRA or to re-use the data that we have used for testing. To find out how, just read on.

Using a specific version of JIRA

As mentioned earlier, atlas-run deploys the latest version of JIRA. But what if you want to deploy the plugin into an earlier version of JIRA and test it? There are two ways to do this:

  • Mention the JIRA version as an argument to atlas-run. Make sure you run atlas-clean if you already have the latest version deployed.

    1. Run atlas-clean (if required).

    2. Run atlas-run -v 5.0 or atlas-run -version 5.0 if you are developing for JIRA version 5.0. Replace the version number with a version of your choice.

  • Permanently change the JIRA version in your plugin's pom.xml file.

    1. Go to your pom.xml file.

    2. Modify the jira.version property value to the desired version.

    3. Modify the jira.data.version property value to a matching version.

    Following is how it will look for JIRA 5.0:

    <properties>
      <jira.version>5.0</jira.version>
      <jira.data.version>5.0</jira.data.version>
    </properties>

Re-using the configurations in each run

Suppose you have added some data onto virtual JIRA; how do you retain it when you clean startup JIRA next time? This is where a new SDK command comes to our rescue. After the atlas-run command has finished its execution, that is, after you have pressed Ctrl + C, execute the following command:

atlas-create-home-zip

This will generate a file named generated-test-resources.zip under the target folder. Copy this file to the /src/test/resources folder or any other known locations. Now modify the pom.xml file to add the following entry under configurations in the maven-jira-plugin plugin section:

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

Modify the path accordingly. This will re-use the configurations the next time you run atlas-run.

Troubleshooting

Following are some points to remember:

  • Missing a JAR file exception? Make sure the local-repository attribute in the settings.xml file points to the embedded Maven repository that comes with the SDK. If the problem still persists, manually download the missing JAR files and use atlas-mvn install to install them into the local repository.

    Note

    Watch out for the proxy settings or antivirus settings that can potentially block the download in some cases!

  • Getting a BeanCreationException error? Make sure your plugin is of version 2. Check your atlassian-plugin.xml file to see if the plugins-version="2" entry is there or not. If not, add the entry shown as follows:

    <atlassian-plugin key="${project.groupId}.${project.artifactId}" name="${project.artifactId}" plugins-version="2">

    Run atlas-clean followed by atlas-run after you have added the preceding entry.

Making changes to and redeploying a plugin


Now that we have deployed the test plugin, it is time to add some proper logic, redeploy the plugin, and test it. Making the changes and redeploying a plugin is pretty easy. In this recipe, we will quickly look at how to do this.

How to do it…

You can make changes to the plugin and redeploy it while the JIRA application is still running. Following is how we do it:

  1. Keep the JIRA application running in the window where we executed atlas-run.

  2. Open a new command window and go to the root plugin folder where your pom.xml file resides.

  3. Run atlas-cli.

  4. Wait for the Waiting for commands message to appear.

  5. Run the pi. pi stands for plugin install and this will compile your changes, package the plugin JAR, and install it into the installed-plugins folder.

    Note

    As of JIRA 4.4, all the modules are reloadable and hence can be redeployed using this technique.

There's more…

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

Debugging in Eclipse

Following are the steps to debug your plugin in Eclipse:

  1. Use atlas-debug instead of atlas-run.

  2. Once the virtual JIRA is up and running with your plugin deployed in it, go to Run | Debug Configurations in Eclipse.

  3. Create a new remote Java application.

  4. Give your application a name, keep the defaults, and give the port number as 5005. This is the default debug port on which the virtual JIRA runs. That's it! Happy debugging!

See also

  • The Setting up the development environment recipe

  • The Creating a skeleton plugin recipe

  • The Using FastDev for plugin development recipe

Using FastDev for plugin development


We have seen how to use atlas-cli to reload a plugin without having to restart atlas-run. It is a pretty good way to save time, but Atlassian have walked the extra mile to develop a plugin named FastDev, which can be used to reload plugin changes during development to all Atlassian applications including JIRA. And that, from the browser itself!

Getting ready

Create a plugin and use atlas-run to run the plugin as discussed in the aforementioned recipe. Let us assume we are doing it on the plugin we created in the previous recipe—the one with the sample Web Item. If we run this sample Web Item plugin, using atlas-run, we can access JIRA at port 2990 as mentioned earlier, and the Web Item will look as highlighted in the following screenshot:

As you can see, the J-Tricks link appears along with the Profile link under the personal section. But what if you wanted the link at the jira-help section, along with Online Help, About JIRA, and so on?

How to do it…

Following are the simple steps to make the aforementioned change to the plugin and reload it using FastDev:

  1. Access the FastDev servlet on the browser using the following path: http://localhost:2990/jira/plugins/servlet/fastdev

    You will find the servlet as shown in the following screenshot:

  2. Make the change to your plugin. In this example, the change is pretty small. All we do is modify the atlassian-plugin.xml file to change the section attribute in the web-item module from section="system.user.options/personal" to section="system.user.options/jira-help".

  3. Click on the Scan and Reload button on the servlet (shown in the previous screenshot). On clicking the button, FastDev will reload the plugin. You can track the progress and see the logs on the browser itself, as shown in the following screenshot:

  4. Once the plugin is successfully reloaded, you will see the following screenshot with a success message:

  5. Reload the JIRA page to see if the change is effective. In our example, the new screen will be as follows:

    As you can see, the J-Tricks link has moved to the help section.

    Note

    Using FastDev is very effective while building a plugin from scratch and testing it, as the pieces fall into the right places gradually.

How it works...

When the Scan and Reload button is clicked, FastDev looks for files that have changed since the last time a plugin was installed. If it detects any changes, it starts a Maven process that reinstalls the plugin.

There's more…

There is more to FastDev than the default configurations. They can be set in your plugin's pom.xml file by adding the required property to the systemPropertyVariables node. You will find the details in the Atlassian documentation (see the previous note box), but the most useful ones are mentioned later.

Adding ignored files

While looking for changes, FastDev ignores certain files such as .js or .css files that don't need a reinstall of the plugin. The following table shows the full list of files/directories that are ignored:

Type

Property name

Default(s)

Directory

fastdev.no.reload.directories

.svn

Extension

fastdev.no.reload.extensions

.js, .vm, .vmd, .fm, .ftl, .html, .png, .jpeg, .gif, .css

File

fastdev.no.reload.files

 –

If you want to ignore additional files or directories, you can add them using the preceding properties, shown as follows:

<systemPropertyVariables>
...
  <fastdev.no.reload.directories>
    images
  </fastdev.no.reload.directories>
  <fastdev.no.reload.extensions>
    classpath
  </fastdev.no.reload.extensions>
  <fastdev.no.reload.files>
    ${basedir}/src/main/resources/LICENSE.txt
  </fastdev.no.reload.files>
</systemPropertyVariables>

Changing admin credentials

FastDev uses the default admin/admin credential to reinstall the plugin. But if the username or password is different, use the fastdev.install.username and fastdev.install.password properties, shown as follows:

<systemPropertyVariables>
...
  <fastdev.install.username>myusername</fastdev.install.username>
  <fastdev.install.password>mypassword</fastdev.install.password>
</systemPropertyVariables>

See also

  • The Setting up the development environment recipe

  • The Creating a skeleton plugin recipe

  • The Making changes to and redeploying a plugin recipe

Testing and debugging


In the world of test-driven development (TDD), writing tests is a part and parcel of the development process. I don't want to bore you with why testing is important! Let us just assume that this holds true for a JIRA plugin development as well. In this recipe, we will see the various commands for running unit tests and integration tests in JIRA plugins.

Note

If you are wondering what exactly TDD is, just go to http://en.wikipedia.org/wiki/Test-driven_development.

Getting ready

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 done this, it is time to write some tests and run those tests to make sure things work as expected!

How to do it...

Without further delay, lets perform the following steps:

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

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

  3. If you are running the integration tests, the command to use is:

    atlas-integration-test
    

    Or, the Maven command to use is:

    atlas-mvn clean integration-test
    
  4. Once we are onto the stage of running tests, we will see them failing at times. Here comes the need for debugging. Checkout the *.txt and *.xml files created under target/ surefire-reports/, which have all the required information on the various tests that are executed.

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

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

    • -Dmaven.test.skip=true: Skips both unit and integration tests

    • -Dmaven.test.unit.skip=true: Skips unit tests

    • -Dmaven.test.it.skip=true: Skips integration tests

How it works…

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

But 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's more…

It is also possible to use custom data for integration tests and to test it against different JIRA versions.

Using custom data for integration/functional tests

While atlas-integration-test makes our life easier by setting up a JIRA instance with some default data in it, we might need some custom data as well to successfully run a few functional tests.

We can do this in a few simple steps:

  1. Export the data from a preconfigured JIRA instance into XML.

  2. Save it under the src/test/xml/ directory.

  3. Provide this path as the value for the jira.xml.data.location property in the localtest.properties file under src/main/resources.

The XML resource will then be imported to JIRA before the tests are executed.

Testing against different versions of JIRA/Tomcat

Just like the atlas-run command, you can use the -v option to test your plugin against a different version of JIRA. Just like before, make sure you run atlas-clean before executing the tests if you had tested it against another version earlier.

You can also use the -c option to test it against a different version of the Tomcat container. For example, atlas-clean && atlas-integration-test -v 3.0.1 -c tomcat5x will test your plugin against JIRA version 3.0.1 using Tomcat container 5.

See also

  • The Setting up the development environment recipe

  • The Deploying a JIRA plugin recipe

Left arrow icon Right arrow icon

Key benefits

  • Extend and customize JIRA; work with custom fields, workflows, reports, gadgets, JQL functions, plugins, and more
  • Customize the look and feel of your JIRA user interface by adding new tabs, web items and sections, drop down menus, and more
  • Master JQL (JIRA Query Language) that enables advanced searching capabilities through which users can search for issues in their JIRA instance and then exploit all the capabilities of the issue navigator

Description

JIRA provides issue tracking and project tracking for software development teams to improve code quality and the speed of development. "JIRA 5.x Development Cookbook" is a one stop resource to master extensions and customizations in JIRA. You will learn how to create your own JIRA plugins, customize the look and feel of your JIRA UI, work with workflows, issues, custom fields, and much more. "JIRA 5.x Development Cookbook" starts with recipes on simplifying the plugin development process followed by a complete chapter dedicated to the plugin framework to master plugins in JIRA. Then we will move on to writing custom field plugins to create new field types or custom searchers. We then learn how to program and customize workflows to transform JIRA into a user friendly system. Reporting support in an application like JIRA is inevitable! With so much data spanning across different projects, issues, and so on, and a lot of planning done for the project, we will cover how to work on reports and gadgets to get customized data according to our needs. We will then look at customizing the various searching aspects of JIRA such as JQL, searching in plugins, managing filters, and so on. "JIRA 5.x Development Cookbook" steers towards programming issues, such as creating, editing, and deleting issues, creating new issue operations, managing the various other operations available on issues via the JIRA APIs, and so on. In the latter half of "JIRA 5.x Development Cookbook", you will learn how to customize JIRA by adding new tabs, menus, and web items, communicate with JIRA via the REST, SOAP or XML/RPC interfaces, and work with the JIRA database. The book ends with a chapter on useful and general JIRA recipes.

Who is this book for?

If you are a JIRA developer or project manager who wants to fully exploit the exciting capabilities of JIRA, then this is the perfect book for you.

What you will learn

  • Create and deploy your own JIRA plugins
  • Deal with custom fields on an issue and program custom field options
  • Program and customize workflows to transform JIRA into a user friendly system
  • Put together reports that show statistics for particular people, projects, versions, or other fields within issues
  • Simplify reporting by writing your own JIRA gadgets, which can be added into a user s dashboard
  • Create, edit, and delete issues
  • Master database handling in JIRA --retrieve issue information from the database, extend the database, retrieve custom field details from the database, access database entities from plugins, and more
  • Communicate with JIRA via the REST, SOAP, or XML/RPC interfaces
Estimated delivery fee Deliver to Brazil

Standard delivery 10 - 13 business days

R$63.95

Premium delivery 3 - 6 business days

R$203.95
(Includes tracking information)

Product Details

Country selected
Publication date, Length, Edition, Language, ISBN-13
Publication date : Apr 25, 2013
Length: 512 pages
Edition : 1st
Language : English
ISBN-13 : 9781782169086
Tools :

What do you get with Print?

Product feature icon Instant access to your digital eBook copy whilst your Print order is Shipped
Product feature icon Paperback book shipped to your preferred address
Product feature icon Download this book in EPUB and PDF formats
Product feature icon Access this title in our online reader with advanced features
Product feature icon DRM FREE - Read whenever, wherever and however you want
OR
Modal Close icon
Payment Processing...
tick Completed

Shipping Address

Billing Address

Shipping Methods
Estimated delivery fee Deliver to Brazil

Standard delivery 10 - 13 business days

R$63.95

Premium delivery 3 - 6 business days

R$203.95
(Includes tracking information)

Product Details

Publication date : Apr 25, 2013
Length: 512 pages
Edition : 1st
Language : English
ISBN-13 : 9781782169086
Tools :

Packt Subscriptions

See our plans and pricing
Modal Close icon
R$50 billed monthly
Feature tick icon Unlimited access to Packt's library of 7,000+ practical books and videos
Feature tick icon Constantly refreshed with 50+ new titles a month
Feature tick icon Exclusive Early access to books as they're written
Feature tick icon Solve problems while you work with advanced search and reference features
Feature tick icon Offline reading on the mobile app
Feature tick icon Simple pricing, no contract
R$500 billed annually
Feature tick icon Unlimited access to Packt's library of 7,000+ practical books and videos
Feature tick icon Constantly refreshed with 50+ new titles a month
Feature tick icon Exclusive Early access to books as they're written
Feature tick icon Solve problems while you work with advanced search and reference features
Feature tick icon Offline reading on the mobile app
Feature tick icon Choose a DRM-free eBook or Video every month to keep
Feature tick icon PLUS own as many other DRM-free eBooks or Videos as you like for just R$25 each
Feature tick icon Exclusive print discounts
R$800 billed in 18 months
Feature tick icon Unlimited access to Packt's library of 7,000+ practical books and videos
Feature tick icon Constantly refreshed with 50+ new titles a month
Feature tick icon Exclusive Early access to books as they're written
Feature tick icon Solve problems while you work with advanced search and reference features
Feature tick icon Offline reading on the mobile app
Feature tick icon Choose a DRM-free eBook or Video every month to keep
Feature tick icon PLUS own as many other DRM-free eBooks or Videos as you like for just R$25 each
Feature tick icon Exclusive print discounts

Frequently bought together


Stars icon
Total R$149.97 R$857.97 R$708.00 saved
JIRA 5.x Development Cookbook
R$367.99
Atlassian Confluence 5 Essentials
R$306.99
JIRA 5.2 Essentials
R$395.99
Total R$149.97R$857.97 R$708.00 saved Stars icon
Banner background image

Table of Contents

11 Chapters
Plugin Development Process Chevron down icon Chevron up icon
Understanding the Plugin Framework Chevron down icon Chevron up icon
Working with Custom Fields Chevron down icon Chevron up icon
Programming Workflows Chevron down icon Chevron up icon
Gadgets and Reporting in JIRA Chevron down icon Chevron up icon
The Power of JIRA Searching Chevron down icon Chevron up icon
Programming Issues Chevron down icon Chevron up icon
Customizing the UI Chevron down icon Chevron up icon
Remote Access to JIRA Chevron down icon Chevron up icon
Dealing with the JIRA Database Chevron down icon Chevron up icon
Useful Recipes Chevron down icon Chevron up icon

Customer reviews

Rating distribution
Full star icon Full star icon Full star icon Full star icon Half star icon 4.3
(4 Ratings)
5 star 75%
4 star 0%
3 star 0%
2 star 25%
1 star 0%
Sim Hua Soon Jun 11, 2013
Full star icon Full star icon Full star icon Full star icon Full star icon 5
I have read the previous edition of the JIRA Development Cookbook and found it to be an extremely useful reference. I am glad that I have the updated edition by my side.This updated edition of the Cookbook had been updated with changes and new features introduced in JIRA 5.It's really useful for anyone who wants to start coding new features to their JIRAs.
Amazon Verified review Amazon
Amazon Customer May 28, 2013
Full star icon Full star icon Full star icon Full star icon Full star icon 5
Great book on JIRA 5, for all things JIRA, development, plugins, interfacing, business.If you want to make JIRA a key part of your company's infrastructure, than this book is a must.Nice job!
Amazon Verified review Amazon
Dale Miller Jun 19, 2013
Full star icon Full star icon Full star icon Full star icon Full star icon 5
I have worked with Jira on both the administration side and plugin development. This book is an excellent addition to anyone's library who is working with Jira and is interested in starting plugin development or increasing their knowledge of plugin development. It does a great job of explaining the necessary steps for a beginner to get started and walks you through examples that become more complex as your knowledge grows. It also provides plenty of more in depth information that will fill in the many gaps missing in or difficult to find in Atlassian's online documentation. Examples and instruction are provided for the most often requested extensions to the base Jira tool. This book will definitely be well used on my part.
Amazon Verified review Amazon
chevy Dec 17, 2013
Full star icon Full star icon Empty star icon Empty star icon Empty star icon 2
The book is probably good for pure developers, but it didn't help me understand the product and to customize it for my purpose.
Amazon Verified review Amazon
Get free access to Packt library with over 7500+ books and video courses for 7 days!
Start Free Trial

FAQs

What is the delivery time and cost of print book? Chevron down icon Chevron up icon

Shipping Details

USA:

'

Economy: Delivery to most addresses in the US within 10-15 business days

Premium: Trackable Delivery to most addresses in the US within 3-8 business days

UK:

Economy: Delivery to most addresses in the U.K. within 7-9 business days.
Shipments are not trackable

Premium: Trackable delivery to most addresses in the U.K. within 3-4 business days!
Add one extra business day for deliveries to Northern Ireland and Scottish Highlands and islands

EU:

Premium: Trackable delivery to most EU destinations within 4-9 business days.

Australia:

Economy: Can deliver to P. O. Boxes and private residences.
Trackable service with delivery to addresses in Australia only.
Delivery time ranges from 7-9 business days for VIC and 8-10 business days for Interstate metro
Delivery time is up to 15 business days for remote areas of WA, NT & QLD.

Premium: Delivery to addresses in Australia only
Trackable delivery to most P. O. Boxes and private residences in Australia within 4-5 days based on the distance to a destination following dispatch.

India:

Premium: Delivery to most Indian addresses within 5-6 business days

Rest of the World:

Premium: Countries in the American continent: Trackable delivery to most countries within 4-7 business days

Asia:

Premium: Delivery to most Asian addresses within 5-9 business days

Disclaimer:
All orders received before 5 PM U.K time would start printing from the next business day. So the estimated delivery times start from the next day as well. Orders received after 5 PM U.K time (in our internal systems) on a business day or anytime on the weekend will begin printing the second to next business day. For example, an order placed at 11 AM today will begin printing tomorrow, whereas an order placed at 9 PM tonight will begin printing the day after tomorrow.


Unfortunately, due to several restrictions, we are unable to ship to the following countries:

  1. Afghanistan
  2. American Samoa
  3. Belarus
  4. Brunei Darussalam
  5. Central African Republic
  6. The Democratic Republic of Congo
  7. Eritrea
  8. Guinea-bissau
  9. Iran
  10. Lebanon
  11. Libiya Arab Jamahriya
  12. Somalia
  13. Sudan
  14. Russian Federation
  15. Syrian Arab Republic
  16. Ukraine
  17. Venezuela
What is custom duty/charge? Chevron down icon Chevron up icon

Customs duty are charges levied on goods when they cross international borders. It is a tax that is imposed on imported goods. These duties are charged by special authorities and bodies created by local governments and are meant to protect local industries, economies, and businesses.

Do I have to pay customs charges for the print book order? Chevron down icon Chevron up icon

The orders shipped to the countries that are listed under EU27 will not bear custom charges. They are paid by Packt as part of the order.

List of EU27 countries: www.gov.uk/eu-eea:

A custom duty or localized taxes may be applicable on the shipment and would be charged by the recipient country outside of the EU27 which should be paid by the customer and these duties are not included in the shipping charges been charged on the order.

How do I know my custom duty charges? Chevron down icon Chevron up icon

The amount of duty payable varies greatly depending on the imported goods, the country of origin and several other factors like the total invoice amount or dimensions like weight, and other such criteria applicable in your country.

For example:

  • If you live in Mexico, and the declared value of your ordered items is over $ 50, for you to receive a package, you will have to pay additional import tax of 19% which will be $ 9.50 to the courier service.
  • Whereas if you live in Turkey, and the declared value of your ordered items is over € 22, for you to receive a package, you will have to pay additional import tax of 18% which will be € 3.96 to the courier service.
How can I cancel my order? Chevron down icon Chevron up icon

Cancellation Policy for Published Printed Books:

You can cancel any order within 1 hour of placing the order. Simply contact customercare@packt.com with your order details or payment transaction id. If your order has already started the shipment process, we will do our best to stop it. However, if it is already on the way to you then when you receive it, you can contact us at customercare@packt.com using the returns and refund process.

Please understand that Packt Publishing cannot provide refunds or cancel any order except for the cases described in our Return Policy (i.e. Packt Publishing agrees to replace your printed book because it arrives damaged or material defect in book), Packt Publishing will not accept returns.

What is your returns and refunds policy? Chevron down icon Chevron up icon

Return Policy:

We want you to be happy with your purchase from Packtpub.com. We will not hassle you with returning print books to us. If the print book you receive from us is incorrect, damaged, doesn't work or is unacceptably late, please contact Customer Relations Team on customercare@packt.com with the order number and issue details as explained below:

  1. If you ordered (eBook, Video or Print Book) incorrectly or accidentally, please contact Customer Relations Team on customercare@packt.com within one hour of placing the order and we will replace/refund you the item cost.
  2. Sadly, if your eBook or Video file is faulty or a fault occurs during the eBook or Video being made available to you, i.e. during download then you should contact Customer Relations Team within 14 days of purchase on customercare@packt.com who will be able to resolve this issue for you.
  3. You will have a choice of replacement or refund of the problem items.(damaged, defective or incorrect)
  4. Once Customer Care Team confirms that you will be refunded, you should receive the refund within 10 to 12 working days.
  5. If you are only requesting a refund of one book from a multiple order, then we will refund you the appropriate single item.
  6. Where the items were shipped under a free shipping offer, there will be no shipping costs to refund.

On the off chance your printed book arrives damaged, with book material defect, contact our Customer Relation Team on customercare@packt.com within 14 days of receipt of the book with appropriate evidence of damage and we will work with you to secure a replacement copy, if necessary. Please note that each printed book you order from us is individually made by Packt's professional book-printing partner which is on a print-on-demand basis.

What tax is charged? Chevron down icon Chevron up icon

Currently, no tax is charged on the purchase of any print book (subject to change based on the laws and regulations). A localized VAT fee is charged only to our European and UK customers on eBooks, Video and subscriptions that they buy. GST is charged to Indian customers for eBooks and video purchases.

What payment methods can I use? Chevron down icon Chevron up icon

You can pay with the following card types:

  1. Visa Debit
  2. Visa Credit
  3. MasterCard
  4. PayPal
What is the delivery time and cost of print books? Chevron down icon Chevron up icon

Shipping Details

USA:

'

Economy: Delivery to most addresses in the US within 10-15 business days

Premium: Trackable Delivery to most addresses in the US within 3-8 business days

UK:

Economy: Delivery to most addresses in the U.K. within 7-9 business days.
Shipments are not trackable

Premium: Trackable delivery to most addresses in the U.K. within 3-4 business days!
Add one extra business day for deliveries to Northern Ireland and Scottish Highlands and islands

EU:

Premium: Trackable delivery to most EU destinations within 4-9 business days.

Australia:

Economy: Can deliver to P. O. Boxes and private residences.
Trackable service with delivery to addresses in Australia only.
Delivery time ranges from 7-9 business days for VIC and 8-10 business days for Interstate metro
Delivery time is up to 15 business days for remote areas of WA, NT & QLD.

Premium: Delivery to addresses in Australia only
Trackable delivery to most P. O. Boxes and private residences in Australia within 4-5 days based on the distance to a destination following dispatch.

India:

Premium: Delivery to most Indian addresses within 5-6 business days

Rest of the World:

Premium: Countries in the American continent: Trackable delivery to most countries within 4-7 business days

Asia:

Premium: Delivery to most Asian addresses within 5-9 business days

Disclaimer:
All orders received before 5 PM U.K time would start printing from the next business day. So the estimated delivery times start from the next day as well. Orders received after 5 PM U.K time (in our internal systems) on a business day or anytime on the weekend will begin printing the second to next business day. For example, an order placed at 11 AM today will begin printing tomorrow, whereas an order placed at 9 PM tonight will begin printing the day after tomorrow.


Unfortunately, due to several restrictions, we are unable to ship to the following countries:

  1. Afghanistan
  2. American Samoa
  3. Belarus
  4. Brunei Darussalam
  5. Central African Republic
  6. The Democratic Republic of Congo
  7. Eritrea
  8. Guinea-bissau
  9. Iran
  10. Lebanon
  11. Libiya Arab Jamahriya
  12. Somalia
  13. Sudan
  14. Russian Federation
  15. Syrian Arab Republic
  16. Ukraine
  17. Venezuela