Summary: this page describes how to use the standalone CAST Report Generator to generate PowerPoint or Word documents containing data generated by CAST.

What is the CAST Report Generator?

The CAST Report Generator is a standalone solution for automatic generation of reports based on data generated by CAST. The solution provides the opportunity (for example) to prepare and automate assessments for each new version of application analyzed with CAST. Documents are based on Microsoft Office templates and they can be modified to prepare a specific template to meet a particular use case or to comply with a company format. After generation, the resulting document can be further adapted if necessary.

The Report Generator is based on the CAST RestAPI meaning that CAST AI Administrators and project managers alike can use the tool. The following video provides an overview: https://player.vimeo.com/video/85837301.

How does it work?

The CAST Report Generator is a standalone application that is delivered separately from CAST AIP. It interacts with the data stored in the CAST Dashboard Service schema (and also the CAST Measurement Service schema - see note below however) via the CAST RestAPI to produce various Word and PowerPoint reports from predefined or custom templates. As such, to use the CAST Report Generator you must already have one of the following set up on your local network to connect to one or multiple CAST Dashboard Services/Measurement Services populated with at least one Application and snapshot.

CAST RestAPI
CAST Engineering Dashboard
CAST Health Dashboard
CAST Engineering/Health Dashboard combined

Whilst it is possible to configure the CAST Report Generator to interact with a CAST Measurement Service schema (in particular this is required if you would like to generate Portfolio templates available in v 1.4.0 and above), you should be aware that the following components are not currently consolidated into the Measurement Service schema, thus potentially rendering reports (other than Portfolio templates which are designed for Measurement Service schemas) incomplete. These components all function correctly when a Dashboard Service schema is configured:
- CAST_COMPLEXITY
- CAST_DISTRIBUTION
- TOP_RISKIEST_TRANSACTIONS
- TOP_RISKIEST_COMPONENTS
- ACTION_PLANS
- ACTION_PLANS_VIOLATIONS
- CAST_COMPLEXITY_WITH_VIOL
- IFPUG_FUNCTIONS (≥ v. 1.3.0)

Note also that accessing the data in a CAST Dashboard Service requires a specific license key. Please see CAST-AED-RESTAPI - Dashboard Service license key configuration for more information.

Limitations

Report Generator with embedded Dashboards provided by CAST Console ≥ 2.x

It is not currently possible to use CAST Report Generator with embedded Dashboards provided by CAST Console ≥ 2.x. If you need to use CAST Report Generator and you are using Console ≥ 2.x, you will need to deploy a standalone Dashboard to interface with the required schemas. Embedded and standalone Dashboards can co-exist.

Release Notes

Please see CAST Report Generator - Release Notes for more information about each release:

New components added
New features added
Bug fixes

Download and installation process

Please see CAST Report Generator - Installation process for more information about:

How to obtain the CAST Report Generator
Installation prerequisites
Installation process

Launching CAST Report Generator

Once installed, CAST Report Generator can be launched from the Windows Start menu as follows:

Update check

During CAST Report Generator start-up, a check is made to see whether the current release of CAST Report Generator is the most recent. If a newer release is available, a link to CAST Extend will be provided in the Messages panel, allowing you to download the new update:

If CAST Extend is not accessible, this will also be logged in the Messages panel.

Configuring access to the data

Configuring access to the data in the Dashboard Service can be achieved as follows:

In the CAST Report Generator UI, enter the URL of your CAST RestAPI installation with /rest appended to the end (for example: http:server[:port]/RestAPI/rest) into the Web Service field:

In CAST Report Generator ≥ 1.17, it is no longer necessary to add the /rest suffix. If this is omitted, it will be added automatically by the GUI.

You now have a choice of authentication method - if in doubt you should use the Username/password option:

Username/Password

Enter your username and password for the CAST RestAPI deployment - depending on the authentication mode configured by the CAST AI Administrator - you need to login with a presupplied username and password or your corporate username and password. If in doubt, contact your CAST Administrator.

API Key (available in v. ≥ 1.11.0)

If your CAST RestAPI deployment is deployed with SAML authentication mode enabled, then CAST Report Generator cannot authenticate using the traditional Username/password option. Instead, tick the API Key option and enter the appropriate username and the API Key in the Password field:

Contact your CAST Administrator to provide the API Key - see also RestAPI authentication using an API key.

SAML is not supported for connections to the dashboard RestAPI made via CAST Report Generator in v. ≤ 1.10.0)

Click the Validate button to test the connection.
Validation test results will then be displayed in the right hand Messages panel:

Ensure that the validation is successful. You are now connected and can generate reports.

Note that:

From v 1.10.x:
- CAST Report Generator will no longer store the credentials of the RestAPI service configured in the GUI. This means that for every new session of Report Generator, credentials must be entered before reports can be generated.
- The field "User" in the list of connections will no longer be displayed:

Distinguishing between identical Applications on Measurement and Dashboard Service schemas

When the same Application is present in a Measurement Service schema and in a Dashboard Service schema, the following sections present how the Report Generator deals with this situation. This may occur in the following situations:

You have input a single RestAPI URL that points to a WAR using the "combined" AAD-AED or HD-ED WAR file and have configured (in the context.xml) both a Measurement Service and Dashboard Service on the same RDBMS and where the same Application is present in both databases
Any other situation where the same Applications are present in a Measurement Service schema and in a Dashboard Service schema and you have input URLs to RestAPI installations where those databases have been configured for access (in the context.xml)

Applicable to Report Generator ≥ 1.15.x

Applications that are present in the Measurement Service schema are not offered for selection. This is because certain data is not present in the Measurement Service schema (see note at the start of the page) thus potentially rendering reports incomplete. Portfolio templates (which are designed for Measurement Service schemas) will function normally.

Applicable to Report Generator 1.5.x - 1.14.x

The CAST Report Generator will offer the same Applications TWICE (one from the Dashboard Service database and a Measurement Service database), but the Application name will be prefixed with the "domain" name (as configured in the context.xml file in the RestAPI). Typically, "AED" is the domain used for Applications in the Dashboard Service database and "AAD" is the domain used for Applications in the Measurement Service database, but custom "domain" names can also be configured and the CAST Report Generator will use these. This allows you to select the correct Application knowing that Applications/Snapshots in the Measurement Service database do NOT include as much information as those in the Dashboard Service and therefore some templates used with a Measurement Service database may return errors:

Applicable to Report Generator ≤ 1.4.x

The CAST Report Generator will offer the same Applications TWICE (one from the Dashboard Service database and a Measurement Service database), but the Report Generator is not able to distinguish between the two and you may find that parts of your generated report are not complete due to having selected an Application/Snapshot in the Measurement Service database which does not contain all data (contrary to an Application/Snapshot in the Dashboard Service database):

Generating reports

The CAST Report Generator is supplied with several predefined Word and PowerPoint templates that you can use as a basis for your reports. To generate a report:

Application based reports

First you must ensure that you are working in the Application tab:

Now choose your Application and Snapshots using the drop down lists. Note that it is not necessary to select a "previous" snapshot unless you need to compare two snapshots:

Now choose your report template:

Finally click the Generate Report button and choose a name and location for the report (the default suggested name will be the same as the template file name selected to generate the report).
The CAST Report Generator will then generate the report based on the data stored in the CAST Dashboard Service database and save it to the chosen location.
On completion, the Messages panel will display a link to the report - click this to open the report and view the contents:

Note that in release ≥ 1.8.x, you can save a report as a PDF file, rather than having to use the same file format as the chosen template. To do so, change the file extension to .PDF in the save dialog box:

You should ensure that Microsoft Office is installed on the machine if you choose this output type (the Microsoft Office runtime is used for this process) - if this is not the case, the report will be generated in Microsoft Office format.
This feature is not supported for outputting reports based on Microsoft Excel templates.

Portfolio based reports (version 1.4.0 and above)

Note that Portfolio based reports require that you:

have configured a web service that connects to a Measurement Service database
have configured some custom Categories/Tags in the CAST HealthDashboard - see HD - Tag and category management

First you must ensure that you are working in the Portfolio tab:

Now choose your Category/Tag:

Now choose your report template:

Finally click the Generate Report button and choose a name and location for the report.
The CAST Report Generator will then generate the report based on the data stored in the CAST Measurement Service database and save it to the chosen location.
On completion, the Messages panel will display a link to the report - click this to open the report and view the contents:

Note that in release ≥ 1.8.x, you can save a report as a PDF file, rather than having to use the same file format as the chosen template. To do so, change the file extension to .PDF in the save dialog box:

You should ensure that Microsoft Office is installed on the machine if you choose this output type (the Microsoft Office runtime is used for this process) - if this is not the case, the report will be generated in Microsoft Office format.
This feature is not supported for outputting reports based on Microsoft Excel templates.

Multiple Rest API installations

The CAST Report Generator can be configured to interact with more than one Rest API installation if required. This is simple to achieve using the CAST Report Center UI:

Click the Options button and select WebService Configuration as shown below:

This option will take you to the following UI that enables you to view and configure the list of Web Service connections that are available to the CAST Report Generator:

We can see that the initial connection we first entered is already listed and the Active option is set to "True" meaning that the CAST Report Generator will always use this connection when generating reports.
To add an additional connection, enter the URL in the Web Service field, and enter the appropriate login and password, then click the Validate button:

If the new connection is successfully validated (check the Messages panel) it will be listed in the Web Service table:

Note that the Active column contains "False" for the new connection. If you want to generate reports using this new connection you first need to activate it by selecting the connection and then clicking the Active button. The connection will then become the Active connection for all report generation:

Note if you delete ALL existing Web Service configurations and then add a new one, this new configuration will NOT be Active by default and you will need to manually make it active before you can generate reports.

Templates

The CAST Report Generator is supplied with a set of pre-defined templates. You can find out more information about templates and report output options in CAST Report Generator - Templates and output options.

Options

The CAST Report Generator contains a small set of configurable options that:

ability to change the location for the storage of Templates (see Changing the template storage location)
provide access to GUI localization in English, French, German, Spanish, Italian and Chinese Simplified (zh_CN)
define the thresholds for the APPLICATION_SIZE_TYPE and APPLICATION_QUALITY_TYPE placeholders (see the base templates for more information)

You can access the Settings menu by clicking the menu option in the upper left, then selecting Settings:

GUI localization

Choose the language you prefer, then click Save to apply the changes. The chosen language will then be used:

in the GUI
for log messages
for some aspects of the generated report

Note that when Chinese (Simplified, PRC) is selected, the following also occurs:

The path to the templates will be changed to %PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates\zh_CN so that Chinese language specific templates are used instead of the default English language templates. Note that these templates have NOT been translated into Chinese, but the option is now available for manual translation.
The Report Generator will request all Assessment Model information in Chinese (Simplified, PRC), i.e. any reports that are generated will contain rule descriptions in Chinese (Simplified, PRC).

Thresholds

Use these options to define the thresholds for the APPLICATION_SIZE_TYPE and APPLICATION_QUALITY_TYPE placeholders (see the base templates for more information). Click Save to apply the changes:

Log files

The CAST Report Generator saves a log of all interactions with the CAST Dashboard Service in the following location (one log file per day is generated):

%PROGRAMDATA%\CAST\ReportGenerator\<version>\<ReportGenerator_YYYYMMDD>.log

Configuring log verbosity

By default, the log files are set to "INFO" level verbosity, but you can change this if necessary. Open the following file with a text editor:

%PROGRAMFILES(x86)%\CAST\<version>\ReportGenerator\log4net.config

Locate the following section in the file:

<root>
    <!--
      ALL or DEBUG : Display all messages which are typed DEBUG, INFO, WARN, ERROR or FATAL
      INFO         : Display all messages which are typed INFO, WARN, ERROR or FATAL
      WARN         : Display all messages which are typed WARN, ERROR or FATAL
      ERROR        : Display all messages which are typed ERROR or FATAL
      FATAL        : Display all messages which are typed FATAL
      OFF          : Display no messages
    -->
    <level value="INFO" />

Change the following line to match the verbosity level you require:

<level value="INFO" />

For example:

<level value="DEBUG" />

When complete, save the file and then restart the CAST Report Generator for the new log configuration to be taken into account.

Command line interface

The CAST Report Generator has a command line interface which you can use to automate the generation of your reports. The command line interface is provided by the following executable which can be located in the ReportGenerator folder at the root of the CAST installation folder:

≥ 1.13.0	%PROGRAMFILES(X86)%\CAST\ReportGenerator\<version>\CastReporting.Console.Core.exe
≤ 1.12.0	%PROGRAMFILES(X86)%\CAST\ReportGenerator <version>\CastReporting.Console.exe

Direct commands

You can use tool by launching it with the following parameters - CAST recommends using a batch file to do so.

Note the Usage column refers to the type of report that is being generated: Application or Portfolio. Common refers to options that are used with both report types.

Command	Usage	Description
-webservice <ws_name>	Common	URL of your CAST RestAPI installation in the form: http://<server>:<port>/<APIWAR>/rest
-username <username>	Common	The username that grants you access.
-password <password>	Common	The password corresponding to the -username
-apikey true\|false	Common	If you have enabled SAML authentication mode for your CAST Dashboard/RestAPI deployment, you will need to use an API Key instead of a password. To do, so you will need to modify the command line as follows: add the -apikey true option (the default when the option is omitted is false) enter the API Key in the -password option Available in v. ≥ 1.11.0.
-template <template_name>	Common	Required template file name for document generation surrounded by double quotes
-file <output_file>	Common	Generated output file name surrounded by double quotes. If this option is omitted, the command line will generate a generic file name that includes the date and time the file was generated. Note that: In release < 1.8.0 you should always use the same file extension as the chosen template. In release ≥ 1.8.0 you can output the report to PDF by using a .PDF extension for the output file name. You should ensure that Microsoft Office is installed on the machine if you choose this output type. Note that this feature is not supported for outputting reports based on Microsoft Excel templates.
-culture	Common	Choose from one of the following locales (you can also use the first two characters (e.g.: fr for fr-FR) fr-FR en-US es-ES IT-it DE-de zh-CN This will force the resulting report to be generated with some aspects matching the chosen language:
-application <app_name>	Application	Application name containing data for document generation.
-snapshot_cur <application_name - current_snapshot_version>	Application	An optional command enabling you to specify a particular snapshot as the "current" snapshot. Ensure that you use the <application_name - current_snapshot_version> format for specifying the snapshot, for example: -snapshot_cur Arizona - V2.0.1 Note that this command is optional - if you omit it, the most recent snapshot is set as the "current" snapshot.
-snapshot_prev <application_name - prev_snapshot_version>	Application	An optional command enabling you to specify a particular snapshot as the "previous" snapshot. Ensure that you use the <application_name - current_snapshot_version> format for specifying the snapshot, for example: -snapshot_prev Arizona - V1.0.0 Note that this command is optional - if you omit it, the snapshot prior to the most recent is set as the "previous" snapshot.
-domain <domain_name>	Application	Name of the domain containing the required application (optional). This option can be used to distinguish multiple Applications that have the same name, but are stored in different domains. The domain name can be found in the context.xml file for the target RestAPI installation. For example, in the following context.xml, the name attribute contains the domain name "AED": <Resource name="jdbc/domains/AED" url="jdbc:postgresql://AMLWCH:2280/postgres" connectionInitSqls="SET search_path TO v836_1704_central;" username="operator" password="CastAIP" auth="Container" type="javax.sql.DataSource" driverClassName="org.postgresql.Driver" validationQuery="select 1" initialSize="5" maxTotal="20" maxIdle="10" maxWaitMillis="-1" /> Note that: you can also use -database to distinguish Applications with the same name. in ≥ 1.15.x, if the -domain option is not specified in the command line, Report Generator will only consider Applications stored in the Dashboard Service schema.
-database <db_name>	Application	Name of the database/schema name containing the required Application (optional). This option can be used to distinguish multiple Applications that have the same name, but are stored in different database/schemas. Note that you can also use -domain to distinguish Applications with the same name.
-reporttype portfolio	Portfolio	Use this command if you want to generate a report for a Portfolio, rather than an Application. When using this option, it must be always be first. See examples below.
-category <category name>	Portfolio	When using the -reporttype option, use this option to choose the category for the report.
-tag <tag name>	Portfolio	When using the -reporttype option, use this option to choose the tag for the report.

Example

Application reports

Generate an Application based report using the 1 - Powerpoint-components-library.pptx template for the eCommerce Application:

CastReporting.Console.Core.exe -webservice http://<server>:8080/<APIWAR>/rest -username cast -password cast -application eCommerce -template "1 - Powerpoint-components-library.pptx" -file "output_report.pptx"

Generate an Application based report using the 1 - Powerpoint-components-library.pptx template for the eCommerce Application using specific historic snapshots:

CastReporting.Console.Core.exe -webservice http://<server>:8080/<APIWAR>/rest -username cast -password cast -application eCommerce -template "1 - Powerpoint-components-library.pptx" -snapshot_cur Arizona - V2.0.1 -snapshot_prev Arizona - V1.0.0 -file "output_report.pptx"

Generate an Application based report using the 1 - Powerpoint-components-library.pptx template for the eCommerce Application using French language:

CastReporting.Console.Core.exe -webservice http://<server>:8080/<APIWAR>/rest -username cast -password cast -application eCommerce -template "1 - Powerpoint-components-library.pptx" -file "output_report.pptx" -culture fr-FR

Portfolio reports

Generate a Portfolio based report using the 1- Portfolio-Powerpoint-components-library.pptx template:

CastReporting.Console.Core.exe -reporttype portfolio -webservice http://<server>:8080/<APIWAR>/rest -username cast -password cast -template "1- Portfolio-Powerpoint-components-library.pptx" -file "output_report.pptx"

Generate a Portfolio based report using the 1- Portfolio-Powerpoint-components-library.pptx template with Category and Tag options set:

CastReporting.Console.Core.exe -reporttype portfolio -webservice http://<server>:8080/<APIWAR>/rest -username cast -password cast -template "1- Portfolio-Powerpoint-components-library.pptx" -category Business_Unit -tag Finance -file "output_report.pptx"

Generate a Portfolio based report using the 1- Portfolio-Powerpoint-components-library.pptx template with Category and Tag options set using French language:

CastReporting.Console.Core.exe -reporttype portfolio -webservice http://<server>:8080/<APIWAR>/rest -username cast -password cast -template "1- Portfolio-Powerpoint-components-library.pptx" -category Business_Unit -tag Finance -file "output_report.pptx" -culture fr-FR

Using an API Key

Available in v. ≥ 1.11.0.

Generate an Application based report using the 1 - Powerpoint-components-library.pptx template for the eCommerce Application via an API Key:

CastReporting.Console.Core.exe -webservice http://<server>:8080/<APIWAR>/rest -username cast -password myapikey -apikey true -application eCommerce -template "1 - Powerpoint-components-library.pptx" -file "output_report.pptx"

CLI log and return codes

CLI Log

When using the CLI, the standard log files will be used to record the action - see Log files for more information.

Return codes (available in ≥ 1.13.0)

When a CLI has completed, you can view a return code to quickly view the outcome of the action. Use the following command when the CLI action has completed:

echo %ERRORLEVEL%

One of the following codes will be returned:

0	Report successfully generated
1	Bad arguments given to the Report Generator
2	Web service cannot be accessed or is badly configured
3	Report failed

For example:

Using the parameters.xml file

Instead of defining the parameters directly in a batch file, you can launch the CastReporting.Console.Core.exe together with the parameters.xml file. A template parameters.xml file is located in the ReportGenerator folder at the root of the CAST installation folder, or can be downloaded here. The parameters.xml file can be configured to contain the commands you require:

Enter the required information in between the double quotes. The required information is the same as listed in the table above in the Direct commands section.

Example

CastReporting.Console.Core.exe parameters.xml

Converting output to PDF using the CLI

If you would prefer to view your reports in PDF format rather than Microsoft Office format, you can automate the transformation using a free command line tool called OfficeToPDF. For example:

officetopdf.exe report_file.docx report_file.pdf

This command line tool could be integrated into your CAST Report Generator batch scripts so that you have an automated solution to generate the reports (using CAST Report Generator) and then transform the resulting reports into PDF format (using OfficeToPDF).

In release ≥ 1.8.0 you can output the report directly to a PDF using the CAST Report Generator CLI by specifying a .PDF extension for the output file name defined with the -file option. You should ensure that Microsoft Office is installed on the machine if you choose this output type. Note that this feature is not supported for outputting reports based on Microsoft Excel templates.