This page last changed on May 03, 2010 by ggaskell.

Purpose of this Module Type

A report plugin module defines a report within JIRA. A JIRA report can display statistical information based on all elements within JIRA - e.g. issues, projects, users, issue types, etc. Reports have HTML results and (optionally) Excel results as well. These results are rendererd by Velocity templates included with the plugin. A report can also accept parameters selected by the user before running.

Configuration

The root element for the report plugin module is report. It allows the following attributes and child elements for configuration:

Attributes

Name Required Description Default
class  

The class which implements this plugin module. The class you need to provide depends on the module type. For example, Confluence theme, layout and colour-scheme modules can use classes already provided in Confluence. So you can write a theme-plugin without any Java code. But for macro and listener modules you need to write your own implementing class and include it in your plugin. See the plugin framework guide to creating plugin module instances.

The Java class of the component. The class must implement com.atlassian.jira.plugin.report.Report, but we recommend that you extend the convenience class com.atlassian.jira.plugin.report.impl.AbstractReport in your plugin.
 
key

The identifier of the plugin module. This key must be unique within the plugin where it is defined.
Sometimes, in other contexts, you may need to uniquely identify a module. Do this with the complete module key. A module with key fred in a plugin with key com.example.modules will have a complete key of com.example.modules:fred.

I.e. the identifier of the component.
N/A
i18n-name-key  

The localisation key for the human-readable name of the plugin module.

 
name  

The human-readable name of the plugin module.

I.e. the human-readable name of the component.
The plugin key.

Elements

Name Required Description
description   A human-readable description of this report module. May be specified as the value of this element for plain text or with the key attribute to use the value of a key from the i18n system.
label The user-visible name of this portlet. May be specified as the value of this element for plain text or with the key attribute to use the value of a key from the i18n system.
resource type="velocity" Used to render the report results. The results format is whatever the template can output.
resource type="18n"   A Java properties file within the plugin that specifies internationalization values.
properties   Used to generate the report's configuration parameters (see Configuring Plugins with Object Configurable Parameters for details on these properties).

Description

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 Report interface or it can extend 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 Velocity templates used to render the report. The templates include:

  • Report view - the actual report view
  • Excel view - an Excel view for the report (optional)

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;
}

Internationalisation

It is also possible to include i18n property files to allow other users to easily translate the strings used in the report for different languages.

Example

This example is taken from JIRA's internal time tracking report.

<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 containing 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 example, 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 and the internationalisation 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.

Notes

For more details, see the tutorial on creating a JIRA report.

Document generated by Confluence on Mar 27, 2011 18:53