Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
Overview
By adding a Dataplane Customizer Script to your report, you can modify many aspects of how charts are drawn in report results.
Tip |
---|
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.
A customizeChart
section can customize the chart series, domain categories, axes and more.
Code Block |
---|
customizeChart { // one or more chart-customization commands go here } |
Customizations that appear later in the Customizer Script override any earlier, matching customizations.
For example:
Code Block |
---|
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:
Code Block |
---|
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:
Code Block |
---|
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 } |
Anchor | ||||
---|---|---|---|---|
|
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:
Code Block |
---|
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:
Code Block |
---|
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 } |
Tip |
---|
For help with composing Java-style regular expressions, see this standard reference. |
Info |
---|
Both |
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:
Code Block |
---|
customizeChart { category "Technical task" name "Dev Task" category "Documentation" name "User Docs" } |
Anchor | ||||
---|---|---|---|---|
|
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:
Code Block |
---|
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:
Tip |
---|
|
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:
Code Block |
---|
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:
Code Block |
---|
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:
Code Block |
---|
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:
Series Segment 1 (Priority) | Series Segment 2 (Issue Type) | Series Name |
---|---|---|
P1 | Bug | P1 / Bug |
P2 | 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.
Code Block |
---|
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:
Code Block |
---|
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:
Code Block |
---|
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".
Code Block |
---|
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:
Code Block |
---|
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
Image Modified
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:
Code Block |
---|
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:
Code Block |
---|
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:
Code Block |
---|
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:
Code Block |
---|
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" } |
Anchor | ||||
---|---|---|---|---|
|
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".
Code Block |
---|
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:
Tip |
---|
|
To illustrate some common ways of using custom series ordering:
Code Block |
---|
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 } |
Panel | |
---|---|
Page Contents
|