Customizing Reports with Scripts

Overview

Dataplane includes a built-in scripting engine to allow for advanced, programmatic customization of reports.

These user-defined Customizer Scripts can adjust the color of chart elements, change the axis range and titles, sort tables, adjust the display of statistics, and much more. Future versions of Dataplane will permit users to perform even more detailed customization of the report generation process.

Dataplane Customizer Scripts are written in Groovy, which is a dynamic language for the Java Virtual Machine. However, you do not need to know Groovy to use Customizer Scripts, and Customizer Scripts need not be complex.

Adding Customizer Scripts to your Dataplane reports is entirely optional, but they provide an additional level of control to power users.

An Example Customizer Script

To demonstrate a simple example of a Customizer Script, assume that a user creates a report showing the number of issues associated with various development projects, using a standard Current Issue Values report. The report is segmented by both issue type and priority. By default, Dataplane assigns colors to each segment in the chart automatically.

Before doing any customization, the default chart looks like this:

The resulting chart is colorful, but to make trends easier to see, we want to change the colors so that Bugs and Feature Requests are easily distinguishable. The user flips back to the Configure tab on the report page, clicks the More Options link in the top right corner to enable the Customizer Script field, and then enters the following Customizer Script:

This script tells Dataplane to adjust the color of all segmentations for Bugs (with any priority) to be a shade of goldenrod (yellow) and all Feature Requests (with any priority) to be colored a shade of dark blue. After entering the Customizer Script and re-running the report, the output now looks like this:

This is much easier to understand. Now, suppose that P1 issues are very important, so we also want to visually distinguish P1 feature requests and bugs from the rest of the issues. The user can also apply this new coloring rule by making a slight change to the Customizer Script:

After applying this last change, we see that bugs and features are colored separately, but P1 issues of either type are rendered in a shade of red. All of this, and more, can be done with Customizer Scripts:

Adding a Customizer Script to Your Report

You may add a Customizer Script to any Dataplane report you create or edit. Each report's Customizer Script is used only by the individual report in which it is included.

To access a report's Customizer Script, click the More Options link in the top right corner of the report configuration page:

After clicking More Options, the Customizer Script editor is shown at the bottom of the report configuration page:

You can now start writing a Customizer Script in order to adjust the behavior and appearance of your report.

Customizer Script Syntax

A Dataplane Customizer Script generally looks like this:

customizeCOMPONENT {
    first customization command
    second customization command
    ...
}

Depending on what you are customizing, the first line could be "customizeChart" (to customize the series, the axes and more in the chart), "customizeTable" (to customize the results table), or any of the other options described below. This is called a customizer block.

If you wish to modify more than one aspect of the report output (such as performing adjustments to both the chart and the table) you can include multiple customizer blocks of different types in the script, or even multiple blocks of the same type.

If you wish to add comments inside your script so that you (or others) can better understand the content, write "//" at the beginning of a line, followed by as much text as you want on that same line. To write a comment that is longer than one line, instead surround your comment with a pair of comment markers ("/*" and "*/").

For example:

// This is a single line comment.

// This is another comment which has a "//" at the beginning of the line.
// Each comment in this form must start with a "//" on the same line.

/* This is a multi-line comment describing the script, which only has
   comment start and end markers at the very beginning and end of the comment.
 */

The Customizer Script Editor

The Dataplane Customizer Script editor includes a number of enhanced editing features to simplify composing scripts, including:

• syntax highlighting of customizer blocks, making it easy to understand your script and to see mistakes,
• line numbers, so that you can easily navigate your script, and
• code folding, so you may show and hide blocks within "{ }" braces.

Getting Started with Customizer Scripts

Dataplane Customizer Scripts have a wide range of uses in fine tuning Jira reports to match your organization's and team's view of the world.