Customizing Reports with Scripts

Overview

Dataplane Customizer Scripts allow you to programmatically customize the output of Dataplane's charts and tables.

A Customizer Script can be used to adjust the colors of charts, to change the axis range and titles, to sort tables, to adjust the display of statistics, and more. Future versions of Dataplane will permit users to perform even more detailed customization of the report generation process.

Customizer Scripts are entirely optional, but they provide an additional level of control to power users.

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:

Customizer Script Basics

Customizer Scripts are attached to individual Dataplane reports, and scripts can be modified when creating a new report or when editing an existing saved report. From either type of report, you access the Customizer Script by clicking the More Options link in the top right corner of the report configuration page:

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

From this point, the user can enter a Customizer Script in order to adjust the appearance of the chart. (The Dataplane Customizer Script language is based on 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.)

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, you can 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, you may also surround your comment with a pair comment markers ("/*" and "*/").

// 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.
 */

Using the Enhanced Script Editor

Through a new Dataplane Labs feature, users have the option of using an enhanced text editor to edit Customizer Scripts. The enhanced text editor is available to all users who are using a browser other than Internet Explorer.

The enhanced script editor includes the following features:

• syntax highlighting of customizer blocks, making it easier to understand your script and to see mistakes,
• line numbers, so that you can easily navigate your script,
• code folding, so that you can easily show and hide blocks within "{ }" braces, and
• a dynamically-resizable text area.

For example, depending on the quantity of customizations being performed, Customizer Scripts can sometimes get lengthy. If you ever make an error in a Customizer Script, the error will be reported based on the line number of the script that caused the error, so having a built-in line number reference can be very useful.

To use the enhanced script editor, simply enable the feature in Dataplane Labs. Users who are using Internet Explorer will always be shown the regular script editor, regardless of the configuration in Dataplane Labs.

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.