A JIRA report can display statistical information based on all elements within JIRA - e.g. issues, projects, users, issue types, etc. The report logic collates and parses the data, which is then presented to the user as required.
With JIRA 3.0, the introduction of the plugin system aims to provide a simple point of extensibility for custom features users may wish to add to JIRA. This tutorial will describe how to create a custom report within JIRA 3.0, using this plugin interface.
The following articles provide further detailed information on writing a JIRA 3 plugin:
A Report Plugin Module Primer
In order to make a custom report available within JIRA, it is necessary to create a report plugin module. As with all plugin modules, the report plugin will consist of the following components:
- Java classes encapsulating report logic
- Resource templates for display of the report
- Plugin descriptor to enable the report module in JIRA
all contained within a single JAR file.
The Java classes include the necessary logic to retrieve the data used in configuring and displaying the report. The module class can implement the interface com.atlassian.jira.plugin.report.Report - or it can extend com.atlassian.jira.plugin.report.impl.AbstractReport. The main methods of interest are:
- generateReportHtml - generate HTML view of report
- generateReportExcel - generate Excel view of report
- getParams - retrieve the required data to be passed to the view template
- validate - validate any parameters used in configuring the report
The second component consists of templates used to render the report - Velocity templates can be used here. The templates can include:
- Report view - the actual report view
- Excel view - an Excel view for the report (if required)
The plugin system parses the atlassian-plugin.xml file for any configuration parameters associated with the report - parameters required in order to display the report. The plugin system constructs a suitable configuration screen requesting the user to specify values for these parameters.
If an Excel view template is provided, users have the ability to view and further manipulate the data through Excel. If the Excel template is provided please ensure that your report also implements the following method:
It is possible to include i18n property files also - so as to allow other users to easily translate the strings used in the report for different languages. The following report examples are fully internationalized and include default property files.
The report module descriptor is the only mandatory part of the plugin. It must be called atlassian-plugin.xml and be located in the root of the JAR file.
Here is a sample report module descriptor element:
In this sample, the report logic is encapsulated in the TimeTrackingReport Java class. The view template location is specified in the templates/plugins/jira/reports/time-tracking-report.vm directory. The internationalistaion property files are located at com.atlassian.jira.plugins.reports.timetracking. Following that, the parameters required to configure the report are specifed - in this case, the version, the sort order and a filter.
JIRA Plugin Development Kit
Maven is an ant-like build tool that downloads any specified project dependencies automatically (just one of the many features).
The JIRA Plugin Developement Kit consists of a number of examples (including the ones discussed here) to help developers extend JIRA through the plugin interface as easily as possible.
Once the development kit has been setup, you need only run the command:
to build the desired plugin. Using Maven is not a requirement - you can use ant or any other build tool, however, it will make your life a lot easier.
The following examples detail how to extend an existing sytem report and how to create a custom report. Each example is included in the JIRA Plugin Developement Kit. When compiled, the atlassian-jira-plugin-report-example-1.0.jar file includes each report and can be copied to the JIRA lib directory in order to make the reports available within the system.
Example 1 - Extending an Existing System Report
In this example, an existing system report - 'Single Level Group By Report' - is extended to display the assignee and the last updated time of the issue. The logic and view templates within JIRA are slightly modified in order to achieve this extension.
The full source of this example is included in the JIRA Plugin Developement Kit in the examples/plugin-report-sample directory - the files of interest are:
Firstly, the atlassian-plugin.xml file is created/modifed to define the new report module element:
The report definition specifies the following information:
- the class encapsulating the report logic (SingleLevelGoupByReportExtended)
- the name and description properties
- the location of the i18n files
- the parameters required to configure the report
The logic for the report is encapsulated in the class SingleLevelGroupByReportExtended (a slightly modified version of the original SingleLevelGroupByReport class within JIRA). The view template requires a manager to correctly display the last updated time for the issue - so the class passes the OutLookDateManager OutlookDate object to the velocity template:
The last updated time can now appear in the correct date/time format as configured within JIRA.
The report view template is also edited from the original to display the assignee and the last updated time for the issue:
Once the compiled JAR file is placed in the lib directory - the report is available from the report menu on the 'Browse Project' page.
Example 2 - Issue Creation Report
In this example, a custom report is coded to display a histogram of issues created over a specified time. The report will collate all issues created within a specific project over the specifed duration, subdivided by a configurable time interval.
The full source of this example is included in the JIRA Plugin Developement Kit - the files of interest are located in the example/plugin-report-sample directory:
Firstly, the atlassian-plugin.xml file is created/modified to include the new report module element:
The report module element defines that the logic is encapsulated in the class CreationReport. The name and description properties and the location of the i18n files are also specified.
In this case, the report requires four parameters to correctly display the data and are specified as follows:
- projectid - a select field specifiying the project on which the report will focus. The possible project options available are retrieved through another JIRA class - com.atlassian.jira.portal.ProjectValuesGenerator.
- startDate - a date field specifiying the start of the time period for the report.
- endDate - a date field specifiying the end of the time period for the report.
- interval - a numeric field specifiying the time interval used to divide the overall time period (this is the histogram interval).
The plugin system will construct a suitable report configuration screen - allowing the user to specify the above parameters.
The CreationReport class retrieves the parameters as specified by the user. Next, the relevant issue counts are retrieved from the system for the specified time over the specifed time interval from the specified project. The issue counts are normalised in order to produce a balanced histogram. Finally, the relevant details are passed to the velocity template.
The view template displays the histogram constructed from the data passed from the class CreationReport.
The i18n property files are also included - allowing the text strings to be internationalised for users in different locales.
The report appears within the report section on the 'Browse Project' page.
Note: There is no Excel view for this report.