General

GUI Reference: Management Report Template Editor

Define new templates for management reports to display information from the CodeSonar hub, modify existing management report templates.

Management Reports are available for all analyses, independent of the language or languages involved.

Important Note: the CodeSonar Web GUI makes extensive use of JavaScript. Make sure JavaScript is enabled in your web browser.

Navigating to

From... Action Initial Editor Contents
Analysis Expand the Reports section and click new (on the Report Template line). An empty management report template, with "Analysis" scope selected.
Expand the Reports section, select a template name from the pull-down menu, and click edit (on the Report Template line). The template for the selected report. Note that the menu only lists templates with "Analysis" scope.
Home Expand the Reports section and click new (on the Report Template line). An empty management report template, with "Latest Analyses" scope selected.
Expand the Reports section, select a template name from the pull-down menu, and click edit (on the Report Template line). The template for the selected report. Note that the menu only lists templates with "Last Analyses" or "All Analyses" scope.
Project Expand the Reports section and click new (on the Report Template line). An empty management report template, with "Latest Analyses" scope selected. selected.
Expand the Reports section, select a template name from the pull-down menu, and click edit (on the Report Template line). The template for the selected report. Note that the menu only lists templates with "Project" scope.
By URL: http://hub_location/report/template/ An empty management report template, with no scope setting.

Page Properties

Output formats JSON
Visibility Filter Applied none
RBAC Permissions Needed
Page AccessREPORTTEMPLATE_READ
Page Contents/FunctionalityANALYSIS_EXISTS
PROJECT_EXISTS

Page Contents

The following annotated screenshot fragment shows the different parts of the report template editor.

annotated screenshot: Report Template Editor, annotated toolbar toolbar report element menu editing panel editing panel Standard footer

Standard Header See GUI Reference: Standard Header.
Breadcrumbs Home > Report Template : Template_Name
Home > Report Template
Depending on whether or not the whether a template is currently open in the editor, where
  • Home links to the GUI Home page,
  • Template_Name is the name of the report template being edited.
Toolbar Provides functionality for managing the template as a whole. See full details below.
Editing Panel Displays the current template contents, and allows users to add, remove, and edit template elements. See full details below.
Report Element Menu Provides functionality for adding elements to the report template. See full details below.
Standard Footer See GUI Reference: Standard Footer.

Toolbar

The toolbar provides functionality for managing the template as a whole.

annotated screenshot fragment: report template editor toolbar

save controls To save the template, enter a name in the Template Name field and click Save.
  • If there is an existing user-defined template with the same name, CodeSonar will display a message in the toolbar:
    Template "<template_name>" exists. Click here to overwrite.
    (where <template_name> is the name you specified). Either click the provided link to overwrite the previous template, or enter a different name in the Template Name and click Save again.
  • If one of the CodeSonar predefined templates has the same name, CodeSonar will display a message in the toolbar:
    The name "<template_name>" is reserved, please use a different name.
    Choose a different name for the template, enter it in the Template Name and click Save again.

If a template is currently being edited, a Delete Template button is also available.

  • Deletion removes the template from the hub. CodeSonar will display a dialog asking you to confirm before proceeding with deletion.
  • Delete Template functionality applies to the template currently being edited: check the confirmation dialog to confirm that the name of the template to be deleted matches your expectations.
  • If the template has previously been exported to a JSON file, it can be imported back into the hub and saved if required.
See Management Reports: Permissions for details of the permissions required to save and delete templates.
permissions key link [Only available if a template is currently open in the editor.]
Click to navigate to the Report Template Role-Permissions page for the template.
template scope selectors Use the checkboxes to select one or more scopes for the template.

Note that all templates must have at least one scope (otherwise they will not be available from any location in the GUI). If you try to save a template with no scopes selected, an error message will be displayed.
Settings and Preview tabs The template editor provides two tabs with different views of the template.
  • Settings provides functionality for editing a template: the editing panel and report element menu.
  • Preview shows an example HTML report generated from the template. At the top left of the tab is a Preview for menu: use this to select the data to include in the example report. (If your hub contains no projects, there will be no data to populate any preview with. If your hub contains projects but no analyses, you will only be able to populate previews for templates with Project scope.)
In most cases you will spend the majority of your time in the Settings tab, perhaps with occasional switches to the Preview tab to check that the report is behaving as expected.

See Management Reports: Permissions for details of the permissions required to preview management reports.
Import and Export buttons CodeSonar provides template import/export functionality based on JSON files.

To export the current template to a JSON file:

  1. Click Export.
  2. CodeSonar will use the file saving functionality provided by your browser to export the template.
    1. Work through the file saving process to finish exporting your template.
    The file name will be <Template_Name>.json, where <Template_Name> is the name of the report template.

To import a template from a JSON file:

  1. Click Import.
  2. If you are currently editing a template and have unsaved changes, a dialog will ask if you really want to import a new template.
    • If you want to save your changes before proceeding:
      1. Click Cancel.
      2. Use the save controls to save your template.
      3. Start the import process again.
    • Otherwise:
      1. Click OK. Your changes will be discarded.
  3. CodeSonar will use the file loading functionality provided by your operating system to import the template.
    1. Work through the file loading process to finish importing your template.
  4. The loaded template will be displayed in the editor.
  5. Use the save controls to save the loaded template.

Editing Panel

The editing panel is located in the Settings tab. It displays the current template contents, and allows users to add, remove, and edit template elements.

Element Placeholders

Elements in the template are represented by element placeholders in the editing panel:

Text The full text of the element.
Table The table title, followed by a skeleton table that shows the table column headings and a small number of unpopulated table rows.
Chart The chart title, followed by a small image indicating the chart type.
Section A box that indicates the extent of the section, with a label of the form repeat for {{<varname>}} in <typename>, where <varname> is the section metavariable name and <typename> is the section type.
Alerts An "Alerts" heading, followed by a yellow box containing an alert icon alert icon.
Page Break A line across the page.
List of Figures The list title, followed by a representative list item with placeholder text "Level 1 Text".
List of Tables The list title, followed by a representative list item with placeholder text "Level 1 Text".
Parse Log The log title, followed by a skeleton parse log entry with a small number of unpopulated rows.
Table of Contents The table title, followed by a nested set of representative list items with placeholder text "Level 1 Text", "Level 2 Text", "Level 3 Text".

Add an element

To add a new element to the template:

  1. Scroll the editing panel until the location where you want to insert the new element is visible.
  2. Click the element name in the Report Elements menu.
  3. Drag onto the editing panel.
  4. Release the mouse button when the mouse is over the location where you want to insert the element.
  5. An element placeholder for your new element will be added to the editing panel.
  6. If the default element format is not suitable, follow the instructions for editing an element.

Remove an element

To remove an element from the template:

  1. Scroll the editing panel until the element placeholder is visible.
  2. Click the element placeholder to open its editing dialog.
  3. Click the Delete button at the bottom left of the dialog.

Edit an element

To edit an element in the template:

  1. Scroll the editing panel until the element placeholder is visible.
  2. Click the element placeholder to open its editing dialog.
  3. Make the required changes to the element.
  4. Click the OK button at the bottom right of the dialog.

Move an element

The editor does not currently support relocating template elements directly. If you wish to change the location of a template element:

  1. Remove the element from its old location.
  2. Add a new instance of the element to the new location.
  3. Edit the new instance, if necessary.

Element Editing Dialogs

The process for editing a report template element is the same for all elements: click the element placeholder to open an editing dialog, then use the dialog to make the required changes.

Editing dialogs have a common set of buttons.

Delete Remove this element from the template and close the dialog.
OK Accept the specified modifications and close the dialog.
Cancel Discard the specified modifications and close the dialog.

Editing dialog details: text | table | chart | section | other

Text Editing Dialog

The text editing dialog consists of an editing field plus the standard editing dialog buttons.

screenshot: text editing dialog

Note that clicking on the title of a table, chart, or section will not open the text editing dialog. Instead, it will open the relevant editing dialog for the table, chart or section. Use the options tab of that dialog to change the title.

Table Editing Dialog

The table editing dialog has four tabs: table type | columns | rows | options

table type
 The table type tab allows users to change the type of information displayed in the table.

screenshot: table dialog, table type tab

Table The items in the Table menu parallel those listed under Table in the Report Elements Menu.
In most cases you will not need to modify this setting: the menu is provided in case you have changed your mind about the required table type.
columns Each table type has a default set of table columns, and default labels to refer to those columns. The columns tab allows users to modify this set by adding, removing, and editing columns, and to specify custom field names to refer to columns.

screenshot: table dialog, columns tab

The tab has one subtab for each column currently included in the section, and an add column link for adding additional columns to the set. Each subtab has the following fields.

Column The information displayed in the column.
Label The associated column heading.
For This field is available only for counted Column selections and specifies (using a search language term that can include metavariables) constraints on which instances of the property should be included in the count. This setting is applied in combination with the Filter setting. See note on escaping search strings.
Filter This field is available only for counted Column selections and specifies (using a visibility filter setting) constraints on which instances of the property should be included in the count. This setting is applied in combination with the For setting.
Sort The overall ordering of table rows is determined by applying the Sort ordering specified in the leftmost subtab to the column governed by that subtab, then sorting within those results using the ordering specified in the next subtab, then the next, and so on.
rows
 The rows tab allows users to specify qualitative and quantitative restrictions on the set of rows that will be included in the table.

screenshot: table dialog, rows tab

The tab has the following fields.

Search The scope from which table rows can be obtained.
  • If the table is contained inside a section, the default scope will be restricted to the (innermost) containing section.
  • One or more of the options in the Search menu may be broader than the scope of the generated report (or of the containing section, if any). This can be useful if you want to include material that compares the projects and analyses covered by the report to other projects and analyses on the hub.
For This field is available only for table types that correspond to search domains, and specifies (using a search language term that can include metavariables) constraints on the rows to include in the table. See note on escaping search strings.
Filter This field is available only for table types that correspond to search domains, and specifies (using a visibility filter setting) constraints on the rows to include in the table.
Where Use this clause to specify constraints on table columns (as described in the columns tab). If the column whose values you wish to constrain is not present, you will need to add it with the add column link in the columns tab.

A WHERE constraint has the form:

lnum operator condition
where num is the 0-based index of the column of interest within the current table, and operator and condition are as defined in the search language applicable to the table. Note that this differs from the standard search language field-condition, by specifying the constraint with respect to a column index rather than a field-name.

Logical operators &, |, and NOT can be applied to combine multiple constraints.

Note: Index-based conditions mean that if you re-order your columns, you may need to modify your WHERE clause.
Limit An upper bound U on the number of rows in the table. If more than this many section elements satisfy the constraints specified by the Search, For, Filter, and Where fields, then CodeSonar will use the first U rows returned by the hub. (If Offset is specified: the first U elements from that offset.)
Offset A threshold T such that CodeSonar will leave the first T elements returned by the hub out of the table.
options Other display options for the table.

screenshot: table dialog,options tab

Title The title for the table: it will appear above the table in the final report. Can include report metavariables; in particular you may wish to use global metavariable {{T()}}.
Show warning comments [Warnings tables only]
Select to include warning notes in the table. The notes for each warning are displayed under the table row describing that warning. Only notes specified by the user are displayed: CodeSonar-generated history items describing user changes to Priority, State, Finding or Owner are not included.

Chart Editing Dialog

The chart editing dialog is heavily based on the the standard chart wizard, with the following exceptions.

Section Editing Dialog

The section editing dialog has four tabs: section type | properties | iterations | options

section type The section type tab allows users to change the section type, and to specify a custom name for the corresponding section metavariable.

screenshot fragment: section type tab of section editing dialog

The tab has Section and Variable Name controls.

Section The section type: options are a superset of those listed under Section in the Report Elements Menu.

In most cases you will not need to modify this setting: the menu is provided in case you have changed your mind about the required section type.
Variable Name If you do not want to use the default section section metavariable name, enter a new name in the text field.
properties By default, CodeSonar selects a small set of section properties, and chooses default metavariable field names to refer to those properties.

The properties tab allows users to modify this set by adding, removing, and editing properties, and to specify custom field names to refer to properties.

screenshot: section dialog, properties tab

The tab has one subtab for each property currently available in the section, and an add property link for adding additional properties to the available set. Each subtab has the following fields.

Property The section type property from which the section property is derived.
Refer to as The section metavariable field name to associate with this property.
For This field is available only for counted Property selections and specifies (using a search language term that can include metavariables) constraints on which instances of the property should be included in the count. This setting is applied in combination with the Filter setting. See note on escaping search strings.
Filter This field is available only for counted Property selections and specifies (using a visibility filter setting) constraints on which instances of the property should be included in the count. This setting is applied in combination with the For setting.
Sort The overall ordering of section iterations is determined by applying the Sort ordering specified in the leftmost subtab to the property governed by that subtab, then sorting within those results using the ordering specified in the next subtab, then the next, and so on.

To add a new property to the available set:

  1. Click add property.
    A new subtab will be added and selected, with initial default assignments for most fields.
  2. Select the name of your desired property from the Property menu.
  3. If you don't like the default field name provided for the property, enter a new name in the Refer to as field.
  4. If necessary, edit the For, Filter, and Sort fields to make any other changes you require.

To remove a property from the available set:

  1. Click the subtab for that property to select it.
  2. Click remove field.
iterations The iterations tab allows users to specify qualitative and quantitative restrictions on the set of section elements that will be iterated over.

screenshot: section dialog, iterations tab

The tab has the following fields.
Search The scope from which section elements can be obtained.
  • If the section is contained inside another section, the default scope will be restricted to the (innermost) containing section.
  • One or more of the options in the Search menu may be broader than the scope of the generated report (or of the containing section, if any). This can be useful if you want to include material that compares the projects and analyses covered by the report to other projects and analyses on the hub.
For A search language term that specifies constraints on the section elements that will be included in the set. The term can include metavariables. See note on escaping search strings.
Filter A visibility filter setting that specifies constraints on the section elements that will be included in the set.
Where Use this clause to specify constraints on section properties (as described in the properties tab. If the property whose values you wish to constrain is not present, you will need to add it with the add property link in the properties tab.

A WHERE constraint has the form:

lnum operator condition
where num is a 0-based index into the horizontal list of current properties, and operator and condition are as defined in the search language applicable to the property.

For example, the following screenshot fragment shows a Properties tab for a Projects section. The list of current properties is, in left to right order:

  • PID (index l0)
  • Name (index l1)
  • Description (index l2)

If an additional property were added via the add property link, its index would be l3, and so on.

screenshot: section dialog, annotated properties tab

For example, to restrict the iteration for this section to projects whose Description contains (case-insensitive) substring important, we could use the following WHERE clause.

l2:important
Note that this differs from the standard search language field-condition, by specifying the constraint with respect to a list index rather than a field-name.

Logical operators &, |, and NOT can be applied to combine multiple constraints.

Note: Index-based conditions mean that if you re-order your horizontal list, you may need to modify your WHERE clause.
Limit An upper bound U on the number of iterations of this section. If more than this many section elements satisfy the constraints specified by the Search, For, Filter, and Where fields, then CodeSonar will use the first U elements returned by the hub. (If Offset is specified: the first U elements from that offset.)
Offset A threshold T such that CodeSonar will leave the first T elements returned by the hub out of the iteration.
options Other display options for the section.

screenshot: section dialog, options tab

Title The title for the overall repeating section: it will appear before the first iteration of the section in the final report. Can include report metavariables; in particular, you may wish to use global metavariable {{S()}}.

Other Editing Dialogs

The Other report elements also have editing dialogs: Alerts | List of Figures | List of Tables | Page Break | Parse Log | Table of Contents

Alerts screenshot: alerts dialog
a text field The title for the Alerts element: it will appear before the table of alerts in the final report. Can include report metavariables.
For Analysis The analysis whose alerts will be displayed.

The menu contains one item for each analysis section that (transitively) contains the Alerts element. In many cases this means there will be exactly one menu item. Note that if there are no menu items, it means the Alerts element is not contained in an analysis section and will produce an error message in any generated report.
List of Figures screenshot: list of figures dialog
a text field The title for the list of figures: it will appear before the list in the final report. Can include report metavariables.
List of Tables screenshot: list of tables dialog
a text field The title for the list of tables: it will appear before the list in the final report. Can include report metavariables.
Page Break screenshot: report page break dialog
buttons only The page break edit dialog contains only Delete and Cancel buttons.
Parse Log screenshot: report parse log dialog
a text field The title for the Parse Log element: it will appear before the parse log in the final report. Can include report metavariables.
For Analysis The analysis whose parse log will be displayed.

The menu contains one item for each analysis section that (transitively) contains the Parse Log element. In many cases this means there will be exactly one menu item. Note that if there are no menu items, it means the Parse Log element is not contained in an analysis section and will produce an error message in any generated report.
Show All Select to include all parse log entries in the generated report; deselect to include only parse log entries for compiler invocations in which errors occurred.
Table of Contents screenshot: table of contents dialog
a text field The title for the table of contents: it will appear before the table in the final report. Can include report metavariables.

Escaping Search Strings

For a list of characters that must be escaped in search strings, see CodeSonar Search Languages: Escape Codes.

To escape metavariable values, use the esc filter. For example, suppose you are creating a repeating section with section metavariable {{directory}}. If you want the repeating section to contain a table or chart of directory warnings, you will need a warning search language query that matches all warnings in files whose path contains the directory path. It's important to escape any special characters that may appear in paths, so the query will look something like the following.

path:"{{directory.Path|esc}}"

or, equivalently,

path:"{{esc(directory.Path)}}"

Report Elements Menu

The report elements menu is located in the Settings tab. It lists all the elements that can be added to the report template. Menu items are organized into groups by type, as described in the following table.

  Menu Item Report Element

Text

See also Management Reports: Elements: Text.
  Heading 1 Large, left-justified heading text. Will be included in the table of contents (if one is included).
  Heading 2 Left-justified heading text, smaller than Heading 1.
  Heading 3 Left-justified heading text, smaller than Heading 2.
  Paragraph Left-justified body text.
  Title 1 Large, centered title text.
  Title 2 Centered title text, smaller than Title 1.

Table

See also Management Reports: Elements: Table.
  Analyses Analysis information, with one line for each analysis.
  Directories Directory statistics, where a directory is considered to be included in an analysis one or more analyzed files is located in that directory.
  Files File information, with one line for each file.
  Languages Language statistics, where a language is considered to be included in an analysis if one or more analyzed files have that language.
  Metrics Summary (Analyses) Metric summary table showing maximum, minimum, and average (mean) values for analysis-granularity metrics.
  Metrics Summary (Files) Metric summary table showing maximum, minimum, and average (mean) values for file-granularity metrics.
  Projects Project information, with one line for each project.
  Warning Classes Warning summary table: warning count for each warning class.
  Warning Categories Warning summary table: warning count for each warning category.
This differs from other warning summary tables in two important ways:
  • A warning can have zero or more categories, so some warnings may contribute to the counts in more than one row of this table.
  • You can restrict the set of table rows using a search language query or saved search in the Warning Categories search domain.
  Warning Findings Warning summary table: warning count for each finding.
  Warning Owners Warning summary table: warning count for each owner.
  Warning Priorities Warning summary table: warning count for each priority.
  Warning States Warning summary table: warning count for each state.
  Warnings Warning information, with one line for each warning.

Chart

See also Management Reports: Elements: Chart.
  Warnings by Class Bar chart showing warning count for each warning class.
  Warnings by File Bar chart showing warning count in each file.

Section

See also Management Reports: Elements: Repeating Section.
  Analyses A repeating analysis section.
  Files A repeating file section.
  Projects A repeating project section.

Other

The Other submenu contains options for adding additional infrastructure to the report, and for inserting supporting information about the analysis.
  Alerts A table of all alerts issued by an analysis (must be located inside an Analysis Section).
  List of Figures A list of all the charts in the report, in order of appearance. Each chart is listed by its title (as specified in the options tab of the chart editing dialog), with a link to the chart itself.
  List of Tables A list of all the tables in the report, in order of appearance. Each table is listed by its title (as specified in the options tab of the table editing dialog), with a link to the table itself.
  Page Break Inserts a page break in the report. (Affects PDF pagination; rendered as an element in XML.)
  Parse Log The parse log for an analysis (must be located inside an Analysis Section).
  Table of Contents An outline list of all Heading 1, Heading 2, and Heading 3 text in the report.

Troubleshooting

My preview or generated report contains an error message like the following.
The following error was found in the report template:
A valid analysis id from a parent section must be referenced.
This indicates that the template includes an Alerts or Parse Log element that is not contained in an Analysis section.
  1. Open the report template, if it is not already open.
  2. Scroll to the location of the Alerts (Parse Log) element.
  3. Insert an Analysis section directly above or below the Alerts (Parse Log) element, if one is not already present.
  4. Delete the Alerts (Parse Log) element.
  5. Insert a new Alerts (Parse Log) element inside the Analysis section.
My preview or generated report contains an error message like the following.
The following error was found in the report template:
'vname' is undefined
This indicates that the template refers to a metavariable {{vname}} that does not exist. There are several possibilities.
The Report Elements menu only offers two kinds of chart - I want to chart other data.
You can use the chart editing dialog to completely customize any chart.
  1. Insert a Warnings by Class chart in your report template.
  2. Click the chart placeholder to open the chart editing dialog.
  3. If necessary, change the chart type.
  4. Go to the data tab and make your desired modifications.
  5. Go to the options tab and change the chart title to reflect the updated chart contents.
  6. Make any other chart modifications you require.
  7. Click OK.
The Report Elements menu only offers three kinds of repeating section - I want a repeating section with a different section type.
You can use the section editing dialog to specify a different section type.
  1. Insert an Analyses section in your report template.
  2. Click the section placeholder to open the section editing dialog.
  3. Select a new Section type from the menu in the section type tab.
  4. Make any other modifications you require.
  5. Click OK.
The menu in the Reports section of the Home (Analysis, Project) page doesn't contain the template I want.

There are two possibilities.

More on Management Reports