JIRA Graph Plugin

This plugin may no longer be supported. I (Graham) created this plugin during the spare time of one of my co-op terms. Due to other responsibilities, I will no longer be supporting this plugin. This plugin was originally created to work with Confluence 2.6.2 and JIRA 3.11. As never versions of Confluence and JIRA are released this plugin may not work. The latest snapshot of the source code is attached to this page; feel free to edit and recompile it as needed. The project may eventually be picked back up, but for now it works as I need it to.

My apologies - Graham.

Name	JIRA Graph Plugin
Version	1.2
Author	Graham J Bell or Kyle Dohring
Price	Free
Download JAR	jira_graph-1.2.jar
Source Code (Jan 25th, 2008)	jira_graph04113008.zip

What is it?

This is a not a JIRA plugin, but a Confluence plugin that displays a graph of total issues per status over time, directly from a JIRA database. It is similar to using the JIRA Charting Plugin in combination with the JIRA Portlet Macro, but was designed with a different purpose and different functionality. The JIRA Graph Plugin was not designed to replace or compete with these excellent plugins, but merely be an additional tool for developers to use if they wish.

Advantages/Disadvantages to the Charting Plugin + Portlet Macro

While the JIRA Charting Plugin does offer extensive functionality, it is only capable of graphing 'Created vs Resolved Issues' over 'a period of X days previous to the current date'. The JIRA Graph Plugin is capable of graphing all five of the main statuses (Created, In Progress, Reopened, Resolved, Closed) over any time range. It is also capable of combining the 'Created', 'In Progress' and 'Reopened' statuses to obtain a total of all issues that are 'Under Investigation'. More importantly it was designed specifically for Confluence and the average Confluence user, who requires little to no experience with JIRA itself. The plugin is not dependent on any other Confluence or JIRA plugins or macros.

The JIRA Graph Plugin is not capable of graphing using any saved filter, but does offer extensive flexibility as to which selection of issues a user wishes to graph.

The JIRA Graph Plugin is capable of applying weights to different priorities. Sometimes a business like to see how they are doing in regards to P1 issues being more important than P5 issues. This is sometimes referred to as a Software Quality Index (SQI) graph.

Changing what selection of issues are being graphed is easier with the JIRA Graph Plugin. If the Charting Plugin and Portlet Macro are being used and a Confluence user wishes to change which issues are being graphed, he/she would have to log into JIRA and create a saved filter from a massive selection of options (which can be intimidating to inexperienced users), then create the portlet in JIRA, then copy the protlet's URL and paste it in the Confluence wiki-markup. However, if the JIRA Graph Plugin is being used and a Confluence user wishes to change which issues are being graphed, he/she only needs to change the parameters being passed to the macro (see below), or simply use no parameters, which will instead cause a Java Applet GUI to run, which allows users to preview any graph without ever having to go near JIRA.

The JIRA Graph Plugin includes a Java Applet GUI, designed specifically for novice users. It is capable of 'previewing' any graph the macro creates without having to refresh/change the web page or go anywhere near JIRA. This can be beneficial in situations where some users may have access to the company's Confluence system, but no access to the company's JIRA system. The GUI applet also has a feature where by simply pressing a button, a popup appears with generated wiki-markup code that if copied and pasted in Confluence will result in the macro creating the same graph the applet just previewed.

One disadvantage is that the JIRA Graph Plugin's macro and applet to not query the database in real time, as doing so would take very long. Instead the plugin uses a cache system, where it is required to periodically query new information from the database and rebuild a cache. Once a cache is constructed, the macro and applet simply load the cache files each time they are run to generate new graphs from the files. How frequently this update occurs can be configured in the plugin's configuration screen and is at the administrator's discretion.

The JIRA Graph Plugin does not interact with JIRA at all, but instead queries its database. At present moment the JIRA Graph Plugin is only capable of querying SQL Server, MySQL and Oracle databases. Will likely add more capability in future versions.

Downloading & Installing

At present moment the only means to install the JIRA Graph Plugin is to download the jar file directly (if you are using Internet Explorer, please change the '.zip' extension of the file to a '.jar' extension after downloading). Then upload the file using the Confluence Administrative Console.

IMPORTANT:

The macro and applet will not run until you have successfully configured the plugin and created a cache. Once the plugin is installed you can access it's configuration screen (see screenshots below). From there you must properly configure all fields. You can click the 'Help' link to bring up a page with more information about the fields. Once the plugin is configured and you have clicked 'Update', you must build the cache. There are two ways to initiate building the cache: either try to use the macro or applet {jira_graph} in an actual Confluence page, or go to the Cache Details screen and click the 'Refresh Cache' button.

If you try to use the macro or applet before the cache exists, it will start a separate thread in the background to build the cache and return saying the cache is not ready yet (this is normal). To access the Cache Details screen go to the plugin's configuration screen, click the 'Help' link, then click the 'Cache Details' link. The Cache Details page gives more detailed information about what the cache is and when it was last updated, as well as the ability to update the cache immediately. The larger the database is, the longer the cache takes to build. The cache usually takes between 5 and 15 minutes to refresh, but could take much more or much less time, depending on the size of the database.

Macro Parameters

To run the applet instead of the macro, just add {jira_graph} with no parameters. The applet tool can help you build what graph (and what parameters) you want to use with the macro.

All parameters are optional. If a parameter is not specified, its default value will be assumed.
If no parameters are specified (or 'gui' is specified as true), then all parameters will be ignored and the GUI applet will run instead.
If more than one project or 'all' is specified, then the fixfor, affected and components parameters will be ignored.
If the priority weights are disabled in the plugin's configuration, then the weights parameter will be ignored.

Parameter	Description	Expected Values	Default Value
gui	Determines if the user wishes to use the GUI applet instead of the macro.	Boolean value: true or false	true
minimode	Determines if the macro will display results in full, or as a mini graph.	Boolean value: true or false	false
type	Specifies what type of graph to display (1=Bar Graph, 2=Scatter Graph, 3=Line graph with points, 4=Line graph with no points).	Integer value between [1 and 4].	3 (Line Graph with points)
dategroup	Specifies how to group results (-1 = by day, -2 = by week, -3 = by month, -4 = by year).	Integer value between [-1 and -4]	-1 (group by day)
fgcolor	Specifies what color the borders and text in the graph will be.	Six-character hexadecimal number.	000000 (black)
bgcolor	Specifies what color the background of the graph will be.	Six-character hexadecimal number.	FFFFFF (white)
priorities	Specifies the macro to only count issues with desired priorities.	Comma-separated list of integers, or '*' or 'all'.	all
groupstatus	Determines if the 'Created', 'In Progress' and 'Reopened' statuses should be combined as 'Under Investigation'.	Boolean value: true or false	false
cumulative	Determines if totals will be cumulative or not.	Boolean value: true or false	false
weights	Determines if weighted values will be applied to priorities.	Boolean value: true or false	false
projects	Specifies the macro to only count issues belonging to desired projects.	Comma-separated list of project keys, or '*' or 'all'.	all
fixfor	Specifies the macro to only count issues in the desired project belonging to desired fixfor versions.	Comma-separated list of fixfor versions, or '*' or 'all'.	all
affected	Specifies the macro to only count issues in the desired project belonging to desired affected versions.	Comma-separated list of affected versions, or '*' or 'all'.	all
components	Specifies the macro to only count issues in the desired project belonging to desired components.	Comma-separated list of components, or '*' or 'all'.	all
start	Specifies what date the date range for issues should start on. If empty or not specified, the macro will use the earliest date any issue was created.	Valid date in the format of 'DD/MM/YYYY', or the empty string. Only numbers and slashes - no letters.	An empty string
end	Specifies what date the date range for issues should end on. If empty or not specified, the macro will use the latest date any issue had it's status changed.	Valid date in the format of 'DD/MM/YYYY', or the empty string. Only numbers and slashes - no letters.	An empty string

Example Usage

{jira_graph}	Runs the GUI Applet tool instead of the macro.
{jira_graph\|gui=false}	Runs the macro and displays totals for all issues over the entire history (by day).
{jira_graph\|gui=false\|start=01/01/2007}	Runs the macro and displays totals for all issues from 'Jan 1st, 2007' to 'today' (by day).

Different Modes

The plugin is capable of running in three modes. The 'gui' and 'minimode' parameters will determine which of these modes it runs in. The first is the GUI Applet tool which can preview any graph but does not save which graph the user was viewing. The second is the macro in full mode which displays a large, highly-detailed graph as well as tables of the statistical information and search parameters. The third is the macro in mini-mode, which displays a mini-graph and a value, that will either represent the maximum or 'final graph value' of each status (depending on whether cumulative is true/false). The gallery below contains one screenshot of each of these modes.

In mini-mode you can mouse-over for more information. Both full and mini-mode versions of the macro offer the ability to download the statistics table as a comma-separated value (CSV) file, by clicking the image.