How Do We Develop Jira Plugins
Jira is a popular issue tracking tool and is also used in many businesses as a business process management system (BPM). Sure, there are more suitable tools like jBPM, but Jira is much more user-friendly. And even though it's less feature-rich regarding BPM options, it can be easily extended using plugins written in Java language. It's a big benefit as we can do almost everything with the help of plugins. But there is also a disadvantage that customer can demand to use Jira with plugins even though some other tool could be more suitable. Believe it or not, even Jira has its limits.
Developing a plugin is like building a house from Lego blocks (modules). The new module can be created manually but it's easier to use the Atlassian SDK command atlas-create-jira-plugin-module. It lists all available modules and the result of the command depends on its type. For example, Workflow Condition will make an entry in atlassian-plugin.xml, in a properties file and it will create a new Java class with condition definition and factory class. Of course, these can be created also by hand. The atlassian-plugin.xml is a very important file that holds module definitions and configuration. In the Workflow Condition case, it will hold a full class name of the condition. If something isn't in atlassian-plugin.xml, your plugin doesn't know about it.
It would be useless to go through each available module. Instead, I will name a few of them which we use very often.
Workflow Condition - is used to restrict a transition. It is executed each time the issue is viewed and is in status with a restricted transition. If the condition evaluates to false, no transition button will be shown.
Workflow Validator - is also used to restrict a transition, but it's executed only when the transition is about to happen (when a user clicks on the transition button). The Validator class will just execute and you have to throw an exception if the validation process isn't successful.
Workflow Post Function - executes after the transition. We use them all the time to change assignee, track times, assign due dates, send notifications and many more.
Servlet - handles get and post requests. We use them often as a backend for different pages (administration, dashboards, subtask bulk creation). But not all the time is server accompanied by a page.
Web Item - it's usually in our case a button with a link tied to a servlet. It can lead the user to some page or execute an action (we use them for custom reviews). The position of the item is defined by section parameter and viewing can be restricted by condition tag, which references custom class. This class has to extend AbstractIssueWebCondition and implement shouldDisplay method. Since our plugins share space on Jira with different other projects, it's important to hide buttons for users who don't use them.
Web Panel - defines a panel with custom content. It's especially useful when you want to show some issue related information but you don't want to use a whole page.
Velocity is a server-side template language. It is used to pass and call Java objects in HTML. For example, one of our dashboards is an HTML page with a table and Velocity is used to generate table rows with values in a loop. The easiest way how to create a custom page is to create a servlet that renders provided HTML page with passed parameters using TemplateRenderer class.
Map<String, Object> params = new HashMap<String, Object>();
We developed several Jira plugins implementing various internal business processes and extended the Jira in many different ways. Let's go through the systems and features which are possible to do using plugins.
Process installer available from administrator page which is able to install all necessary workflows, screens and custom fields to fresh Jira instance. But these are only the main elements which are created. The installer also handles custom Condition/Validator/Post Function assignment, setup of permission schemes, security schemes, and many more things.
The feature is very useful for local development but it also allows us to quickly create testing Jira instance with process anytime we want. One small disadvantage is that each change in workflow needs to be reflected also in the installer. The development takes more time and if this is forgotten, workflow in a plugin can quickly become dated which leads to confusion why testing instance acts differently than production.
Process initializer is implemented as a custom administration page which calls REST endpoint responsible for executing custom initialization class.
By default, the Jira issue has only Assignee and Reporter role. In a complex business process, there can be multiple roles. Each role can even have multiple users and this asks for custom development. Our plugins have administration pages where plugin administrator can assign people to different roles per each Jira project. When an issue is created, custom Post Function assigns these peoples to the specific issue.
During the workflow, the plugin takes users from different roles and swaps the Assignee of issue. The assignee cannot be changed manually. Very often, only specific roles can move issue to the next status so we can allow the assignee to do it and let the plugin handle swapping.
It's a common case to track the time of statuses. Managers want to know how long each stage took in order to optimize the process and have a basic knowledge of time demands. Another common case is to track overdue hours. We simply do it using Workflow Post Function which is saving current time with date to custom Finished field. We also fill the Started date of the new status and calculate the due date. All dates are then used by the notification system, in different reports and dashboards.
Dashboards and reports
Even though specialized reporting tools can be used on exported issues, customers usually want to see basic reports right in Jira. Plugins we developed have 3 different types of dashboards.
Jira dashboards - these are standard Jira dashboards manually created during the first plugin installation. The first gadget usually shows important links (to custom dashboards, documentation or to support page) and the following ones are Filter Results. But in general, everything available in Jira can be done on these dashboards. A disadvantage is that only the dashboard creator can edit his own dashboards.
Static custom dashboard - if a simple read-only report is needed, a static page backed by Servlet is usually sufficient. In our case, we take all process issues and group them by defined criteria. Some parameters are summed and shown in tables. For convenient reasons, page also contains a filter where user can filter issues by available field values. Only standard Atlassian UI components are used on the page and usage of filter requires a page refresh. This is the reason why I refer to the dashboard as static. That might be a disadvantage, but on the other hand, this type of dashboard can be developed quickly even by backend developers.
Users want to be informed when something happens with the Jira issue they are in charge of. Sometimes, multiple user groups have to be informed. We came to the conclusion that basic Jira notifications aren't enough so we introduced two notification concepts. Both of them are using our own mail service. But it's mostly a wrapper which fills email templates and uses SMTPMailServer component to do actual sending of emails.
Transition notification - is a parametrized Workflow Post Function. It's possible to define an email notification template and receiving roles. Users on these roles will receive the email with a notification when the transition happens. The advantage of this concept is, that notifications can be easily added and stacked during the workflow definition. On the other hand, there is no centralized notification place so in order to do some change, we need to find the exact transition in the workflow diagram and publish the updated workflow.
Periodic notification - is sent by scheduled service using Cron job. The exact time of execution is defined in a property file. We use this to send overdue notifications or notifications when the deadline is approaching. This is a useful concept when you need to send many emails periodically and maybe do some issue processing. Service can execute during the night or morning when your Jira instance probably isn't under heavy load.
Calculated fields on demand
At some point in the workflow, several users have to review the issue. When all reviews are done, the issue will go to the next status. This cannot be done by the basic transition button. We fill review date when a review is done (custom button backed by Servlet) and each time we check if all is done. If so, the applied Workflow Condition "All Reviews Are Done" is true and the issue is automatically transitioned to the next status by Servlet. There is no visible transition button due to Workflow Condition and everything is handled only by custom buttons.
It's possible to develop many more interesting systems using plugins. I named only a few general concepts, but our plugins are way more integrated into the business processes. It's possible just to translate customer's business processes to Jira, but that is usually not the best solution since Jira can automate different parts of the workflow. CloseIT has a broad consulting experience. After a dialog with a client, we can suggest how to improve and automate parts of the process which can be automated. And what to do to get the most out of Jira.
Author: Luděk Novotný