How to create a JIRA Report

Overview

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:

• JIRA Plugin Guide,
• How to create a new Custom Field Type
• Vincent Massol's tutorial

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.

Report Logic

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

Resource Templates

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:

public boolean isExcelViewSupported()
{
return true;
}

Other Resources

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.

Plugin Descriptor

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:

<!--
	The "class" attribute here defines the actual report object.
	This is an implementation of com.atlassian.jira.plugin.report.Report.
	There is also an abstract implementation which may be useful at
	com.atlassian.jira.plugin.report.impl.AbstractReport.
-->
<report key="time-tracking" name="Time Tracking Report"
	class="com.atlassian.jira.plugin.report.impl.TimeTrackingReport">
<description key="report.timetracking.description">
	This report shows the time tracking details for a specific project.
</description>

<!-- the label of this report, which the user will use to select it -->
<label key="report.timetracking.label" />

<!-- the 'view' template is used to render the HTML result -->
<resource type="velocity" name="view"
	location="templates/plugins/jira/reports/time-tracking-report.vm" />
<!--
	The 'excel' template is used to render an Excel result.
	The 'Excel view' of the report will only be visible if
	this template exists for the plugin module
-->
<resource type="velocity" name="excel"
	location="templates/plugins/jira/reports/time-tracking-report-excel.vm" />

<!-- this is a .properties file containin the i18n keys for this report -->
<resource type="i18n" name="i18n"
	location="com.atlassian.jira.plugins.reports.timetracking" />

<!-- the properties of this report which the user must select before running it -->
<properties>
	<property>
		<key>versionId</key>
		<name>common.concepts.version</name>
		<description>report.timetracking.version.description</description>
		<!-- valid types are string, text, long, select, date -->
		<type>select</type>
		<!-- the values generator is a class which will
		generate values for this select list -->
		<values class="com.atlassian.jira.portal.VersionOptionalValuesGenerator"/>
	</property>
	<property>
		<key>sortingOrder</key>
		<name>report.timetracking.sortingorder</name>
		<description>report.timetracking.sortingorder.description</description>
		<type>select</type>
		<values class="com.atlassian.jira.portal.SortingValuesGenerator"/>
	</property>
	<property>
		<key>completedFilter</key>
		<name>report.timetracking.filter</name>
		<description>report.timetracking.filter.description</description>
		<type>select</type>
		<values class="com.atlassian.jira.portal.FilterValuesGenerator"/>
	</property>
</properties>
</report>

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

You can choose to develop your plugins however you wish. However, we recommend using Maven 1.0 and the 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:

maven jar

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.

Examples

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:

• src/etc/templates/groupreport/single-groupby-reportextended.vm
• src/etc/atlassian_plugins.xml
• src/etc/com/atlassian/jira/plugin/reports/example/singlelevelgroup/singlelevelgroup_report.properties
• src/java/com/atlassian/jira/plugin/report/example/singlelevelgroup/SingleLevelGroupByReportExtended.java

Firstly, the atlassian-plugin.xml file is created/modifed to define the new report module element:

<!-- An simple example of customising an exisiting report -
	adding the admin and updated date of an issue to the template -->
<report key="singlelevelgroupbyextended" name="Example: Group By Report Extended"
	class="com.atlassian.jira.plugin.report.example.singlelevelgroup.SingleLevelGroupByReport">
<description key="report.singlelevelgroupby.description">i18n description</description>
<resource type="velocity" name="view"
	location="templates/groupreport/single-groupby-report-extended.vm" />
<resource type="i18n" name="i18n"
	location="com.atlassian.jira.plugin.reports.example.singlelevelgroup.singlelevelgroup_report" />
<label key="report.singlelevelgroupby.label.extended" />
<properties>
	<property>
		<key>filterid</key>
		<name>report.singlelevelgroupby.filterId</name>
		<description>report.singlelevelgroupby.filterId.description</description>
		<type>select</type>
		<values class="com.atlassian.jira.portal.SearchRequestValuesGenerator"/>
	</property>
	<property>
		<key>mapper</key>
		<name>report.singlelevelgroupby.mapper</name>
		<description>report.singlelevelgroupby.mapper.description</description>
		<type>select</type>
		<values class="com.atlassian.jira.issue.statistics.FilterStatisticsValuesGenerator"/>
	</property>
</properties>
</report>

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:

...
try
{
I18nHelper i18n = new I18nBean(authenticationContext.getUser());

startingParams = EasyMap.build("action", action,
"statsGroup", getOptions(request, authenticationContext.getUser(), mapper),
"searchRequest", request, "mapperType", mapperName, "customFieldManager", customFieldManager, "portlet", this);

startingParams.put("outlookDate", ManagerFactory.getOutlookDateManager().getOutlookDate(authenticationContext.getLocale()));

return descriptor.getHtml("view", startingParams);
}
...

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:

...
<td>$issue.getString('assignee')</td>
<td>$outlookDate.format($issue.getTimestamp('updated'))</td>
...

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:

• src/etc/templates/creationreport/issuecreation-report.vm
• src/etc/atlassian_plugins.xml
• src/etc/com/atlassian/jira/plugin/reports/example/issuecreation/issue_creation_report.properties
• src/java/com/atlassian/jira/plugin/report/example/creationreport/CreationReport.java

Firstly, the atlassian-plugin.xml file is created/modified to include the new report module element:

<!-- An 'Issue Creation' Report - displays a histogram of issue create within a
	specifed project over a specified time -->
<report key="issuecreationreport" name="Example: Issue Creation Report"
	class="com.atlassian.jira.plugin.report.example.creationreport.CreationReport">
<description key="report.issuecreation.description">i18n description</description>
<label key="report.issuecreation.label" />

<resource type="velocity" name="view"
	location="templates/creationreport/issuecreation-report.vm" />
<resource type="i18n" name="i18n"
	location="com.atlassian.jira.plugin.reports.example.issuecreation.issuecreation_report" />

<properties>
	<property>
		<key>projectid</key>
		<name>report.issuecreation.projectid.name</name>
		<description>report.issuecreation.projectid.description</description>
		<type>select</type>
		<values class="com.atlassian.jira.portal.ProjectValuesGenerator"/>
	</property>
	<property>
		<key>startDate</key>
		<name>report.issuecreation.startdate</name>
		<description>report.issuecreation.startdate.description</description>
		<type>date</type>
	</property>
	<property>
		<key>endDate</key>
		<name>report.issuecreation.enddate</name>
		<description>report.issuecreation.enddate.description</description>
		<type>date</type>
	</property>
	<property>
		<key>interval</key>
		<name>report.issuecreation.interval</name>
		<description>report.issuecreation.interval.description</description>
		<type>long</type>
		<default>3</default>
	</property>
</properties>
</report>

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.

Report Logic

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.

Resources

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.