Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Info
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.
Panel

Table of Contents
maxLevel3

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

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
Info
  • 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)

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:

Image Removed

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:

Image Removed

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

Image Removed

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

...

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.

...

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:

Image Removed

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

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

Image Removed

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

...

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:

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

Image Removed

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

Image Removed

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:

Image Removed

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

Image Removed

  • Now choose your report template:

Image Removed

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

Image Removed

Info

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:

Image Removed

  • You should ensure that Microsoft Office is installed on the machine if you choose this output type.
  • This feature is not supported for outputting reports based on Microsoft Excel templates.

Portfolio based reports (version 1.4.0 and above)

Info

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:

Image Removed

  • Now choose your Category/Tag:

Image Removed

  • Now choose your report template:

Image Removed

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

Image Removed

Info

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:

Image Removed

  • You should ensure that Microsoft Office is installed on the machine if you choose this output type.
  • 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:

Image Removed

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

Image Removed

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

Image Removed

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

Image Removed

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

Image Removed

Info

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.

...

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:

Image Removed

...

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

Image Removed

Info

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:

Image Removed

...

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

Code Block
languagetext
%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:

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

Locate the following section in the file:

Code Block
languagexml
<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:

Code Block
languagexml
<level value="INFO" />

For example:

Code Block
languagexml
<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:

...

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

...

Code Block
languagetext
%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.

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

...

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
Info
Available in v. ≥ 1.11.0.

...

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.

Info

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.

...

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:

Image Removed

...

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:

Code Block
languagetext
-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.

...

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:

Code Block
languagetext
-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.

...

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

Code Block
languagetext
<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.

...

(error)

...

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.

...

Example

Application reports

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

Code Block
languagetext
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:

Code Block
languagetext
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:

Code Block
languagetext
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:

Code Block
languagetext
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:

Code Block
languagetext
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:

Code Block
languagetext
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

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

Code Block
languagetext
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.

...

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:

Code Block
languagetext
echo %ERRORLEVEL%

One of the following codes will be returned:

...

For example:

Image Removed

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:

Image Removed

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

Code Block
languagetext
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:

Code Block
languagetext
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).

Code Block
languagetext
%PROGRAMDATA%\CAST\ReportGenerator\<version>\Templates
Info
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.