What is the transition in Jira

Extending JIRA with plugins - overview and possibilities

JIRA is a project, process and product management tool from Atlassian that is widely used in agile software development, but has long been used beyond the IT department. Over 70% of the Fortune 100 companies use JIRA. If the extensive configuration options are exhausted, JIRA can be further adapted to your own needs thanks to its expandable architecture based on the Atlassian plugin framework. The bandwidth of plugins ranges from extensions for workflows to adaptations of the user interface to the integration of your own web applications and services. The article describes the architecture of JIRA, gives an overview of the possibilities for extensions and is intended to facilitate the introduction to the Atlassian plugin framework.


JIRA is a popular tool in software development. It has long since left its original function of managing errors / bugs and tasks far behind. It supports agile project management according to Scrum and Kanban, but it is also used for general task management and the implementation of other business processes. Last but not least, it is also suitable for product management, especially in connection with the Confluence collaboration tool.

Over 35,000 customers worldwide use JIRA, including 70% of the Fortune 100 companies.

A decisive success factor of JIRA (and Atlassian products in general) is the countless possibilities to adapt and expand the software. In addition to smaller "hacks" for adapting the user interface (eg loading Java scripts via announcement banners or custom fields, modifying the original HTML templates) and scripts for data imports, exports and workflow behavior, there is a robust foundation with open and expandable Architecture.

There are already numerous add-ons for expanding or adapting workflows, some of which are, however, relatively expensive compared to the price of the JIRA basic installation and the license of the currently freely available add-ons should be checked carefully, as it happens that an add -On is initially freely available, but suddenly has to be paid for. This is what happened, for example, with the popular “Misc Workflow Extensions” add-on for adapting workflows.

Atlassian uses the terms “add-on” and “plug-in” as synonyms, in the following these are also referred to as extensions.

Plugin generations

A plugin is a package consisting of source code, resources and configuration files. The following plug-in generations can be distinguished in the Atlassian environment:

  • “Version 1” plugins. The first generation of plugins ran directly in the JIRA core system and used the same classloader. Each Atlassian product had very different expansion options.
  • “Version 2” plugins (since JIRA 4). The second generation of plugins runs in an OSGi container. This means that each plugin has its own classloader, and dependencies can be managed via OSGi. All Atlassian products use the same foundation.
  • “Speakeasy” plugins (from JIRA 4.3). This type of plugin is based purely on JavaScript / HTML. The aim is / was to simplify the development process for simple extensions. Unfortunately, the project has not been further developed since 2013. Use in publicly accessible JIRA instances is also still not recommended.
  • “Connect“ plugins (since 03/2014, for JIRA OnDemand). Extensions for the JIRA Cloud version can be developed with the Connect Framework. These can then only be operated for them. Simply put, Connect Plugins are web applications that communicate with JIRA via REST interfaces. This means that they can be developed and operated completely independently of JIRA, but they are also dependent on the available REST interfaces and naturally cannot access the numerous JAVA APIs like a version 2 plug-in.

This article deals with the Version 2 plugins. They are currently the first choice when using a self-hosted JIRA server.

Version 2 extensions are, as mentioned, developed, installed and operated separately from the core system. They can be installed and uninstalled during operation (thanks to OSGi).

The Atlassian Plugin Framework (APF) makes it possible to integrate seamlessly into the JIRA architecture and to exchange or expand almost any component. JIRA itself is de facto just a set of plugins for the Atlassian framework.

Atlassian maintains an open source culture and so it is a great advantage that you have both insight into the libraries used by Atlassian and full access to the source code of JIRA. After purchasing a license, it can be downloaded from my.atlassian.com.

The following is a brief description of how JIRA works, what options there are for customization and where extensions could make sense.

Image JIRA architecture, source: Atlassian, own adaptation.

JIRA issues

The heart of JIRA are the so-called Issuesthat defined a Workflow run through. In German these are tickets (or processes) that follow a workflow. You can freely define which fields a ticket has. The individual fields have different types, e.g. they allow free text entries, various number formats, date entries via a calendar or a predefined selection list whose values ​​are configured in the administration area of ​​JIRA. Own formats or types can be added as an extension. This is explained in more detail in the section “Custom types for custom fields”.

Hacking vs. Extending

In many cases, JIRA allows HTML / JavaScript to be entered in the administrative area. For example, a globally visible banner can provide users with important information, such as upcoming updates. The description of custom fields can also contain HTML / Javascript.

In both cases, JavaScript can be smuggled into the application.

Since JIRA 6.2 the possibilities of getting JavaScript code into the application in this way have been restricted.

Although these options exist, this is not recommended, especially for larger installations:

  • Scripts must / are often developed or tested directly in the productive JIRA instance, which is error-prone and difficult to maintain.
  • Scripts are stored in text fields and changes must be maintained manually.
  • Missing versioning: It is not clear with which versions of JIRA a script is compatible, nor which version of the script is “installed”.
  • User interface hacks can cause problems with JIRA updates.
  • No overview for administrators of where scripts were smuggled in and how.
  • High manual test effort due to a lack of test automation.
  • As of JIRA 6.2, some of these options are disabled by default.

For administrative activities, one-off exports or for prototyping, the Script Runner add-on should be mentioned at this point. The ability to execute your own Groovy code makes it very powerful and can be used for productive hacks (Scripted Fields, Scripted JQL Functions).

In contrast, extensions can be installed and uninstalled cleanly. They follow a life cycle in development as well as in production, can be properly managed using a version control system, and packaged and published using a maven-based build tool (more on this in the next section). This enables structured - often automated testing.

Update: At this point a note on our 4-part blog series: Agile testing of JIRA plugins (part 1), wired tests (part 2), system tests (part 3), CI server integration and test coverage (part 4).

In addition, plugins can be explicitly adapted individually to new versions of JIRA and thus become update-proof.

Develop your own components

The official English developer documentation offers a very good introduction to plugin development. The Atlassian Framework essentially consists of the following components:

  • A Maven-based build tool: AMPS.
  • Java APIs and libraries to access Atlassian functions and product-specific functions. For a complete overview see link.
  • A JavaScript Framework (AJS)
  • An HTML / CSS framework for the development of user interfaces: AUI.
  • Various Atlassian add-ons, in particular
    • The Universal Plugin Manager (UPM): A plugin that enables plugins to be managed. (sounds strange, but that's how it is)
    • FastDev: reinstalls the plugin that is currently being developed when changes are made to the source code, without having to reload the entire container (i.e. the JIRA application).

AMPS, the Atlassian Maven PlugIn System, comes with a number of command line commands that support the development of your own components. The Atlassian maven commands offer support for the entire plugin development life cycle, including start-up help for new modules by generating the required source code and configuration files.

A simple life cycle for developing a JIRA plugin could look like this:

> atlas-create-jira-plugin

Creates the basic structure for the plugin: directories and files are created. Some sample code will be generated to get you started.

> atlas-create-jira-plugin-module

Creates a JIRA module. Updates the plugin configuration and creates appropriate files and directories depending on the module.

> atlas-run

Starts a developer JIRA instance and loads the plug-in located in the current directory.

> atlas-package

Packages the plugin as a shippable artifact (jar)

Atlassian-plugin.xml / Add-On Descriptor

The linchpin of an Atlassian plugin is the so-called descriptor: The XML configuration file “atlassian-plugin.xml”. The plug-in is formally described in this file: Basic information such as the name and a unique key (plug-in key) are stored. In addition, resources, dependencies and components are defined here.

Add-on modules to expand JIRA

There are over 30 module types to choose from for JIRA. These can be divided into the following categories:

  • Extension of the user interface (Web Item, Web Panel, Web Panel Renderer, Web Section, Component Tab Panel, Issue Tab Panel, Project Tab Panel, Version Tab Panel, Template Context Item, User Format Plugin, User Profile Plugin)
  • Web resources (Web Resource, Web Resource Transformer, Downloadable Plugin Resource)
  • Workflow extensions (Workflow Condition, Workflow Post Function, Workflow Validator)
  • Own service classes (Component, Component Import, Module Type)
  • Extensions for new custom fields (Custom Field, Custom Field Searcher)
  • Gadgets (Gadget Plugin Module)
  • Web interfaces (REST Plugin Module, RPC Endpoint Plugin)
  • Reports and search results (Report, Search Request View)
  • Own web apps, pages and servlets (Webwork Plugin, Servlet, Servlet Filter, Servlet Context Listener, Servlet Context Parameter, URL Routing Plugin)
  • JQL extensions (JQL function)
  • Keyboard shortcuts (Keyboard shortcut)
  • Licensing support

There are also other ways to expand the software. The above list should, however, provide a good overview. In addition to the official developer documentation, the JIRA source code is a good source of documentation for plugin development and provides an insight into how it works. In the module "jira-reference-plugin“Most of the modules are implemented as examples.

JIRA workflows and workflow functions

Each JIRA ticket is assigned to a specific workflow. A workflow is characterized by different states (Statuses) and transitions between these states (so-called. Transitions).

The change between different states in a workflow is linked to

  • Conditions
  • Validators
  • Post functions
  • Trigger

Workflows are a central component of JIRA and should be precisely adapted to the company processes. Own workflow functions lead to the greatest possible flexibility and automation of work processes.

Image JIRA workflow functions.

A precondition (“Condition”) is evaluated before a transition is even given, e.g. from status “open” to status “completed”. In other words, a corresponding button to carry out a transition is only displayed to the user if all the preconditions are met. A typical use of a precondition is to check whether the user has a certain authorization.

If all the preconditions are met, you can press Validators (“Validators” / also called confirmations) are checked to see whether the entries are correct. If a validator returns an error, this is displayed to the user and the transition is not carried out.

If the preconditions and validators have been passed, they come Follow-up functions (“Post-Functions”) are used. There are a number of standard follow-up functions that are executed with every transition, e.g. the status of the ticket is updated and persisted in the database or a comment by the user is added to the ticket. In addition, JIRA brings a number of optional follow-up functions, e.g. to assign the issue to a user, to set the value of a field or to trigger a "webhook".

A simple use case of a post function is, for example, to set a ticket field to a certain value or to assign the ticket to a certain person.

Webhooks and triggers can be used to notify other applications of workflow events.

A Webhook is an HTTP post call of a specific URL, triggered by an event (e.g. new ticket created). A JSON object of the ticket for which the event was triggered is transmitted. Webhooks can be triggered by general events, but also - as already mentioned - by a post function. Another web application can be notified of certain events in this way.

A new kind of workflow function since JIRA 6.3.3 Trigger. In contrast to webhooks, they allow external events from other applications to be used to control workflows in JIRA. Triggers are currently offered for Stash, FishEye / Crucible, Bitbucket, and GitHub. A common use case is to change the status of a ticket at an event. For example, creating a development branch in Bitbucket / Github can transfer a ticket of the same name to the status “In progress”. There is currently no information available about the development of our own triggers.

Adaptation and expansion of the user interface

The user interface of JIRA is highly configurable and can be expanded with so-called "web fragments". The add-on module types "web items", "web sections" and "web panels" offer options for clean expansion. This means that menus can be supplemented with their own menu items, and new buttons, tabs, fields and sections can be inserted in detail views.

JIRA issue detail view, in red a selection of sections that can be added via web items / sections.

Web resources

Static files such as JavaScript, CSS stylesheets and images are defined in the atlassian-plugin.xml file and these can then be used in the Java / JavaScript code or in a template via a key. There is also the option of transforming the files before delivery. One example of this is the i18n Transformer: certain terms in the JavaScript source text are translated or internationalized before delivery.

At the beginning it was mentioned how one can integrate one's own JavaScript into JIRA via “hacks”. The better alternative here are web resources. The “web resource context” can be used to specify in which areas of JIRA a resource should be loaded. For example, additional JavaScript can be loaded via the context “jira.view.issue” in the ticket detail view. Atlassian provides a list of all possible contexts. Even though there is no update security here either, this approach still offers the advantages of plugins compared to the hacks mentioned at the beginning.

Own types for custom fields

As already mentioned at the beginning, there are predefined fields as well as user-defined fields for tickets. A user-defined field always has a certain type, e.g. for entering numbers, free text, entering dates or a selection list with users. If the predefined types are not sufficient, you can develop your own (so-called "custom field types"). A simple example that is not supplied by JIRA is the type “integer” or “percentage” (only floating point numbers are offered out-of-the-box). Another area of ​​application is the display of lists with dynamic content. This content can e.g. be provided by internal services. E.g.a list of departments can be queried in order to assign a ticket to a department. Complex cascading lists are also a good use case. For the use of JIRA in an automotive company, for example, a process should be created which, among other things, also enables the selection of a vehicle model and a sub-version based on it. The data for this could be obtained from the internal ERP system via an interface.

Own types for user-defined fields offer extensive possibilities to extend forms.

Can be mapped via configurationExtension (custom field types) necessary
Simple formats such as dates or numbers. Simple selection lists.Special formats, e.g. serial numbers, article numbers.
Selection lists from external database / web services depending on other fields.

Table: Comparison of the possibilities of configuration and own types for custom fields.


Reports are ad hoc statistics. They are mostly project-related and allow data to be presented in aggregated or enriched form based on the tickets of a project. JIRA brings some (a few) reports in its standard version. This includes the report on the “Average Age of Tickets”, “Created vs. Solved Tickets” and a few more.

The reports provided quickly reach their limits. An extension makes perfect sense here. The add-on module "Report" is specified in the file atlassian-plugin.xml and typically contains:

  • Name, unique key and description (like all add-ons)
  • Reference to the Java class that generates the report. (This implements the interface report (link!) Or is derived from the class AbstractReport (link!))
  • Parameters that the user can enter
  • Template for presentation in HTML format (mostly Velocity)
  • (optional) Template for presentation as Excel. This is essentially a simple table. Comprehensive Excel reports are only possible with additional effort, but are quite feasible.

JQL, search results and filters

An important component of JIRA is the ticket search. A simple mask allows simple search results to be defined by selection, e.g. to list all tickets with a certain status in a certain project.

With the help of the JIRA Query Language (JQL, based on the database query language SQL), complex queries can also be defined.

The expression that is searched for (operand) can be a defined value (e.g. project “Mars 2030”) or a function. JQL supports a number of functions, e.g. currentUser () returns the currently logged in user, or watchedIssues () a list of the observed processes of the logged in user.

An example of a JQL query: We are looking for processes in the Mars 2030 project that are assigned to “mario” and have been moved from the status “done” to the status “closed” by the currently logged in user:

project = "Mars 2030" and assignee in ("mario") and status changed BY currentUser () FROM Done to Closed

Own JQL functions can be implemented with the module type “JQL Function”. For example, a function issuesWithSubtasks (3) could return all tickets for which 3 sub-tickets have been created.

Search queries can be saved as “filters”. On the one hand, you can quickly run the query again yourself at any time, but you can also share filters with other people and subscribe to the filters by e-mail, e.g. to receive a daily list of closed tickets.

There are various out-of-the-box options for displaying the search results, e.g. an HTML list view, PDF, Word, Excel, a print view or even RSS. The HTML view is highly configurable, whereas the other options are significantly limited in their configuration options.

Own formats can be implemented as an extension with a plug-in of the type “search request view”. For example, a customized PDF view can be developed or a special XML format can be returned as a result.


Dashboards play a central role in JIRA. They are customizable overview pages that are intended to give the user a quick overview of projects, tickets, etc. In addition to the system dashboard predefined by the administrator, a user's home page is usually his personal or favorite dashboard. A dashboard consists of one or more gadgets; these show e.g. tickets that are assigned to the user or diagrams for statistical information of a project.

Gadgets can be freely combined and thus allow highly personalized views to be defined for different purposes.

Typical JIRA gadgets are:

  • the activity stream: display of activities in a single or all projects
  • Tickets assigned to me, created and monitored by me
  • Diagrams showing the average age of tickets, number of tickets created vs. completed tickets
  • Filter results (saved searches of tickets)
  • Current information and useful links, maintained by the JIRA administration.

The development of your own gadgets makes it possible to bring information of any kind to dashboards. This can be JIRA-internal data, external data or a combination of internal and external data.

Atlassian gadgets are based on Google+ gadgets or open social gadgets and are developed in JavaScript / HTML. The data is usually loaded via a REST web service.

A typical gadget plugin includes:

  • An XML configuration file ("gadget.xml")
  • The Atlassian JavaScript Framework (AJS)
  • Integrated web resources: JavaScript, HTML templates and CSS (see also section Web resources)
  • REST services that deliver data.

Although it is possible to develop gadgets "stand-alone", you lose support from the AJS framework and other convenience functions. It is therefore advisable to pack gadgets in an “Atlassian plugin”.

Own REST interfaces

The web interfaces are an important module of a web application. JIRA uses REST-based interfaces here. It provides a variety of functions for reading data from JIRA, configuring JIRA or writing data. If this is not enough, you can also lend a hand here and develop additional REST modules. Like all other modules, this is also defined in the atlassian-plugin.xml and is based on JAX-RS or Jersey, and JAXB is used for converting Java objects to XML / JSON.

Own web apps in JIRA

If you want to implement completely new functionality in JIRA or to integrate your own existing WebApp, you can fall back on the plug-in modules “Web Work Actions” and “Active Objects”. In addition, servlets or your own frameworks can of course be used.

The Web Work Actions plugin module offers an easy way to develop your own pages or WebApps in JIRA. An “action” class is defined that responds to a specific URL path. A method then “fills” a Velocity template, renders it and the browser can then display it.

The interaction with the JIRA database is implemented via “Active Objects” (AO). This ORM framework follows the “active record pattern” with the aim of enabling easy interaction with the database. The objects or tables are defined as classes that are supported by the class Entity be derived (or RawEntity to implement). The framework takes care of the creation of the table and possible changes to the schema. Indeed, the framework does some of the work for the developer and successfully abstracts the database.


In summary, one can say that the expansion options of JIRA are very extensive. The development of plugins with the Atlassian framework is developer-friendly and relatively well documented. A major advantage in development is the availability of the JIRA source code and the reference implementation of the individual plugin modules.

Thanks to OSGi, the plugins are clearly separated from one another and can still communicate with one another. Communication with the Atlassian core system and JIRA is possible via a REST API or via Java APIs.

In the future, it is to be expected that JIRA or Atlassian will penetrate further core processes of companies. This is done, for example, with Atlassian's own “Service Desk” plug-in, which maps the classic IT support process by combining a portal for reporting incidents with the management and processing of the tickets reported in JIRA.

For future plugin generations, it remains to be seen how the Atlassian Connect Framework will develop and what a possible version 3 for JIRA Server plugins will look like.