GUI Reference: Management Reports

• Availability
• Scope
• Report Elements
• Metavariables
• Generating Reports
• Management Report Templates
• Permissions
• More

Availability

Management report functionality is available in the Reports sections of the GUI Home / Project Tree, Analysis, and Project pages.

The following annotated screenshot fragment shows the different parts of the expanded Reports section.

Scope

Each management report template is associated with one or more scopes. These scopes determine the set of information that will be included in the report, and which page or pages the template will be available from.

[*] The report contents can be refined from the starting points shown in this table by applying additional constraints to each report element, as described in the following section.

Report Elements

A report can contain multiple elements from any of several categories.

• Text
• Table
• Chart
• Repeating Section
• Other

Text

Arbitrary text (which may include metavariables) can be included throughout the report. The management report template editor provides a range of available formats; text elements are edited using the text editing dialog.

Table

As with tables in the CodeSonar GUI, tables in management reports present summaries of various hub information along with hyperlinks to corresponding search results.

The management report template editor provides a range of predefined tables. Functionality for customizing tables is provided by the table editing dialog, including:

• Adding or removing columns.
• Specifying qualitative and quantitative limits on the table's rows.
• Customizing the table title. This title will be used in any list of tables in the report.

Metavariables can be used in table titles, and in constraints specified on the rows and columns of the table.

Chart

As with charts in the CodeSonar GUI, tables in management reports present graphical summaries of various hub information along with hyperlinks to corresponding search results.

The management report template editor provides two predefined charts. Functionality for customizing charts is provided by the chart editing dialog, including:

• Changing the chart type.
• Changing the chart data (for example, because neither of the predefined charts covers the data you want).
• Specifying additional constraints on the chart data.
• Customizing the chart title. This title will be used in any list of figures in the report.

Metavariables can be used in charts titles, and in constraints specified on the chart data in the search tab of the chart editing dialog.

Repeating Section

One of the main building blocks of the management report tool is the repeating section (or just "section"). A repeating section in a report template defines structure and content for describing the properties of a single CodeSonar artifact: for example, one file, one analysis, or one project. When it generates a report from the template, CodeSonar will iterate over the set of files (analyses, projects) associated with the section, producing one instance of the templated section for each. By default, all files (analyses, projects) in the enclosing scope are iterated over: use the iterations tab of the section editing dialog to specify a different set. (For non-nested sections, the enclosing scope is the scope of the report; otherwise it is the scope of the section that is the immediate parent.)

Sections can contain any combination of report elements, including other sections. For example, a report could contain a repeating section that iterates over every analysis of a project, nested inside a repeating section that iterates over every project on the hub.

The management report template editor provides functionality for adding sections to a report template; functionality for customizing sections is provided by the section editing dialog.

Every section has a section metavariable that is available inside the section (including in any sections nested inside it)

We use the following terminology.

Other

Elements that do not fall into one of the previous categories are grouped under "Other" in the report elements menu of the management report template editor:

• Alerts
• List of Figures
• List of Tables
• Page Break
• Parse Log
• Table of Contents

Report Metavariables

Management report elements can make use of metavariables. These metavariables are referred to by name in report templates, then instantiated to concrete values when reports are generated.

• Metavariable names are delimited with double curly brackets {{...}}.
• The metavariables available for a management report template fall into two categories:
  • a standard set of global metavariables, and
  • a special section metavariable for every repeating section in the template.
• Metavariables can be used in several different contexts.
  • Inside any text element.
  • In the title of any table, chart, list of tables, list of figures, or table of contents.
  • To specify constraints on table columns and rows.
  • To specify constraints on repeating section properties and iterations.

Global Metavariables

The global metavariables are available at all locations in the report template.

For example, suppose a report template with project scope had the following paragraph text.

Then if user alex generates a report from this template, the corresponding report text will be (something) like the following.

Section Metavariables

Every repeating section has a corresponding section metavariable that is available inside the section (including any included sections).

Section metavariables differ from global metavariables in several respects:

• Availability: each section metavariable is only available inside the corresponding section (including any included sections).
• Naming: CodeSonar provides a default section metavariable name when a new section is created, but users can change this name in the section type tab of the section editing dialog.
• Complexity: each section metavariable has a set of fields that correspond to section properties. Section metavariables are always used in combination with field names. As with section metavariable names, field names can be modified from the section editing dialog - in this case, from the properties tab.

For example, suppose a project section included the following paragraph text.

Then if a user generates a report from this template, the corresponding report text will be (something) like the following.

(This example uses default project section properties.)

Generating Reports

In general terms, a management report is generated by

• applying a management report template
• to a concrete scope (a specific analysis, a specific project, the hub contents at a specific point in time)
• with a specified output format.

The process for generating a management report is outlined in Task: Generate a Management Report.

There are various options for disseminating a generated report.

          http://hub_location/report/<scope>-<template_id>.<ext>?<option_string>

Report Formats

Management Report Templates

A management report template specifies the abstract structure of a report: which elements it will contain, and in what order. Management reports are then generated by applying a template to a selected set of information.

CodeSonar ships with a set of predefined templates, and provides functionality for creating additional templates, editing existing template, and importing and exporting templates.

Predefined Templates

CodeSonar provides a set of predefined templates for common reporting scenarios.

Note that the predefined templates are protected from overwriting and are not securable resources. If you wish to make a template based on modifications to one of the predefined templates, specify a different name in order to save it.

Note on historic analyses

If an analysis was performed by a CodeSonar version from before mappings for a particular taxonomy were supported, the warnings issued by that analysis will not be associated with categories from that taxonomy. This means that if you create a warning class category report or warning class category severity report for that analysis and taxonomy, the warning class tables and charts will not contain any information.

To resolve this, you can re-analyze the same code with a newer version of CodeSonar that supports the taxonomy you are interested in, then create a report on the new analysis.

Permissions

CodeSonar permissions apply to management report templates and management report contents as follows.

More on Management Reports

• Management Report Template Editor Reference
• Management Report Tasks:
  • Create a new management report template
  • Edit an existing management report template
  • Generate a management report