CAST Report Generator - Templates and output options


Summary: this page describes how to work with the templates provided with CAST Report Generator and custom templates that may be created for your own purposes.

Introduction

Report Generator is supplied with a set of pre-defined templates which can be used as-is or adapted to your own needs. These templates are located here by default:

%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\Application\Compliance reports
%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\Application\Component library
%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\Application\Legacy reports
%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\Application\Sizing reports
%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\Portfolio
%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\zh_Hans\Application\Compliance reports
%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\zh_Hans\Application\Component library
%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\zh_Hans\Application\Legacy reports
%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\zh_Hans\Application\Sizing reports
%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\zh_Hans\Portfolio

Templates are taken from "%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\zh_Hans\..." when Chinese (Simplified, PRC) is selected in Settings > Language.

You can find a list of these templates in the Component documentation which is accessible from each Release Notes page.

Note that:


  • In older releases of CAST Report Geneator the %PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\zh_Hans is named %PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\zh_CN.
  • Some Application level templates provided in%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\zh_Hans have been translated into Chinese.
  • Portfolio level templates provided in %PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\zh_Hans\Portfolio have NOT been translated into Chinese and are instead provided in English.

Officially supported templates

CAST provides various templates that are officially supported. These templates include scores, transaction risks, propagated risks, trending, scan-by-scan comparisons, lists of critical violations, and lists of components that have the most impact if remediated. Officially supported templates are stored in :

%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\

Note that templates located in the following locations are not officially supported:

%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\Application\Legacy reports
%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\zh_Hans\Application\Legacy reports

Sample reports

There are a number of reports that have been generated with these templates. To see samples of some of these reports, please click  CAST Report Generator - Sample Reports.

Changing the template storage location

You can change the location that CAST Report Generator uses to store templates by modifying the Settings option and then clicking Save at the bottom of the page:

You must then ensure that you store the templates in a folder hierarchy starting with Application or Portfolio - if not, the Report Generator will not be able to find the custom templates. For example, if the new template storage location is set to:

D:\CAST\Templates

Then you should ensure that you create a folder hierarchy starting with Application or Portfolio. Templates can then be stored in any subsequent folder/subfolder, for example:

D:\CAST\Templates\Application\My Compliance Templates
D:\CAST\Templates\Portfolio\My Other templates
D:\CAST\Templates\zh_Hans\Application
D:\CAST\Templates\zh_Hans\Portfolio

Creating your own custom templates

It is relatively easy to create your own custom templates for generating bespoke reports: CAST provides "base" templates that provide an explanation of how to do so (for Microsoft Word, Excel and PowerPoint) and also contain a large set of placeholders (example data that can be extracted in text, graph and table format) that can be copied and then adapted as necessary. The "base" templates are stored in:

%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\Application\Component library
%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\zh_CN\Application\Component library

You can use these base templates as the basis for creating your own report templates - simply copy them, make your changes and then save them with a different name. Refresh the Report template section to view the new template:

You must ensure that any custom templates are stored in the following locations (assuming that you are using the default storage location) so that they can be found by Report Generator:

Any default or custom folder/subfolder of:

%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\Application
%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\Portfolio
%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\zh_Hans\Application
%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\zh_Hans\Portfolio

Using the Excel output options

The CAST Report Generator supports the generation of reports in Excel format, as explained below. A template called "3 - Excel-components-library.xlsx" is also available as standard for Application reports.

Reuse of Word and PowerPoint blocks

  • All table and text blocks can be re-used in Excel.
  • To use any block in Excel, prefix all definitions with RepGen:TEXT or RepGen:TABLE.
  • The data will be put on the exact location where the definition resides.

Limitations

Text blocks

  • Cells referencing a text block will have their content replaced with the actual value received from the REST APIs.
  • Style and format information will be preserved. Report Generator will try and generate numeric-type values when the data provided by the REST API is numeric; otherwise, the data will be inserted as text.
  • Formulas referencing “text block” cells will work as expected.

Table blocks

  • Report Generator inserts new lines starting from the line that contains the "RepGen:TABLE;BLOCK_NAME;options…" definition. Existing content below the "RepGen:" will not be overwritten.
  • Report Generator will not apply any style or format to inserted cells. However, Report Generator will try and generate numeric-type values when the data provided by the REST API is numeric; otherwise, the data will be inserted as text.
  • Formulas referencing cells that are part of the block template will not be updated.
  • As a result, it is recommended to reserve one worksheet per table block and insert formulas in one or more consolidation worksheets. Formulas referencing template cells should reference whole columns (e.g.: =SUM('raw_data_worksheet'!D:D)), or cell ranges that are large enough to address all data extracted from the REST APIs (e.g.: =SUM('raw_data_worksheet'!D2:D20000)).

Graph blocks

  • Graph blocks are not supported in Excel: only table and text blocks.

Block IFPUG_FUNCTIONS

This block will display the Transaction Functions and the Data Functions as listed below:

  • HEADER
    • NO: means there is no header displayed from the data from the REST API
    • YES: means that the header will be taken into account as stored in the REST API
  • TYPE
    • TF = Transaction Function display
    • DF = Data function display

Example:

Result:

Adding data inline with text - Word templates

To add a metric ID (for example) inline with text in a Word template, for example:

...proceed as follows:

  • Enter the text into the Word template
  • Where you want to display the data, switch to the Developer tab (1) and add in a Rich Text Content Control (2), which will be displayed as below (3):

  • Switch to Design Mode:

  • Right click the Rich Text Content Control and select Properties:

  • Enter the data you want to pull in the TAG field, then click OK to confirm. In this example, the total number of critical violations is being displayed using the following syntax: TEXT;APPLICATION_METRIC;ID=67011