KBEC-00154 - Registering a custom report

Summary

This article discusses how to make a custom report (not generated by ReportFactory or batch reports) show up in a project's Reports tab.

Solution

Use the 'registerReport' ec-perl API call to register the custom report. The properties set on report jobs drive the mechanism behind the Reports tab. There are Perl utility functions in ElectricCommander::ReportUtils that you can call to set these properties on any job. The report artifacts (for example, an HTML file) is expected to reside in the "artifacts" directory of the jobstep workspace.

Examples

The code below makes two calls to the 'registerReport' function:

• The first call registers the report using a grouping of type and date - This includes the report in the Reports tab and displays the report when the date is selected.
• The second call uses a grouping of type only - This is used to display the most recently dated report of that type, for example, when the type is selected in the tree index it will display the most recently dated report of that type (Note: In 3.6 only; earlier versions incorrectly display the oldest report).

use ElectricCommander;
use ElectricCommander::ReportUtils;

my $cmdr = new ElectricCommander();
$cmdr->abortOnError(0);
my $title = "$[Report Title]";
my $reportName = "statusReport.html";
my $url = "$[/myJobStep/workspaceName]/$reportName";

# Register the report in the project report tab
# Use a grouping of type and date - this will include the report in the report
# tab and display the report when the date is selected
my $myGroupings = { reportType => $title, reportDate => getReportTimestamp(),};
registerReport($cmdr, "$[jobId]", $url, $title, $myGroupings);

# Set parent level tree groupings (e.g. just reportType)
# Use a grouping of type only - this is used to display the most recently dated
# report of that type, e.g. when the type is selected in the tree index it will
# display the most recently dated report of that type
$myGroupings = { reportType => $title,};
registerReport($cmdr, "$[jobId]", $url, $title, $myGroupings);

If you want a different location for the 'artifacts' directory, use this snippet:

# Create and register an alternate artifacts directory
my $artifactsDir = "report-artifacts";
mkdir($artifactsDir);
registerArtifactsDirectory($cmdr, "$[jobId]", $artifactsDir);

Applies to