JIRA 5 x development cookbook

www.it-ebooks.info


JIRA 5.x Development
Cookbook

This book is your one-stop resource for mastering JIRA
extensions and customizations

Jobin Kuruvilla

BIRMINGHAM - MUMBAI

www.it-ebooks.info


JIRA 5.x Development Cookbook
Copyright © 2013 Packt Publishing

All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or
transmitted in any form or by any means, without the prior written permission of the publisher,
except in the case of brief quotations embedded in critical articles or reviews.
Every effort has been made in the preparation of this book to ensure the accuracy of the
information presented. However, the information contained in this book is sold without
warranty, either express or implied. Neither the author, nor Packt Publishing, and its dealers
and distributors will be held liable for any damages caused or alleged to be caused directly or
indirectly by this book.
Packt Publishing has endeavored to provide trademark information about all of the companies
and products mentioned in this book by the appropriate use of capitals. However, Packt
Publishing cannot guarantee the accuracy of this information.

First published: April 2013

Production Reference: 1180413

Published by Packt Publishing Ltd.
Livery Place
35 Livery Street
Birmingham B3 2PB, UK.
ISBN 978-1-78216-908-6
www.packtpub.com

Cover Image by Suresh Mogre ()

www.it-ebooks.info


Credits
Author

Project Coordinator

Jobin Kuruvilla

Hardik Patel

Reviewers

Proofreaders

Felix Martineau

Maria Gould

Mizan Ali Sayed

Paul Hindle
Aaron Nash

Acquisition Editor
Kevin Colaco

Indexer
Rekha Nair

Lead Technical Editor
Sruthi Kutty

Graphics
Abhinash Sahu

Technical Editors
Dominic Pereira

Production Coordinator

Kirti Pujari

Arvindkumar Gupta

Mameet Singh Vasir

Hardik B. Soni

Cover Work
Arvindkumar Gupta

www.it-ebooks.info


About the Author
Jobin Kuruvilla is an Atlassian Consultant with experience in customizing JIRA and writing

JIRA plugins for various customers. He is currently working with Go2Group as an Atlassian
platinum expert, and is involved in managing Atlassian products for big enterprises as well as
small starter license installations.

Jobin is the author of JIRA Development Cookbook, Packt Publishing, released in 2011,
which is a well-received book in the JIRA community. He also runs a website named
J-Tricks (), using which he shares numerous tutorials
to help the developer community, who he believes have contributed immensely to his
personal development. It is indeed those tutorials that sowed the first seeds of JIRA
Development Cookbook.
Jobin started his career as a Java/J2EE developer in one of the biggest IT companies in
India. After spending his initial years in the SOA world, he got hooked into this amazing
product called JIRA, which he came across during the evaluation of a number of third-party
tools. Soon, Jobin realized the power of JIRA, and pledged to spread the word. He has been
doing it ever since, and he reckons there is a long way to go!

www.it-ebooks.info

Acknowledgement
No book is the product of just the author; he just happens to be the one with his name on
the cover.
A number of people contributed to the success of this book, and it would take more space
than I have to thank each one individually.
First of all, thanks to the Almighty God for helping me to sail through the difficulties in this
short life and for making my life as wonderful as it is now.
The next biggest thanks goes to Project Coordinator, Hardik Patel, and Lead Technical Editor,
Sruthi Kutty, both of whom went through the pain of making me write another book. Also,
thanks to the entire Packt Publishing team for working so diligently to help bring out another
high quality product.
It is amazing to work with a team of talented developers and technical geeks. Thank you
STORM team, PD&B team, and RAMP team. Your encouragement and support were invaluable
to me; you guys rock!
I must also thank the talented JIRA community who are instrumental in helping each other,
sharing solutions, being active in the forums, running user groups, and what not? I am just
one of the many who have benefited.
Before I wind up, thank you Atlassian for giving us JIRA and a set of other wonderful products.
You don't realize how much you are making our lives easier!
Last, but not the least, a big thanks to all at Go2group for the support extended in writing this
book and believing in my capabilities.

www.it-ebooks.info


About the Reviewers
Felix Martineau runs the Atlassian practice at TechSolCom ()
and has been working as a professional JIRA consultant since 2008. Having started with JIRA
in 2007, over the years he has worked with the entire Atlassian portfolio. Felix has a rare
blend of technical expertise, people skills, and business acumen. For Felix, the people are

always more important than the tools.
I want to thank the people at Packt Publishing for giving me this opportunity
to review the book. Jobin Kuruvilla is one of the top people in the JIRA
community, so it's an honor for me to be involved.
I would also like to thank my girlfriend Genevieve for her continuous
support, as well as Paul Gamache and Jean Perron at TechSolCom,
to whom I owe a lot professionally.

Mizan Ali Sayed is a Master in Computer Science from Pune university, India. Mizan
currently works as an Atlassian tools specialist and has experience with implementing,
customizing, and supporting large scale enterprise JIRA. He is active within the Atlassian
forum "Answers" and has published open source add-ons on the Atlassian Marketplace.
I would like to thank my parents and friends for their continuous support
and encouragement.

www.it-ebooks.info


www.PacktPub.com
Support files, eBooks, discount offers and more
You might want to visit www.PacktPub.com for support files and downloads related to your book.
Did you know that Packt offers eBook versions of every book published, with PDF and ePub files
available? You can upgrade to the eBook version at www.PacktPub.com and as a print book
customer, you are entitled to a discount on the eBook copy. Get in touch with us at service@
packtpub.com for more details.
At www.PacktPub.com, you can also read a collection of free technical articles, sign up for a
range of free newsletters and receive exclusive discounts and offers on Packt books and eBooks.


Do you need instant solutions to your IT questions? PacktLib is Packt's online digital book library.

Here, you can access, read and search across Packt's entire library of books.

Why Subscribe?
ff

Fully searchable across every book published by Packt

ff

Copy and paste, print and bookmark content

ff

On demand and accessible via web browser

Free Access for Packt account holders
If you have an account with Packt at www.PacktPub.com, you can use this to access PacktLib
today and view nine entirely free books. Simply use your login credentials for immediate access.

Instant Updates on New Packt Books
Get notified! Find out when new books are published by following @PacktEnterprise on Twitter,
or the Packt Enterprise Facebook page.

www.it-ebooks.info


www.it-ebooks.info


This book is dedicated to Sarah, Anna, Anu, Juby, Alice, and Kuruvilla. Also, my

friends from TKM and JNV Kottayam.
This book would not have been possible without you, one way or the other!
A big thank you from the bottom of my heart. I have nothing to give back, but my
love and prayers.

www.it-ebooks.info


www.it-ebooks.info


Table of Contents
Preface1
Chapter 1: Plugin Development Process
7

Introduction7
Setting up the development environment
10
Creating a skeleton plugin
13
Adding plugin modules
17
Deploying a JIRA plugin
19
Making changes to and redeploying a plugin
23
Using FastDev for plugin development
24
Testing and debugging

28

Chapter 2: Understanding the Plugin Framework

31

Introduction31
Architecture explained
34
Types of plugin modules
39
Working with the Plugins1 and Plugins2 versions
44
JIRA system plugins
46
Stable and core APIs
49
Modifying Atlassian bundled plugins
50
Converting plugins from v1 to v2
51
Adding resources into plugins
54
Adding web resources into plugins
56
Building JIRA from source
59
Adding new webwork actions to JIRA
63
Extending a webwork action in JIRA

68
Capturing plugin installation/uninstallation events
71

www.it-ebooks.info


Table of Contents

Chapter 3: Working with Custom Fields

77

Introduction78
Writing a simple custom field
78
Custom field searchers
83
Dealing with custom fields on an issue
88
Programming custom field options
90
Overriding validation of custom fields
93
Customizing the change log value
94
Migrating from one custom field type to another
96
Making custom fields sortable
99

Displaying custom fields on subtask columns
100
User and date fields
102
Adding custom fields to notification mails
103
Adding help text for a custom field
105
Removing the "none" option from a select field
107
Making the custom field project importable
108
Changing the size of a text area custom field
109

Chapter 4: Programming Workflows

113

Chapter 5: Gadgets and Reporting in JIRA

165

Introduction114
Writing a workflow condition
115
Writing a workflow validator
122
Writing a workflow post function
129

Editing an active workflow
136
Making an issue editable/non-editable based on workflow status
138
Including/excluding resolutions for specific transitions
139
Permissions based on workflow status
140
Internationalization in workflow transitions
142
Obtaining available workflow actions programmatically
144
Programmatically progressing on workflows
146
Obtaining workflow history from the database
148
Reordering workflow actions in JIRA
151
Creating common transitions in workflows
153
Creating global transitions in workflows
158
Jelly escalation
160
Introduction166
Writing a JIRA report
167
Reports in an Excel format
174
Data validation in JIRA reports

177
Restricting access to reports
179
ii

www.it-ebooks.info


Table of Contents

Object-configurable parameters for reports
Creating a pie chart in JIRA
Writing JIRA 4 gadgets
Invoking REST services from gadgets
Configuring user preferences in gadgets
Accessing gadgets outside of JIRA

181
189
194
202
206
214

Chapter 6: The Power of JIRA Searching

219

Chapter 7: Programming Issues

253

Chapter 8: Customizing the UI

291

Introduction219
Writing a JQL function
220
Sanitizing JQL functions
226
Adding a search request view
229
Smart querying using quick search
235
Searching in plugins
239
Parsing JQL queries in plugins
242
Linking directly to search queries
243
Index and de-index programmatically
244
Managing filters programmatically
246
Subscribing to a filter
249
Introduction253
Creating an issue from a plugin
254

Creating subtasks on an issue
257
Updating an issue
258
Deleting an issue
259
Adding new issue operations
260
Conditions on issue operations
263
Working with attachments
265
Time tracking and worklog management
267
Working with comments on issues
275
Programming change logs
277
Programming issue links
279
Discarding fields while cloning
282
JavaScript tricks on issue fields
284
Creating issues and comments from an e-mail
287
Introduction292
Changing the basic look and feel
292
Adding new web sections in the UI

295
Adding new web items in the UI
297
Use of decorators
300
iii

www.it-ebooks.info


Table of Contents

Adding conditions for web fragments
Creating new Velocity context for web fragments
Adding a new drop-down menu on the top navigation bar
Dynamic creation of web items
Adding new tabs in the View Issue screen
Adding new tabs in the Browse Project screen
Creating the project tab panel using fragments
Adding new tabs in the Browse Version screen
Adding new tabs in the Browse Component screen
Adding issue link renderers
Extending a webwork action to add UI elements
Displaying dynamic notifications/warnings on issues
Re-ordering issue operations in the View Issue page
Re-ordering fields in the View Issue page

305
308
310

311
315
319
321
325
328
330
338
342
346
348

Chapter 9: Remote Access to JIRA

353

Chapter 10: Dealing with the JIRA Database

393

Introduction354
Writing a Java client for the REST API
354
Creating a SOAP client
356
Writing a Java XML-RPC client
358
Working with issues
360
Working with attachments

364
Remote time tracking
366
Working with comments
368
Remote user and group management
369
Progressing an issue in a workflow
370
Managing versions
371
Managing components
373
Remote administration methods
374
Exposing services and data entities as REST APIs
378
Deploying a SOAP service in JIRA
384
Deploying an XML-RPC service within JIRA
388
Introduction394
Extending the JIRA database with a custom schema
395
Accessing database entities from plugins
399
Persisting plugin information in the JIRA database
401
Using Active Objects to store data
405

Accessing the JIRA configuration properties
408
Getting a database connection for JDBC calls
409
Migrating a custom field from one type to another
410
iv

www.it-ebooks.info


Table of Contents

Retrieving issue information from a database
Retrieving custom field details from a database
Retrieving permissions on issues from a database
Retrieving workflow details from a database
Updating the issue status in a database
Retrieving users and groups from a database
Dealing with change history in a database

Chapter 11: Useful Recipes

411
414
416
419
421
422
424

427

Introduction428
Writing a service in JIRA
428
Adding configurable parameters to a service
430
Writing scheduled tasks in JIRA
433
Writing listeners in JIRA
435
Customizing e-mail content
442
Redirecting to a different page in webwork actions
444
Adding custom behavior for user details
445
Deploying a servlet in JIRA
450
Adding shared parameters to the servlet context
453
Writing a servlet context listener
455
Using filters to intercept queries in JIRA
456
Adding and importing components in JIRA
459
Adding new module types to JIRA
463

Enabling access logs in JIRA
467
Enabling SQL logging in JIRA
470
Overriding JIRA's default components in plugins
471
Internationalization in webwork plugins
474
Sharing common libraries across v2 plugins
476
Operations using direct HTML links
478

Index483

v

www.it-ebooks.info


www.it-ebooks.info


Preface
This book is your one-stop resource for mastering JIRA extension and customization. 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.
The book starts with recipes on simplifying the plugin development process followed by a
complete chapter dedicated to the plugin framework for mastering 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.
We will then look at customizing the various searching aspects of JIRA such as JQL, searching
in plugins, managing filters, and so on.
Then the book steers towards programming issues, that is, creating/editing/deleting issues,
creating new issue operations, managing the various other operations available on issues
using the JIRA APIs, and so on.
In the latter half of the book, you will learn how to customize JIRA by adding new tabs, menus,
and web items, and communicate with JIRA using the REST, SOAP, or XML/RPC interfaces, as
well as working with the JIRA database.
The book ends with a chapter on useful and general JIRA recipes.

What this book covers
Chapter 1, Plugin Development Process, covers the fundamentals of the JIRA plugin
development process. It covers, in detail, the setting up of a development environment,
creating a plugin, deploying it, and testing it.
Chapter 2, Understanding the Plugin Framework, covers, in detail, the JIRA architecture, and
also looks at the various plugin points. It also looks at how to build JIRA from source and
extend or override the existing JIRA functionalities.

www.it-ebooks.info


Preface
Chapter 3, Working with Custom Fields, looks at programmatically creating custom fields in
JIRA, writing custom field searchers, and various other useful recipes related to custom fields.
Chapter 4, Programming Workflows, looks at the various ways of programming the JIRA
workflows. It includes writing new conditions, validators, post functions, and so on, and
contains related recipes that are useful in extending the workflows.
Chapter 5, Gadgets and Reporting in JIRA, covers the reporting capabilities of JIRA. It looks at

writing reports, dashboard gadgets, and much more in detail.
Chapter 6, The Power of JIRA Searching, covers the searching capabilities of JIRA and how it
can be extended using the JIRA APIs.
Chapter 7, Programming Issues, looks at the various APIs and methods used for managing
issues programmatically. It covers the CRUD operations, working with attachments,
programming the change logs and issue links, time tracking, and much more.
Chapter 8, Customizing the UI, looks at the various ways of extending and modifying the JIRA
user interface.
Chapter 9, Remote Access to JIRA, looks at the remote capabilities of JIRA—REST, SOAP,
and XML/RPC—and the ways of extending them.
Chapter 10, Dealing with the JIRA Database, looks at the database architecture of JIRA and
covers the major tables in detail. It also covers the different ways to extend the storage and
access or modify the data from plugins.
Chapter 11, Useful Recipes, covers a selected list of useful recipes, which do not belong in the
preceding categories, but are powerful enough to get your attention. Read away!

What you need for this book
This book focuses on JIRA development. You need the following software as a bare minimum:
ff

JIRA 5.x+

ff

JAVA 1.6+

ff

Maven 2.x

ff

Atlassian Plugin SDK

ff

An IDE of your choice. The examples in the book use Eclipse and SQL Developer.

Some of the recipes are too simple to use the fully-fledged plugin development process,
and you will see this highlighted as you read through the book!

2

www.it-ebooks.info


Preface

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

Conventions
In this book, you will find a number of styles of text that distinguish between different kinds of
information. Here are some examples of these styles, and an explanation of their meaning.
Code words in text, database table names, folder names, filenames, file extensions,
pathnames, dummy URLs, user input, and Twitter handles are shown as follows: " To use this,
edit the settings.xml file under M2_HOME/conf/ by modifying the localRepository
attribute to point to the embedded repository folder."
A block of code is set as follows:

<settings>
.


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

Any command-line input or output is written as follows:
select id from changegroup where issueid = '10010'

New terms and important words are shown in bold. Words that you see on the screen, in
menus or dialog boxes for example, appear in the text like this: "That is, you can just import
the project using the File | Import | Existing Maven Projects option, and selecting the
relevant project."

3

www.it-ebooks.info


Preface

Warnings or important notes appear in a box like this.

Tips and tricks appear like this.

Reader feedback
Feedback from our readers is always welcome. Let us know what you think about this
book—what you liked or may have disliked. Reader feedback is important for us to
develop titles that you really get the most out of.
To send us general feedback, simply send an e-mail to , and
mention the book title via the subject of your message.
If there is a topic that you have expertise in and you are interested in either writing or
contributing to a book, see our author guide on www.packtpub.com/authors.

Customer support
Now that you are the proud owner of a Packt book, we have a number of things to help you to
get the most from your purchase.

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

Errata
Although we have taken every care to ensure the accuracy of our content, mistakes do
happen. If you find a mistake in one of our books—maybe a mistake in the text or the code—
we would be grateful if you would report this to us. By doing so, you can save other readers
from frustration and help us improve subsequent versions of this book. If you find any errata,
please report them by visiting selecting
your book, clicking on the errata submission form link, and entering the details of your

errata. Once your errata are verified, your submission will be accepted and the errata
will be uploaded on our website, or added to any list of existing errata, under the Errata
section of that title. Any existing errata can be viewed by selecting your title from
/>4

www.it-ebooks.info


Preface

Piracy
Piracy of copyright material on the Internet is an ongoing problem across all media. At Packt,
we take the protection of our copyright and licenses very seriously. If you come across any
illegal copies of our works, in any form, on the Internet, please provide us with the location
address or website name immediately so that we can pursue a remedy.
Please contact us at with a link to the suspected pirated material.
We appreciate your help in protecting our authors, and our ability to bring you valuable content.

Questions
You can contact us at if you are having a problem with any
aspect of the book, and we will do our best to address it.

5

www.it-ebooks.info


www.it-ebooks.info

1

Plugin Development
Process
In this chapter, we will cover:
ff

Setting up the development environment

ff

Creating a skeleton plugin

ff

Adding plugin modules

ff

Deploying a JIRA plugin

ff

Making changes to and redeploying a plugin

ff

Using FastDev for plugin development

ff

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.

www.it-ebooks.info


Plugin Development Process
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.
You can find more details on writing Velocity templates at
/>velocity-1.5/user-guide.html#velocity_
template_language_vtl:_an_introduction.

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

Developing the plugin

ff

Deploying it into local JIRA

ff

Testing the plugin functionality

ff

Making changes and redeploying the plugin if required

Each of these steps is explained in detail through the various recipes in this book!
8

www.it-ebooks.info