By adding a Dataplane Customizer Script to your report, you can modify many aspects of how charts are drawn in report results.
If you're not yet familiar with using Customizer Scripts in your reports, read through Customizing Reports with Scripts for some background and then return back here to get going.
The charts produced by Dataplane can be customized using a
customizeChart section in a Customizer Script.
customizeChart section can customize the chart series, domain categories, axes and more.
Customizations that appear later in the Customizer Script override any earlier, matching customizations.
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:
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.
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
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.
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.
categoryRegex command to select a group of domain categories by regular expression.
For help with composing Java-style regular expressions, see this standard reference.
categoryRegex can be mixed within the same Customizer Script. If multiple commands match the same category, Dataplane uses the customization from the very last match in the script.
Customizing the Category Name
To change the name of a domain category, use the
categoryRegex commands followed by the
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.
order keyword with one or more categories selected by a
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:
Which yields the following customized chart:
Some helpful tips on how to use category ordering to get the results you want:
- Custom order values can be either positive or negative. Negative numbers float the category to the top (or left) of the chart. Positive numbers sink the category to the bottom (or right).
- Any categories you haven't explicitly given a custom order to use
order 0by default. Categories with negative custom order values will be above (or left of) them, and categories with positive values below (or right of) them.
orderkeyword is what assigns category order—not the order in which the categories are referenced in your Customizer Script.
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:
Here's a slightly different way of specifying the customized ordering that yields identical results:
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:
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:
|Series Segment 1|
|Series Segment 2|
|P1||Bug||P1 / Bug|
|P2 / Bug|
|P1||Feature Request||P1 / Feature Request|
|P2||Feature Request||P2 / Feature Request|
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.
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:
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:
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" will match "P1", "P2" or "P3".
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:
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:
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:
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.
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:
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".
Some helpful tips on how to set series ordering to get the results you want:
- Custom order values can be either positive or negative. Negative numbers float the series to the top of the chart legend, and the bar or area stack. Positive numbers sink the series to the bottom.
- Any series that you haven't explicitly given a custom order to use
order 0by default. Series with negative custom order values will be above them, and series with positive values below them.
orderkeyword is what assigns series order—not the order in which the series are referenced in your Customizer Script.
To illustrate some common ways of using custom series ordering: