Creating custom reports

You can create custom reports and make them accessible in Insight. A report typically consists of

a single .tcl source file containing Tcl code required to perform build annotation analysis
the Tk code required to display the result in the Insight UI

For example, you can create a report to display the number of jobs that were run by each agent used in the build.

Use the following steps to create a custom report.

Create a Tcl script that uses CreateReport and ConfigureReport to declare and set attributes for a report. Use this format:

CreateReport name ?-<option> <value> ...?▼

Use the following options:

-command

Generates a text-only version of the report

-guicommand

Generates a GUI version of the report

-desc

Specifies a report

-requires

Specifies a list of anno detail levels required for the report. The list must be space-separated

-cleanup

Cleans up the state associated with the report. For example, when a new anno file is loaded

You must use at least one -command option and at least one -guicommand option. For example:

set report [CreateReport "MyCustomReport"]
ConfigureReport $report -desc "The report description \
a continuation of the report description."
ConfigureReport $report -requires {basic file waiting history}
ConfigureReport $report -command RunCustomReport
ConfigureReport $report -uicommand MakeCustomReportUI▼

Make sure the console version of the report returns the report results as a text string (do not merely print directly with [puts]).

If you are running the Insight GUI and you invoke a custom report that has no -guicommand, Insight will run the -command version, capture the output, and display it as raw text in the GUI.

Add the function to perform the analysis and display results to the Tcl script. The function is invoked with two arguments:
- The name of the widget that the function needs to create to display results
- The name of the variable that the function needs to update with progress information, from 0.0 to 1.0. This information controls the progress bar when the report is generated. The progressVar argument is optional
  proc CreateJobsByAgentReport {w progressVar} {
  ▼
  In addition to function arguments, a global variable anno is available for reports. This is a handle for the annolib object containing the build annotation information that is currently loaded in Insight. To access this information in your report, import the anno variable:
  
  global anno

Add Tcl code to perform the analysis on the annotation information.

Following is an example that shows how to forward iterate through all the jobs in the build, counting the number of jobs run by each agent:

array set count {}
set end [$anno jobs end]
for {set j [$anno jobs begin]} {$j != $end} {set j [$anno job next $j]} {set agent [$anno job agent $j]if { $agent ne "" } {if { [info exists count($agent)] } {incr count($agent)} else {set count($agent) 1}}
}▼

Following is the same example using reverse iteration:

array set count {}
set rend [$anno jobs rend]
for {set j [$anno jobs rbegin]} {$j != $rend} {set j [$anno job prev $j]} {set agent [$anno job agent $j]if { $agent ne "" } {if { [info exists count($agent)] } {incr count($agent)} else {set count($agent) 1}}
}▼

Write Tk code to display results.

Insight includes the [Tile] widgets and the [Tablelist] widget. For this report, a simple tablelist can display the results:

# The “count” array contains the number of jobs run by
# each agent.
# We create a simple tablelist (multi-column listbox)
# to display the results.

frame $w
ttk::label $w.label -text “Jobs by agent:” -anchor w
tablelist::tablelist $w.results -columns {0 “Agent”0 “Jobs run by this agent”
}  -height 10 -width 80 -borderwidth 1 -stretch end \-font TkDefaultFont -background gray98 \-stripebackground \#e0e8f0 \-labelcommand tablelist::sortByColumn
$w.results columnconfigure 1 -sortmode integer
grid $w.label -sticky ew
grid $w.results -sticky nsew
grid columnconfigure $w 0 -weight 1
grid rowconfigure $w 1 -weight 1

foreach agent [lsort [array names count]] {$w.results insert end [list $agent $count($agent)]
}
return $w}# end of procedure CreateJobsByAgentReport▼

Save the .tcl files that define your new report in one of the following directories.
- Linux:
  /opt/ecloud/ElectricInsight/reports $HOME/.ecloud/ElectricInsight/reports
  ▼
- Windows:
  C:\ecloud\ElectricInsight\reports $USERPROFILE\Electric Cloud\ElectricInsight\reports
  ▼
  At startup, Insight scans the above directories for .tcl files defining new reports and automatically includes the reports the next time that Insight starts. Reports that are saved in the above directories are available to all users running Insight. Reports in other locations are available to a single user only.
Click Tools > Reload reports.