Adding Custom Reports

2 minute read

You can add custom reports to the Build Details page. Typically, the reports access the uploaded annotation file to present analysis of various aspects of the build. You must write a script/application that takes three arguments and produces an HTML/text output file.

The arguments are (in this order):

  1. Script name (the base name of the script)

  2. Cluster Manager build ID

  3. Directory where the annotation file is located. The filename with annotation is always build.xml. This is where the script writes its output files.

Generally, the script reads the build.xml file and creates a number of files. The first file it must create is the temporary HTML file. That file is named after the provided script name, followed by .html_tmp. This is where the HTML output is created. After the file is done, it is moved under the script name followed by .html.

If the file produces downloadable output (such as plain text), it produces a file named after the script name followed by .out_tmp (the temporary file where the file is created). After the file is created, it is moved under the script name followed by .out.

It is important that the script is well-behaved if failure occurs (for example broken XML). In this case, it must remove the temporary files so the Cluster Manager does not continue to show the Generating…​ state. CloudBees recommends generating an HTML output file (following the naming scheme above) that states the error, so users can learn of a failure.

Recommendation: Start generated output with a table element, which then may contain whatever is desired. To pick up common stylesheet settings, make the table and its cells of the mainWindow class.

Making Custom Reports Available to the Cluster Manager

To make the report available:

  1. Install the script/application in the <ECloud install>/<arch>/bin directory.

  2. Run the application ecaddcmreport with the following arguments (in this order):

  3. shortname (the name used internally to identify the report)

  4. label (the text to display in the UI to represent the report)

  5. commandline (the full path to the executable)

  6. wait flag (1 means the UI stalls the request to wait for the result file and 0 means the request returns immediately)

Known Issues

Due to an issue using wrapped Tcl applications from Windows Apache, tclsh is invoked with the script as the argument.