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 AIP. The solution provides the opportunity (for example) to prepare and automate assessments for each new version of application analyzed with CAST AIP. 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.war
• CAST-Engineering.war
• CAST-Health.war
• CAST-Health-Engineering.war

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:

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

• 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.

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:

Portfolio based reports (version 1.4.0 and above)

• 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:

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:

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

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:

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

%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.

Command	Usage	Mandatory?	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 a 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

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:

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

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).

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