Customizing Charts and Data Series

Overview

By adding a Dataplane Customizer Script to your report, you can modify many aspects of how charts are drawn in report results.

The charts produced by Dataplane can be customized using a customizeChart section in a Customizer Script.

A customizeChart section can customize the chart series, its axes, and more.

customizeChart {
    // one or more chart-customization commands go here
}

Customizing Chart Axes

Dataplane allows you to customize both the domain (X) axis and range (Y) axis of reports.

The domain (X) axis can be customized with a custom title.

The range (Y) axis can be customized with a custom title, and you can set explicit minimum and maximum range values, and change the scale used.

Customizing the Domain (X) Axis

The title of the domain axis can be customized like this:

customizeChart {
    axis "domain" title "Dates in Project Timeline"
}

Customizing the Range (Y) Axis

The range axis can have its title customized, and in addition, the range and scale of the axis can be configured. For example:

customizeChart {
    axis "range" title "Issues Handled"

    axis "range" min 100                  // set the minimum of the Y axis to 100
    axis "range" max 500                  // set the maximum of the Y axis to 500

    axis "range" range(100, 500)          // set both min and max at the same time

    axis "range" scale "log"              // use a logarithmic scale instead of linear
}

Customizing Data Series

A series in Dataplane corresponds to an individual line or bar segment in the output chart. To allow users to select a specific series, Dataplane first allows users to name the individual segments in the series, or to use wildcards to match each segment. After a series has been selected, the user can specify one or more customizations to be performed on that series.

Selecting Series Directly

In general, the segments of a series consist of all of the Segment By options selected by the user in the report configuration page.

In the simplest case, in which a report is segmented by one specific field (such as Priority), series can be selected by specifying the priority name directly.

For example, if possible priorities for an issue were P1 and P2, the following customizer script would adjust the color of P1 to be red and the color of P2 to be green:

customizeChart {
    series "P1" color "red"
    series "P2" color "green"
}

As a more complicated example, suppose that the user runs a report which uses Segment By selections of both Priority and Issue Type. If the valid priorities were P1 and P2, and if the valid issue types were Bug and Feature Request, the possible set of generated series would be as shown in the table below. The combined series name ("Series Name" in the table below) is also what Dataplane displays on the report legend:

In order to select a specific series in this case, the customizer script should include the word series followed by a list of quoted segment names, each separated by commas and all enclosed in parenthesis

For example, the following customizer script would set all P1 Feature Requests to yellow, and all P2 Bugs to black.

customizeChart {
    series("P1", "Feature Request") color "yellow"
    series("P2", "Bug") color "black"
}

Selecting Series using Wildcards

If you want to match all components in a specific series, use the word ANY (without quote marks) in place of an explicit segment in order to match any value.

Using the same scenario as in the previous section, in order to color all P1 series brown, regardless of whether they are Bugs or Feature Requests, use the following:

customizeChart {
    series("P1", ANY) color "brown"
}

Selecting Series using Regular Expressions

In addition to matching series based on explicit names, advanced users can also use Java-style "regular expressions" in order to match more than one series. A regular expression is a special series of characters that allows the use of wildcards to match more than one type of series name. Oracle, the makers of Java, provide a standard reference for Java-style regular expressions.

To match a series using a regular expression, simply write seriesRegex instead of the plain series used in the examples above. For example, if a report were segmented only by Priority, the following would specify that priorities P1, P2 and P3 should be pink and P4 and P4 should be orange. In this example, the square brackets denote that any single letter or number inside the brackets will be matched, so "P[123]" will match "P1", "P2" or "P3".

customizeChart {
    seriesRegex "P[123]" color "pink"
    seriesRegex "P[45]" color "orange"
}

As another example, assume a chart were segmented by Issue Type, and possible issue types were "Bug", "Feature", and "Documentation Task", "Technical Task". If we want to select all of the Issue Types that end in the word "Task", we can use the ".*" sequence of characters to match any arbitrary sequence of characters:

customizeChart {
    seriesRegex ".*Task" color "blue"
    series "Bug" color "yellow"
    series "Feature Request" color "white"
}

The above example would apply the blue color to all technical tasks, while bugs would be yellow and feature requests would be white. Both series and seriesRegex can be mixed within the same customizeChart block. If multiple commands can be matched to the same series, Dataplane will apply the customization from the very last match.

Customizing the Series Name

Dataplane displays names for series in the report legend and in chart tooltips. The series name is automatically created by combining all of the series segments together with a "/" character. For example, a report segmented by Priority and Issue Type might have a series name such as "P1 / Bug".

If you wish to change the name of a series in the legend, use the series or seriesRegex commands from above to select the series, and then write the word name, followed by the new name of the series in quotes. For example, to rename P1 / Feature Requests to "Urgent Feature Requests", and "P5 / Bug" to "Throwaway Bugs", use the following:

customizeChart {
    series ("P1", "Feature Request") name "Urgent Feature Requests"
    series ("P5", "Bug") name "Throwaway Bugs"
}

Customizing Series Color

Many of the above examples have shown how to customize the color of particular series segments. Dataplane allows the user to customize series segments using both color names and HTML color codes. In addition, Dataplane allows the user to suggest that multiple series segments be given similar colors.

The color command tells Dataplane to assign a single color to the selected series. After writing the word color, you can include either an HTML color code or a color name.

Dataplane supports all named colors in the lists of basic W3C colors and extended W3C colors. To use a color name from either of these lists, simply write the color name in quote marks after the color command. For example:

customizeChart {
    series "P1" color "cornflowerblue"
    series "P2" color "olive"
    series "P3" color "sienna"
    series "P4" color "yellowgreen"
    series "P5" color "palegreen"
}

If the specific color you want is not available in the color lists above, Dataplane also supports the use of explicit HTML color codes. An HTML color code is the symbol "#", followed by six hexadecimal digits that describe the red, green and blue components of the color. You can use any third-party tool, such as the HSL Picker website, to create a custom color code.

Once you know the HTML color code, simply write it inside a pair of double quotes, taking care to include the "#" symbol as well.

For example:

customizeChart {
    series "P1" color "#ed127c" // a reddish pink
    series "P2" color "#b6ed12" // a yellowish green
    series "P3" color "#5f4007" // dark brown
}

Customizing Series Order

Dataplane, by default, applies natural JIRA orderings to charted data series.  This includes the order of items in legends and the stacking order of chart bars and areas.

For most types of data, the natural JIRA order is alphabetic. However results segmented by Priority are always ordered from high to low priority, and results segmented by JIRA Status are always ordered based on the creation or defined order of Status field values.

To define a custom order for series, use the order keyword in a Customizer Script.

In the following example, instead of using the natural alphabetic ordering of "Browser Client", "Database", "Reporting Module", the results will be charted in the following order: "Reporting Module", "Database", "Browser Client".

customizeChart {
   	series "Database" order 2
    series "Reporting Module" order 1
    series "Browser Client" order 3
}

Some helpful tips on how to set series ordering to get the results you want:

To illustrate some common ways of using custom series ordering:

customizeChart {
	// float issues assigned to me to the top of the chart
	series "James Madison" order -2	
	// next put issues that nobody has picked up yet
	series "None" order -1	

	// put issues the triage team is looking at on the bottom
	series "Triage Team" order 999	
}

Improving Analysis with Customized Series

Highlighting Series with Color and Order

Assigning custom colors is incredibly useful for reducing "noise" in highly granular data, or for highlighting key parts of the results by reducing the visual significance of others. 

In the following example, we created a standard Dataplane Burn Up Chart that shows project issues in every single status over a one month period:

A reasonable goal in sharing this report would be to highlight the work that still needs completion. To do this, we'll set every issue that's already Resolved or Closed to a muted color and just highlight the open work:

customizeChart {
	// color every series by default to a uniform gray
    series ANY color "gainsboro"
 
	// now apply specific colors to the key series we want to highlight
    series "Work in Progress" color "green"
    series "Open" color "blue"
    series "Reopened" color "cyan"
}

Now we can see much more clearly what's actually important to the team:

Finally, to pop all the key data series to the top of the chart, we'll use the order keyword to define a custom ordering of all the series rather than using the JIRA's natural ordering of statuses:

customizeChart {
	// color every series by default to a uniform gray
	// AND make them last in the stack and legend
    series ANY color "gainsboro" order 50

	// now apply specific colors (AND order) to the key series we want to highlight
    series "Work in Progress" color "green" order 1
    series "Open" color "blue" order 2
    series "Reopened" color "cyan" order 3
}

This gives us a JIRA report that tells a very clear story:

Applying Similar Colors to Similar Series

Another powerful strategy for making key data relationships visible is using the colorLike keyword to tell Dataplane to select similar colors for similar series. This is especially useful when working with multiple levels of series segmentation—when you select two, three or more fields for Segment By in your report configuration.

For example, here's a simple Current Issue Values Report showing a user's To Do list, segmented by both Priority and Status. Because we're applying two levels of segmentation, the data is highly granular and, by default, incorporates a wide range of colors. This makes the chart data rich, but difficult to analyze.

Adding a simple Customizer Script that uses colorLike keywords to give Dataplane some hints on color assignment, we reduce the group of colors used to just five color families and get results that are far more easy to interpret and share:

customizeChart {
	// use variations of these colors for series that start with these statuses
    series "Blocker" colorLike "red" 
    series "Critical" colorLike "orange"
    series "Normal" color "gainsboro"
    series "Minor" colorLike "green"
    series "Trivial" colorLike "blue"

    axis "range" scale "log" title "My Open Issues"
}