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, domain categories, axes and more.

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

Customizations that appear later in the Customizer Script override any earlier, matching customizations.

For example:

customizeChart { 
	// these 2 lines won't have any affect since they specify an order that
	// is overridden by use of the wildcard "category ANY order" below
   	category "Epic" order 1     // show 1st
    category "Story" order 2    // show 2nd
 
	category ANY order 999      // set the default order of all categories to a max value
}

Customizing Chart Axes

Dataplane allows you to customize both the domain and range axes of report charts.

Depending on the chart type selected, the domain axis can appear either on the horizontal (X) or the vertical (Y) axis of the chart, and similarly for the range axis. For most reports, the range axis is the one displaying numeric data and the domain axis is the one displaying dates or category names.

Some examples of typical reports and their axes:

Customizing the Domain Axis

The domain axis can be given a custom title.

Use the following notation to customize the domain title:

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

Customizing the Range Axis

The range axis can be given a custom title, and you can set explicit minimum and maximum range values, and change the numeric scale used.

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 Domain Categories

A domain category is a top-level grouping of report results shown on the domain axis of a bar or column chart. Only non-historical Dataplane reports ("current reports") have domain categories, since the domain axis of Dataplane historical reports is always a date-based timeline instead of a set of categories.

Customizing a domain category involves selecting the category of interest and applying one or more customization keywords and values to that category.

Selecting Categories by Name or Wildcard

The most simple way to select domain categories for customization is by category name, or by wildcard, using the category command.

Selecting a category by name will make changes to only that one category. To apply a customization to all categories in the report, use the special ANY keyword as a wildcard in place of a category name.

For example:

customizeChart {
	category ANY order 999      // set the default order of all categories to a max value
 
   	category "Epic" order 1     // show 1st
    category "Story" order 2    // show 2nd
}

Selecting Categories using Regular Expressions

Advanced users can also use Java-style "regular expressions" in order to match more than one category. A regular expression is a special series of characters that enables complex, pattern-based matching.

Use the categoryRegex command to select a group of domain categories by regular expression.

For example:

customizeChart {
	category ANY order 999          // set the default order of all categories to a max value
    categoryRegex ".*Task" order 1  // then order all issue types whose name includes "Task" first
}

Customizing the Category Name

To change the name of a domain category, use the category or categoryRegex commands followed by the name keyword.

For example:

customizeChart {
    category "Technical task" name "Dev Task"
    category "Documentation" name "User Docs"
}

Customizing Category Order

Dataplane, by default, orders categories on the domain axis from that with the highest numeric result (on top or left) to that with the lowest numeric result (on bottom or right). If there are more categories than are to be individually shown in the report, an additional category named "Other" is added at the end with an aggregate of all remaining results not individually represented on the domain axis.

Two exceptions to Dataplane's default category ordering are when the domain categories represent the Jira Priority or Status fields. A domain showing Priority always orders the results from high to low Jira priority, and a domain showing Status is always sorted based on the creation order or admin-defined order of Jira Status field values.

Using the order keyword with one or more categories selected by a category or categoryRegex command, you can modify the default order for any domain category.

In the following example, instead of ordering domain categories by default using the magnitude of the numeric result, issue types "Epic" and "Story" are moved to the top of the chart by explicitly specifying sort order:

customizeChart {
   	category "Epic" order 1
    category "Story" order 2
    category "Bug" order 3
    category "Technical task" order 4
    category "Task" order 5
    category "Feature Request" order 6
    category "Documentation" order 7
}

Which yields the following customized chart:

Some helpful tips on how to use category ordering to get the results you want:

Using these tips, you can get the same results as in the above customization—bumping "Epic" and "Story" to the top of the chart—with the following simplified Customizer Script:

customizeChart {
   	category "Epic" order -2    // show 1st
    category "Story" order -1   // show 2nd

	// all other categories, by default, use "order 0" and come next
}

 Here's a slightly different way of specifying the customized ordering that yields identical results: 

customizeChart {
	category ANY order 999      // set the default order to a max value
 
   	category "Epic" order 1     // show 1st
    category "Story" order 2    // show 2nd
}

Customizing Data Series

A series in Dataplane corresponds to an individual line, bar or pie segment within the plotted chart.

To customize a single data series, you may identify it explicitly by providing each individual segment name that makes up the series. To provide a customization that will apply to multiple series, wildcards can be used in the list of series segments in order to match multiple data 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 series 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 complex example, suppose you run 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"
}

In general, the names supplied to the "series" keyword should be the same as the names shown in the legend after running the report. Depending on the report configuration options selected, some reports may use variations of a name, and this will be reflected in the legend.

For example, if an Issues Entering Status by Date report has the "cumulative" option selected, a status such as "Closed" will be rendered in the legend as "Closed (Sum)". To select this series in a customizer script, you would write the following:

customizeChart {
	series "Closed (Sum)" color "green"
}

Selecting Series using Wildcards

If you want to match all possible values for one segment of a series, use the word ANY (without quote marks) in place of a segment name.

For example, 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 and wildcards, you may also use Java-style "regular expressions" in order to match more than one series. A regular expression is a special series of characters that can be used to match multiple series based on a naming pattern. Oracle, the makers of Java, provide a standard reference for Java-style regular expressions.

To match one or more series using a regular expression, use the seriesRegex keyword. 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 keywords to select the desired 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
}

Applying Similar Colors to Similar Series

Another useful way of customizing series color is using the colorLike command. The colorLike command tells Dataplane to select similar colors for similar series, and 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"
}

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	
}