Jira is a issue tracking product, developed by Atlassian. It provides bug tracking, issue tracking, and project management functions. Jira’s architecture allows developers to extend its functionalities by writing add-ons. Jira is developed using Java programming language, thus add-ons as well. When I recently started with Jira development, I had many questions and unknowns, especially because lacking of good, up to date documentation / books. After successfully coding my first Jira add-on I have answers on those beginner’s questions and also few tips and tricks that could be useful for developers entering into the Jira add-ons world.
Plugin vs Connect
Jira offers three different flavors:
- Data Center / Enterprise
Before everything else you should know what your add-on is for, since that will dictate your development.
Server version is for installation of the Jira on your own server. It’s up to you to install, configure and maintain it. But it’s good because it gives you more freedom and security (you own your own data).
Data Center is, basically, the same thing as Server, but it provides additional features – it’s a deployment option designed for high availability, performance at scale, and instant scalability when hosting your applications in your own data center. In other words, with Data Center you don’t have to worry about managing your own cluster, scalability and availability.
Cloud is a solution hosted by Atlassian and it’s basically SaaS. With this option, you don’t have to install and maintain anything, Jira is hosted and managed by them.
Regarding development of add-ons, since Server and Data center are the same they have one framework for developing: Atlassian SDK / Plugin2 and Cloud has completely different framework called Atlassian Connect.
Atlassian Connect is new thing and has very good online, up to date documentation and also I am not developing for the Cloud, so that topic is out of scope in this article. My focus here is on Jira Server Plugin development.
Jira Server version I am targeting is 7.x and online documentation is out of date and incomplete and there was no book for it. Fortunately, few days ago new book was released so we are now good to go! 🙂 Let me summarize learning resources:
- Atlassian SDK – core/common SDK for all Atlassian products
- Jira Plugin2 – plugin framework for Jira Server
- Atlassian Design Guidelines – guidelines how to design add-ons for Atlassian products, so they have their look & feel
- Atlassian UI (AUI) – JS/CSS library implementing Atlassian Design Guidelines. You will use this to make your plugin to look and feel like Jira.
- JIRA Development Cookbook (Amazon or Packtpub) – recently published book for Jira Server 7 Plugin development
- Atlassian Forum – place where you can ask questions about Atlassian products and get answers quickly
- Google – obviously 😀
Additional questions and answers you might have:
- Q: Jira is providing both Java and REST API to programmatically invoke operations, which one should I use, I guess it’s more natural to use Java API since Plugin will run in the same JVM? A: You can use both and the fact that Java API is documented only through JavaDoc and REST API is clear and well documented, you will probably end up using REST API frequently as well.
- Q: Does Atlassian University offer training for JIRA Server development? A: No.
- Q: I want to extend already existing plugin as well, not only Jira, is that possible and how? A: A plug-in which has been designed to be extended may provide an SPI or even custom module types. If SPI is not available, it depends on what you need to “extend” – if it involves just calling some code, then you can bind to the plug-in at runtime and invoke its interfaces/classes. If these are not APIs, expect your code to be broken between versions of the plug-in. Extending the UI may not be that easy, depending on the implementation. Anyhow, the best approach is to contact the author of the plugin to ask and also check license.
- Q: Is developer licence free for Jira Server? A: Yes. For QA environment also. With many plugins as well.
- Q: Can I use jQuery and other JS libraries in my plugin. A: Yes, see below.
Tips & Tricks
If you are using Atlassian SDK command line tools to create skeleton of your plugins, you will have QuickReload feature automatically configured. It allows you to quickly see/test your changes as you develop.
When you run atlas-run command in your plugin folder it will start local server and deploy Jira with QuickReload enabled. Then you make change to your code and the only thing you have to do is to rebuild the project with mvn package. As soon as the new jar is built, QuickReload will detect the change, redeploy the plugin and your changes will be visible. It works surprisingly fast.
Keeping data / settings
If you do mvn clean between atlas-run you will lose all your data and settings you created in the previous session. Solution is not to do cleaning and also not to kill server with CTRL+C, but shut down it gracefully with CTRL+D. That way you will always have your data/settings/plugins/etc waiting for you next time.
You can use jQuery in your plugin, but instead of $ notation you will have to use AJS.$ notation and that’s it!
It is smart to make naming conventions for keys/ids/etc in atlassian-plugin.xml not to clash with other plugins. We can use something similar like Java packages naming convention. Example of this:
You can use JS / CSS / image/ etc files in your plugin but not by importing them like usual in your html / velocity / jsp files. Instead you have to define it like this in atlassian-plugin.xml:
Then use defined context in Velocity templates like this:
That will include all your resources.
In case you want to use external resources, you can just use it as usual.
Jira is automatically caching all your web resources and one effect of this is that your JS/CS changes won’t be reflected unless you rename the file. Since Jira is caching based on the web resource key, solution is to make that key dynamic on every build.
First, add this to your POM:
Then change your atlassian-plugin.xml like this:
And then use it normally in Velocity template:
On every quick reload / build key will change and Jira will update the resource.
Standard / Core AUI components are included automatically, but some components don’t belong to the core and they are not included. On every component page in the docs, it clearly stated and if that is the case you have yo use component key (also in component docs) to additionally include the component:
If you want to hide some elements depending on some conditions, let’s say hide menu for users that aren’t logged in, you have to do something like this in atlassian-plugin.xml:
Note from example above that you can either write your own conditions, but in some cases they already exist in Jira 😉
Protecting actions / pages
It’s not enough to hide the link to the action/page, you also have to protect it, so if user manually try to hit it, to get forwarded to the login page if not logged in, for example:
This is just the beginning of Jira Server Plugin development and my first article about this topic. I will be writing more articles on Jira Development as I progress with the matter. Stay tuned! 😉