Timecharts

Need help? Please read the FAQ and Troubleshooting sections first.

Description/Features

Show the history of summarized search results. For example, the number of blocker bugs over the last month.

Summary We're used to seeing charts that show information such as the number of issues summarized by priority, or assignee, or some other field. That's what the standard Filter Statistics plugin does. The Timecharts plugin adds a time dimension to those charts so you can see how the results have changed over time.

One labor-intensive way to do this would be to take a snapshot of the results every day and add each day's results to a spreadsheet outside JIRA. However, this approach is error-prone and doesn't give you the results that already in the past. This plugin takes a different approach and uses the change log information that is already saved in JIRA to calculate what the results of a filter would have been at each moment in the past, with no extra effort on your part.

• The results are displayed as a chart and as a table of data, with optional totals for the data.
• The field used to summarize the filter's data can be most of the built-in fields or even custom fields already defined by the local JIRA administrator.
• The start and end date for the report can be specified, or an interval of the last 30 days can be used. This interval can be easily changed.
• The changes can be summarized by day (the default), and also by week, hour and even second!
• There is an option to export the data to an Excel spreadsheet.
• There are also extensive unit tests provided for the plugin to help other developers modify it.

Usage

1. Check the version to use and download the plugin JAR file from the release location.
2. Copy the downloaded JAR file into the atlassian-jira/WEB-INF/lib directory in your JIRA installation.
3. You also need to have the JIRA Charting Plugin installed.
4. Restart JIRA.
5. Click on BROWSE PROJECT and choose a project. In the list of Reports on the right-hand side, choose Timechart Report.
6. Choose a filter that you have already created, and a field name to summarize the filter by. The other options can all use their default values.
7. Click Next and after a few seconds a chart and table of data should appear.

Report Configuration

The different fields that can be configured for a Timecharts report are:

Filter

The name of the saved filter for which you want to see the history. For example, "All our bugs for the next release".

Summary Field

The issue field to count the issues on. For example, "priority".

Start Date

Start the summary from this date. If this is not set, then the last Interval days are shown.

End Date

End the summary on this date. The default is the current date.

Interval

The interval to summarize the report over, in days. This is ignored if both of the Start and End dates are specified.

Granularity

The granularity of the time data, e.g. hours, days, weeks. The default should be fine for most reports. If you want to see every change in the database, you can choose "seconds", but be warned that generating the report can take a long time.

Show Totals

Show the total of the counts for each day, week, etc.

Examples

Let's say that I'm a QA manager and I want to keep track of the number of critical bugs as a release date approaches. I define a filter that shows me the current bugs marked for the release. I can even use the Filter Statistic portlet to get a bar graph of the summarized priorities of the results. But I'm actually more interested in how the results have changed in the last month. So I create a Timechart Report, select the same filter that I used before and tell the Timechart Report to summarize by Priority. The chart shows me all summarized results for the last 30 days and I can see whether the numbers are going up or down over time.

Screenshots

Screenshots of the JIRA Timecharts Plugin (view as slideshow)
	5. Scrolling down from the chart to see the results		6. Example of the Excel output of the timecharts plugin		7. Another timechart example.
	An example of a timechart		1. A filter used to show bugs for the next release		2. Timechart Report configuration using the same filter
	3. The generated chart and data for the filter		4. The same chart but now only looking at one priority (major)

The configuration slide shows the Unit Tests field enabled. This field is for use by plugin developers and by default does not appear.

(Confluence doesn't yet have a way to set the order of the slides in the slideshow, so run it to the end and then use Previous for the intended order of 1 to 7.)

Building and Developing

First, set up your environment, please read the [How to build an Atlassian Plugin].

To make changes to the plugin, you need to download the source and compile it yourself.

For JIRA versions 3.11 and later:

1. Download the timecharts plugin source with the command svn co https://svn.atlassian.com/svn/public/contrib/jira/jira-timecharts-plugin
2. Change directory to jira-timecharts-plugin
3. Make sure that you have a Java 1.4 compiler and Maven 2.x installed, as described in the new documentation
4. Type mvn package and the resulting plugin JAR file is in the target subdirectory.
5. You can also download JIRA, compile and deploy in one step with mvn -Pplugin-debug

For JIRA versions 3.10 and earlier:

1. Download and unpack the appropriate JIRA development kit
2. Inside the unpacked development kit, create a subdirectory named myplugins or some such and change directory to it.
3. Download the timecharts plugin source with the command svn co https://svn.atlassian.com/svn/public/contrib/jira/jira-timecharts-plugin
4. Change directory to jira-timecharts-plugin
5. Make sure that you have a Java compiler and Maven 1.x installed, as described elsewhere
6. Type maven jar and the resulting plugin JAR file is in the target subdirectory.

Unit Tests

If you modify the plugin, you will no doubt want to run the provided unit tests. To do this, uncomment the whole property element with a key of tests in the src/main/resources/atlassian-plugin.xml file and rebuild the plugin JAR file. After deployment and restarting JIRA, you should then see an extra field named "Unit Tests" at the bottom of the configuration screen for the Timechart Report. You can run all the unit tests by entering "all", or one or more by entering their names separated by commas. The test names, with their results and duration are then displayed. All fields except "Unit Tests" in the configuration screen are ignored when running unit tests.

FAQ

1. Does it work for all filters?

Most common filters do just work. However, filters that use fields in the "Dates and Times" section of FIND ISSUES or other date and time-related fields will not work. Some of these might be possible - there is an open issue for this. The query fields that are implemented include:

• Affects Versions(s)
• Assignee (single user)
• Component(s)
• Current Time Estimate
• Due Date
• Fix For Version(s)
• Issue Type (but not "Standard Issue Types")
• Original Time Estimate
• Priority
• Project
• Reporter (single user)
• Resolution
• Status
• Time Spent
• Votes

2. How does it work?

The results from running a saved filter on the current data are recorded inside the plugin. Next a database query is constructed that contains all the fields that could possibly have affected the results of the filter. This query is run against the change log stored in JIRA, the same place that provides the information for the Change History tab in every issue. The results from the query are then processed to work out what the result of filter would have looked like before each change, and the summary of the filtered data is updated. Finally, a chart is constructed from the data and displayed.

3. How much does it slow down JIRA?

Not much! The plugin has been tested with over 5000 issues in the filter results, and complex queries. The report is usually generated in about 2 seconds, though more complex queries can take up to 10s for large date ranges. Interactive response times with JIRA are not greatly affected during the time that the report is being generated. The reason for all this is that the database query is very specific so that only the necessary information has to be processed by the plugin. Of course, enabling the debug logging in the plugin slows it down significantly.

4. Why is my report not very interesting?

If a report was produced, but it only had one vertical line, then try increasing the date ranges or interval. If nothing changes during the specified interval, then there is only one set of points to show in the report, which is not very interesting. Interesting charts usually have queries that include issues that had some activity during the dates specified.

5. Why is my report overwhelming me with data points?

Try reducing the granularity of the report from days to weeks, which will reduce the number of data points in the report.

6. Does it matter which project I run the report from?

No, because the name of the current project is not used by the plugin.

7. Does it work with all databases?

The plugin has only been tested with MySQL and HSQL. There have been reports that it works with Oracle. Feedback on working platforms would be helpful here.

Troubleshooting

It didn't work for me Now what?

1. If there was a problem restarting JIRA, perhaps you have the wrong version of the plugin? Check the JIRA log files for more information.

2. If the Timechart Report link doesn't appear in the Project homepage, perhaps the plugin has been disabled (though it is enabled by default). Check the list of plugins under ADMINISTRATION.

3. If there is no filter that you want to use, first create the filter and save it as usual, then return to the Timechart Report

4. If you get an error such as "The query field name created:before is either not implemented, or is related to time and so is not supported." then see the FAQ entry here.

5. If report was produced, but it only had one line, then see the answer to this FAQ.

6. If the data doesn't go back in time as far as you expected, consider that only the earliest known change is shown. Otherwise the plugin would produce long horizontal lines to the given start date, which wouldn't be very helpful. If you really want an option to do this, please see the next paragraph and file a feature request. Also, the earliest data of any change is the date when the last backup was imported, since the change log table is cleared then.

7. If the counts appear incorrect to you, check that your filter is using the constraints that you believe it is with the Summary of the filter shown on the left when the filter is run by itself. An example of a filter summary is:

Summary
Project: MyProject
Assignee: Current User
Resolutions: Unresolved
Sorted by: Component/s ascending, then Priority descending

8. If you think that your query was one that Timecharts should have handled, or want to report any other issue, please use the Timecharts JIRA. Helpful information for a bug includes:

1. The settings used for the Timechart Report configuration page
2. The Summary of the filter shown on the left when the filter is run by itself
3. The definitions of any custom fields used in the filter or configuration, e.g. my_field is a "Select List" or "Text <255" field type.

9. If you want more debug information from the plugin, then add

log4j.category.com.consultingtoolsmiths.jira.plugins.timecharts.TimeChart = DEBUG, filelog
log4j.additivity.com.consultingtoolsmiths.jira.plugins.timecharts.TimeChart = false

to your atlassian-jira/WEB-INF/classes/log4j.properties file. This can cause reports to take up to ten times longer to execute.

Known Issues

Bugs

Atlassian Developer Network JIRA (10 issues)
T	Key	Summary	Assignee	Reporter	Pr	Status	Res	Created	Updated	Due
	TMCT-13	status vs time timechart with same value for totals for all dates	Matt Doar	Asaf Matatyaou		In Progress	UNRESOLVED	May 10, 2007	Dec 12, 2007
	TMCT-11	empty chart if summary field = priority	Matt Doar	Bettina Zucker		In Progress	UNRESOLVED	May 09, 2007	Oct 09, 2007
	TMCT-9	Problems with handling of changeitems	Matt Doar	Bettina Zucker		In Progress	UNRESOLVED	May 09, 2007	May 09, 2007
	TMCT-41	Exception when configuration contains custom field named "Project"	Matt Doar	Eugene Gavrilov		Open	UNRESOLVED	May 15, 2008	May 15, 2008
	TMCT-40	Misformated SQL for Oracle	Matt Doar	Wayne Branagh		Open	UNRESOLVED	May 05, 2008	May 05, 2008
	TMCT-39	If not logged in, may get incorrect results for some JIRA configurations	Matt Doar	Matt Doar		Open	UNRESOLVED	Mar 28, 2008	Mar 28, 2008
	TMCT-32	Report generates unhandled exception when selecting a query containing relative times	Matt Doar	Dominick Moré		Open	UNRESOLVED	Nov 16, 2007	Nov 16, 2007
	TMCT-27	When the filter refers to a user group, the plugin fails	Matt Doar	Ross Lamont		Open	UNRESOLVED	Aug 30, 2007	Apr 29, 2008
	TMCT-23	totals are constant over time	Matt Doar	Bettina Zucker		Open	UNRESOLVED	Jun 26, 2007	Jun 27, 2007
	TMCT-4	Remember the field choices better	Matt Doar	Matt Doar		Open	UNRESOLVED	May 05, 2007	May 05, 2007

New Features and Improvements

Atlassian Developer Network JIRA (13 issues)
T	Key	Summary	Assignee	Reporter	Pr	Status	Res	Created	Updated	Due
	TMCT-43	Support SQL Server for Timecharts plugin	Matt Doar	Joanna Thurmann		Open	UNRESOLVED	Jun 17, 2008	Jun 17, 2008
	TMCT-38	stacked area graph option	Matt Doar	Matt Doar		Open	UNRESOLVED	Feb 04, 2008	Feb 04, 2008
	TMCT-35	OutOfMemoryError on large JIRA installations	Matt Doar	Wojciech Gdela		Open	UNRESOLVED	Dec 11, 2007	Apr 12, 2008
	TMCT-33	Clicking on a specific node in the report returns a 404 for secure/index.html	Matt Doar	Chris Hemphill		Open	UNRESOLVED	Nov 16, 2007	Apr 11, 2008
	TMCT-31	Create a portlet version of the plugin	Matt Doar	Matt Doar		Open	UNRESOLVED	Nov 14, 2007	Apr 02, 2008
	TMCT-25	Internationalization work for the plugin	Matt Doar	Matt Doar		Open	UNRESOLVED	Aug 07, 2007	Aug 07, 2007
	TMCT-24	Customizable colors in the chart	Matt Doar	Matt Doar		Open	UNRESOLVED	Jun 26, 2007	Jun 26, 2007
	TMCT-21	Add support for filters with text queries	Matt Doar	Matt Doar		Open	UNRESOLVED	Jun 13, 2007	Jun 13, 2007
	TMCT-20	Think about the burn charts	Matt Doar	Vincent Eggen		Open	UNRESOLVED	Jun 13, 2007	Nov 09, 2007
	TMCT-16	Make Excel data easier to plot in charts	Matt Doar	Matt Doar		Open	UNRESOLVED	May 18, 2007	May 18, 2007
	TMCT-12	Add the ability to specify colors in the chart	Matt Doar	Matt Doar		Open	UNRESOLVED	May 09, 2007	May 09, 2007
	TMCT-7	Fields that are not supported yet but could be	Matt Doar	Matt Doar		Open	UNRESOLVED	May 08, 2007	May 09, 2007
	TMCT-5	Remove the dependency on the Jira Charting plugin	Matt Doar	Matt Doar		Open	UNRESOLVED	May 05, 2007	May 05, 2007

Tasks and Sub-Tasks

Atlassian Developer Network JIRA (5 issues)
T	Key	Summary	Assignee	Reporter	Pr	Status	Res	Created	Updated	Due
	TMCT-37	Add to FAQ	Matt Doar	Matt Doar		Open	UNRESOLVED	Jan 29, 2008	Jan 29, 2008
	TMCT-22	How to create a query that finds just one specific issue?	Matt Doar	Matt Doar		Open	UNRESOLVED	Jun 13, 2007	Jun 13, 2007
	TMCT-19	Add unit tests to check what happens when assignees change their names	Matt Doar	Matt Doar		Open	UNRESOLVED	May 29, 2007	May 29, 2007
	TMCT-17	Provide an image for the plugin chooser	Matt Doar	Matt Doar		Open	UNRESOLVED	May 18, 2007	May 18, 2007
	TMCT-15	Test custom statuses and transitions	Matt Doar	Matt Doar		Open	UNRESOLVED	May 17, 2007	May 17, 2007

Version History

The plugin version should usually match the JIRA version that it has been tested against.

Downloads

TODO use the right key to make the display for just this plugin look like http://confluence.atlassian.com/display/CONFEXT/Social+Bookmarking+Download+Tracking+Past+Three+Months as described at http://confluence.atlassian.com/display/DEVNET/Confluence+Atlassian+Plugin+Repository+Macros

Acknowledgements

This plugin was originally developed for and funded by PacketMotion, Inc