Summary: this page describes how to use the standalone CAST Report Generator to generate PowerPoint or Word documents containing data generated by CAST AIP. |
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
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.
|
Please see CAST Report Generator - Release Notes for more information about each release:
Please see CAST Report Generator - Installation process for more information about:
Once installed, CAST Report Generator can be launched from the Windows Start menu as follows:
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 in the Dashboard Service can be achieved as follows:
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.
|
Note that:
|
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:
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.
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:
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):
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:
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:
|
Note that Portfolio based reports require that you:
|
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:
|
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:
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. |
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.
The CAST Report Generator contains a small set of configurable options that:
You can access the Settings menu by clicking the menu option in the upper left, then selecting Settings:
Choose the language you prefer, then click Save to apply the changes. The chosen language will then be used:
Note that when Chinese (Simplified, PRC) is selected, the following also occurs:
|
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:
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 |
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.
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 |
| |
---|---|---|
≤ 1.12.0 |
|
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 | 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:
| ||
-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.
| ||
-culture | Common | Choose from one of the following locales (you can also use the first two characters (e.g.: fr for fr-FR)
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:
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:
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":
Note that:
| ||
-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. |
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 |
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 |
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" |
When using the CLI, the standard log files will be used to record the action - see Log files for more information.
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:
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.
CastReporting.Console.Core.exe parameters.xml |
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 |
In release ≥ 1.8.0 you can output the report to a PDF by using 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. |