Add goal lines and target areas to charts

Overview

To track your team's release, performance, or quarterly goals, annotate your report charts with goal or performance threshold lines, burn-up guidelines, or target zones using a Dataplane Customizer Script.

If you're not yet familiar with using Customizer Scripts in your reports, read through Customize reports with scripts for some background and then return back here to get going.

The following Dataplane chart, for example, is a traditional Cumulative Flow Diagram of the status of project issues in September. At the end of the four-week reporting period, substantial work has yet to be started. As a project manager, sharing a PDF export of this report with management would require an extensive written explanation to avoid an understandable barrage of concerned questions.

Using Dataplane chart annotations, though, we can provide concise, useful reference points so everyone shares a clear understanding of the unexpected delays.

Here we've added two goal lines and a box annotation to explain the large deviation in scope:

With Dataplane chart annotations, we've clearly identified the original scope of work, can better gauge the amount of additional features requested in the early weeks, have noted the timing of the September 23 program management review, and called out the new work scope that resulted from that meeting.

Displaying goals and adjustments front-and-center on Dataplane charts and legends will help team members and management visualize target metrics more easily, understand course corrections, and celebrate program and team success.

Chart annotation basics

In Dataplane, you can annotate report charts with any number of styled lines or boxes. These chart annotations appear in the chart legend for easy reference and are visible everywhere the chart is displayed–within Dataplane, in exported PDF reports, in Jira dashboard gadgets, and on Confluence pages.

The general syntax for a Customizer Script that adds line and box annotations to a report looks like this:

customizeChart {
	lineAnnotation "<name>" <property1> <value1> <property2> <value2> <property3> <value3>
	boxAnnotation "<name>" <property1> <value1> <property2> <value2> <property3> <value3>
}

By setting various properties of line and box annotations, you can easily control their position, color, size, and labeling:

Property	Values	Description

Property	Values	Description
`<default>`	`"<name>"`	The name of this annotation is to be shown in the chart legend.
`at`	^<value> ^"<date>"	<value>—Display a line across the entire chart at this value on the range axis. "<date>"—Display a vertical line from the bottom to the top of the chart on this date.
`from`	^{("<date or category>", <value>)}	For lines, the left-most (or top-most) point. For boxes, either of the left-most (or top-most) corners.
`to`	^{("<date or category>", <value>)}	For lines, the right-most (or bottom-most) point. For boxes, the right-most (or bottom-most) corner that is diagonal from the one specified by from.
`color`	`<colorName>` `"#rrggbb"` `(rr,gg,bb)`	<colorName>—Any color name from the list of standard HTML 4 or X11 colors (case insensitive), as in: "blue" "#rrggbb"—A hexadecimal RGB color string, as in: "#F0F0F0" (rr, gg, bb)—Decimal RGB component color values where each value is between 0 - 255, as in: (200, 163, 24)
`width`	`<number>`	The width of the line, as in: 5 (default = 2)
`style`	`"solid"` `"dotted"` `"dashed"` `("<lineStyle>, "<color>")` `("<lineStyle>, "<color>", <width>)`	The line style. The line style and color (either by color name or hexadecimal RGB string). The line style, color, and line width.
`order`	<number>	The order in which this annotation should appear in the legend, where 1 is first, 2 is second, etc.

All dates used in chart annotations are of the following format: "yyyy-MM-dd"

Where: yyyy = year, MM = numeric month (e.g. 01, 12), d d = numeric day of month (e.g. 07, 31)

For example: 2014-12-30 (December 30, 2014) and 2014-09-01 (September 1, 2014)

Add line annotations

Chart line annotations are commonly used for:

Setting goal lines and thresholds
Creating burn down and burn up guidelines
marking project milestones on the timeline

In Dataplane, line annotations can be added to the following chart types:

Chart Type		Line Annotation

Chart Type		Line Annotation
Column chart
Normalized column chart
Bar chart
Normalized bar chart
Line chart
Area chart
Pie chart
Multi-pie chart

The general notation for a Customizer Script line annotation is:

customizeChart {
	// just specify a value for a line across the whole chart
	lineAnnotation "<name>" at <value>
 
	// or, specify specific start and end points
	lineAnnotation "<name>" from ("<date or category>", <value>) to ("<date or category>", <value>)
}

In addition, there are lots of shorthand options for drawing line annotations. All of the following are valid ways of describing a line annotation:

customizeChart {
	lineAnnotation "Orig Velocity" from ("2013-05-01", 0) to ("2013-06-30", 100)
	lineAnnotation "Team Goal" at 100
	lineAnnotation "Internal SLA" from 75 to ("2013-08-01", 75) color "lightblue"	// initial SLA
	lineAnnotation "Internal SLA2" from ("2013-08-01", 100) to 100 color "blue"		// SLA revised August 1st
}

Goal lines and thresholds

Goal lines and thresholds are usually represented by a line drawn parallel to the domain axis and across the entire width (or height) of the chart. The simplest notation for this is:

customizeChart {
    lineAnnotation "Q1 Goal" at 120
}

Here, "Q1 Goal" is the name that will be displayed in the chart legend, and 120 is the position on the range axis (in units of the range axis) at which the line will be drawn.

If we want to get fancier, we can style the line by applying color, width, and pattern:

customizeChart {
    lineAnnotation "Q1 Goal" at 120 color "maroon" width 5 style "dashed"
    lineAnnotation "Q2 Goal" at 145 color "#5620D0" width 5 style "solid"		// use rgb color #5620D0 (purple)
    lineAnnotation "Q3 Goal" at 170 color (80,80,80) width 2 style "dotted"		// use rgb color #808080 (gray)
}

The following instructions create the exact same line annotations, but using the more abbreviated style keyword:

customizeChart {
    lineAnnotation "Q1 Goal" at 120 style ("dashed", "maroon", 5)
    lineAnnotation "Q2 Goal" at 145 style ("solid", "#5620D0", 5)		// use rgb color #5620D0 (purple)
    lineAnnotation "Q3 Goal" at 170 style ("dotted", "#808080", 2)		// use rgb color #808080 (gray)
}

And here's what the annotations look like:

For the Cumulative Flow Diagram chart in the example at the top of page, the following line annotations were used to mark the original scope of work and the adjusted scope of work:

customizeChart {
    lineAnnotation "M14 Original" at 120 color "orange" width 5 style "dotted"
    lineAnnotation "M14 Adjusted" at 168 color "red" width 2
}

Burn down and burn up guidelines

Guidelines for classic burn-down and burn-up charts are typically drawn diagonally from the beginning to the end of the time period to show an ideal velocity of work.

The way to draw a Dataplane guideline is as follows:

customizeChart {
    lineAnnotation "Project Burn Up" from 0 to 100 color "blue" style "dotted"
}

If we anticipate a change in team velocity over the reporting period, for example, if additional resources are added to the project, we can even draw separate lines over partial periods to introduce more granularity in our ideal velocity:

customizeChart {
	lineAnnotation "Orig Velocity" from 0 to ("2013-08-10",30) color "blue" style "dashed"
	lineAnnotation "Orig Velocity +2" from ("2013-08-10",30) to 100 color "green" style "dashed"
}

Mark project milestones

Line annotations are also a convenient way of marking key project milestones on your Dataplane report charts, such as:

customizeChart {
	lineAnnotation "Project Kickoff" at "2013-07-20" order 1 color "green"
	lineAnnotation "Added Blue Team" at "2013-08-08" order 2 color "blue"
	lineAnnotation "First PM Review" at "2013-09-23" order 3 color "orange"
	lineAnnotation "Q2 Division Status Update" at "2013-09-30" order 4 color "red"
}

In this example, we've added the order property to each annotation so that they appear in the chart legend in a logical, date-based order.

Add box annotations

Chart box annotations are commonly used for:

Identifying performance target zones
highlighting areas to explain exceptional results

In Dataplane, box annotations can be added to the following chart types:

Chart Type		Box Annotation

Chart Type		Box Annotation
Column chart (historical timeline charts)
Column chart (current value charts)
Normalized column chart (historical timeline charts)
Normalized column chart (current value charts)
Bar chart
Normalized bar chart
Line chart
Area chart
Pie chart
Multi-pie chart

The general notation for a Customizer Script box annotation is:

customizeChart {
	boxAnnotation "<name>" from ("<date>", <value>) to ("<date>", <value>)
}

Where the from property is always either of the left-most corners of the box, and the to property is always the right-most, diagonal corner.

Target zones and highlighted areas

For the Cumulative Flow Diagram chart in the example at the top of page, the following box annotation was used to provide an explanation for the large jump in scheduled work following a program management review:

customizeChart {
	// add a box highlight around September 23rd to highlight the PM review that day
    boxAnnotation "Sep 23 PM Review" from ("2013-09-23", 115) to ("2013-09-25",180) style ("dotted", "black", 2)
}

Put it all together

For completeness, here's the entire Dataplane report Customizer Script for the example report described at the top of the page:

customizeChart {
    series ANY color "gainsboro" order 50

    series "Work in Progress" color "green" order 1
    series "Open" color "blue" order 2
    series "Reopened" color "cyan" order 3
 
    lineAnnotation "M14 Adjusted" at 175 color "red" width 2
    lineAnnotation "M14 Original" at 120 color "orange" width 5 style "dotted"

    boxAnnotation "Sep 23 PM Review" from ("2013-09-23", 115) to ("2013-09-25",180) style ("dotted", "black", 2)
}

Which produces the following, nicely-annotated Jira Cumulative Flow Diagram report:

Page Contents