This tutorial applies to JIRA 5.0 and later.
Level of experience:
This is an advanced tutorial. You should have completed at least one intermediate tutorial before working through this tutorial. See the list of tutorials in DAC.
It should take you approximately 1 hour to complete this tutorial.
On this page:
- Overview of the tutorial
- Step 1. Create the Plugin Project
- Step 2. Review and tweak the generated stub code
- Step 3. Add the plugin modules
- Step 4. Add module properties
- Step 5. Write the Single Level Group By Extended report code
- Step 6. Create the view template for the Single Level Group By report
- Step 7. Start up JIRA and try the report
- Step 8. Code the Creation Report
- Step 9. Develop the Creation Report UI
- Step 10. View the finished product
- Next Steps
Overview of the tutorial
This tutorial shows you how to create custom JIRA reports. In this tutorial, you'll add two reports:
- Single Level Group By Extended report
- Issue Creation report
The Creation Report displays a histogram of issues created over a specified time and broken into certain intervals of time.
The Single Level Group By Extended report builds on an existing report in JIRA. The existing report looks like this:
When you're done, you'll have a new report that looks like this:
Notice the assignee and last modified date in the output.
Your completed plugin will consist of the following components:
- Java classes encapsulating the plugin logic.
- Resources for display of the plugin user interface (UI).
- A plugin descriptor to present the plugin UI in JIRA.
When you have finished, all these components will be packaged in a single JAR file.
To complete this tutorial, you need to know the following:
- The basics of Java development: classes, interfaces, methods, how to use the compiler, and so on.
- How to create an Atlassian plugin project using the Atlassian Plugin SDK.
- The basics of using and administering JIRA.
- This tutorial also involves creating Apache Velocity templates. To extend the tutorial code, you should have a good handle on how Velocity templates work.
We encourage you to work through this tutorial. If you want to skip ahead or check your work when you are done, you can find the plugin source code on Atlassian Bitbucket. Bitbucket serves a public Git repository containing the tutorial's code. To clone the repository, issue the following command:
Alternatively, you can download the source using the Downloads page here: https://bitbucket.org/atlassian_tutorial/jira-report-plugin
Step 1. Create the Plugin Project
In this step, you'll use the Atlassian Plugin SDK to generate the scaffolding for your plugin project. The Atlassian Plugin SDK automates much of the work of plugin development for you. It includes commands for creating a plugin and adding modules to the plugin.
- If you have not already set up the Atlassian Plugin SDK, do that now: Set up the Atlassian Plugin SDK and Build a Project.
In the directory where you want to put the plugin project, enter the following SDK command:
- Choose 1 for JIRA 5 when asked which version of JIRA you want to create the plugin for.
As prompted, enter the following information to identify your plugin:
- Confirm your entries when prompted.
The SDK finishes up and generates a directory for you with the initial project files, including a POM (Project Object Model definition file), stub source code, and resources.
Step 2. Review and tweak the generated stub code
It's a good idea to familiarise yourself with the project configuration file, known as the POM (Project Object Model definition file), and resource files. In this section, you will review and tweak the
pom.xml file and the plugin descriptor file. Open your plugin project in your favorite IDE and follow along in the next sections.
Add plugin metadata to the POM
The POM is located at the root of your project and declares the project dependencies and other information. Add metadata about your plugin and your company or organisation as follows:
- Edit the
pom.xmlfile in the root folder of your plugin.
Add your company or organization name and website to the
Update the project
descriptionelement as follows:
- Remove the commenting from around the
dependencyelement for the
jira-coreartifact, including it in your project.
This tutorial extends an existing JIRA report that relies on APIs in the JIRA core package. So while you normally won't need to do this, you do for this tutorial.
Save and close the file.
Review the generated plugin descriptor
Your stub code contains a plugin descriptor file
atlassian-plugin.xml. This is an XML file that identifies the plugin to the host application (JIRA) and defines the required plugin functionality. Open the descriptor file. You can find it under the
src/main/resources directory of your project home.
You should see something like this (comments removed):
Step 3. Add the plugin modules
Now you will use the plugin module generator (another
atlas command) to generate the stub code for modules for the plugin. For your modules, add two report modules as follows:
- Open a command window and go to the plugin root folder (where the
- Enter the number for the
As prompted, enter the following:
Enter New Classname
Nfor Show Advanced Setup.
Yfor Add Another Plugin Module.
- Again enter the number for the
Enter the following:
Enter New Classname
Nfor Show Advanced Setup.
Nfor Add Another Plugin Module.
Confirm your choices.
The SDK generates the code files for the modules, and adds them to the plugin descriptor. It also adds other resources, such as Velocity files and i18n resource files.
Step 4. Add module properties
Properties are the configurable fields that the plugin exposes in the JIRA UI. We'll add a few properties to the module definition:
Open the file
propertieselement under the Single Level Group By Report Extended module and replace the default
propertyelements it contains with these two new ones:
We're adding two new properties, a filter picker and a selector for the statistics type by which to group the result.
Similarly, uncomment and replace the
propertieselement under the Single Level Group By Report Extended module with the following:
Here we've added:
projectidallows users to choose the project or filter used to generate the report. The projects that are available in a given JIRA instance are retrieved through JIRA's
startDatesets the start of the time period included in the report.
endDatesets the end of the time period for the report.
intervalspecifies the time interval used to divide the overall time period. This is the histogram interval, in other words.
So far, we've been working on two modules at once, each of which corresponds to separate reports in JIRA. From here, let's take them one at a time, starting with the Single Level Group By Extended report.
Step 5. Write the Single Level Group By Extended report code
When you used the SDK to create the modules, it gave you the stub code files for the reports. The stub code is very simple: just a constructor and a few imports. We'll build on it now.
For our first report, we're extending a report delivered with JIRA, the
SingleLevelGroupByReport class. If you have access to the JIRA source code, you can find the source code for the original at this location:
As a reminder, our goal is to include the time of last update for each issue in the report output. It should be rendered in the appropriate date/time format configured in JIRA. The view template gets values to display in JIRA through the parameter map passed by the module code. Thus, we'll modify the parameter map generated by the original JIRA report to add the OutLookDateManager's OutlookDate object to the Velocity template.
Open the source file for the report that the SDK gave us,
SingleLevelGroupByReportExtended.java. The file is under the project home at:
Replace its contents with the following. This is the source code of the original report, but tweaked to account for a different classname and package.
As mentioned, this is simply the original report. Next, add the code that presents the time of last update to the report.
Under the existing field declarations for the class, add a new field:
Also add the new field as a parameter passed to the class constructor.
generateReportHtml()method, add the following line. It should appear within the
tryblock in which the code assigns values to the parameter map.
This code appends an additional parameter to the parameter map created by the method.
- Save your changes.
The class as modified should look something like this:
Step 6. Create the view template for the Single Level Group By report
Next, edit the report view template to display the assignee and the issue's last update time. This version differs from the original JIRA report in two places where we loop over the issue result set to display the time.
Let's update the resource files that the SDK gave us.
- Open the template for the Single Level Group By Extended report:
Replace the placeholder content with the following:
This template code is identical to the template for the original report, but with an added table cell in the output that contains our date.
Open the properties file,
Replace its contents with the following:
These are the text strings that will appear in the UI generated by the report.
- Save and close the file.
That gives us enough to try it out in JIRA. You'll do that next.
Step 7. Start up JIRA and try the report
See what we've got so far by starting up JIRA:
At the command line, change to the project root directory (where the POM is located), and enter the following command:
Give the SDK a few minutes to download the JIRA files and start it up. If you run into build errors, make sure you have enabled the dependency for the
jira-coreartifact in the project POM.
- Once JIRA finishes starting up, open the JIRA interface in a browser with the default credentials, admin/admin.
- Before trying out your report, create a few JIRA artifacts first:
- Create a project. The first time your start JIRA, a wizard prompts you to create one.
- Create a few test issues in the project. To give your report a property to group by, choose different assignees or issue types for your issues.
- Also create at least one filter. You can do this from the search page. For more help, see the documentation on JIRA filters.
- When ready to run the report, go to the Overview page for your project.
- In the Summary view, scroll down and notice your two new reports at the bottom of the list.
- Click Single Level Group By Report Extended.
- Select a Filter and the statistic type you want to group by, and click Next. Your report should look something like this:
While you're at it, take a look at how the other custom report, Creation Report, looks in JIRA. We have our user input fields, thanks to the properties you added to the plugin descriptor, but there are only placeholders for labels and if you click Next, you get a blank page. You'll work on that next.
Meanwhile, you can leave JIRA running and load your plugin changes with FastDev.
Step 8. Code the Creation Report
To make the Creation Report do something a little more useful:
Open the Creation Report source code file at:
Replace its contents with the following.
The code retrieves the parameters specified by the user. It then gets the relevant issue counts from the configured time range, divided into the time intervals specified by the user. The issue counts are normalized, giving the user a balanced histogram. Finally, the relevant details are passed to the Velocity template.
- Save and close the file.
Step 9. Develop the Creation Report UI
If you tried the report in JIRA now, you would still get a blank page. To see a report, you need to code a presentation template, along with text strings that will appear in the UI. To do so:
- Open the Creation Report velocity template file for editing:
Replace its content with the following:
Add the following text strings to the properties file
Save and close the file.
Step 10. View the finished product
Now try the Creation Report again and see what we've got:
- Start up JIRA again using atlas-run or, if you left JIRA running, reload your plugin changes using the compile and reload icon in FastDev:
- At the bottom of the project summary page, click the Creation Report link.
- Supply dates that make a range that encompasses the date on which you created the issues, and long enough to give you a few intervals to look at (keeping in mind the default interval of 3 days).
- Click Next.
This time, we have a report!
Our report output UI is pretty basic, to put it politely. As a next step, try improving the report output. You can use the reports supplied with JIRA as a model.
For more information on topics covered in this tutorial, see: