This documentation is no longer maintained and may contain obsolete information. You should instead refer to Advanced onboarding - snapshot generation and validation.
Generate the snapshot
To generate a snapshot, you need to use the Execute tab in the Application editor:
A wizard will then be displayed enabling you to set the various date and naming options if required:
Click to enlarge
- The initial General Information wizard page enables you to select:
- Capture Date - by default the current date will be pre-selected. If you wish to pre or post date your Snapshot, please select the correct date in the calendar. Note that you can also choose the time (24 hour clock applies) using the fields underneath the date selector. When complete, the Capture Date will be displayed as follows: DD/MM/YY HH:MM
- Label - by default, the label will be predetermined by the CAST Management Studio, based on the date and time the wizard is opened. You can, however, enter your own label - but remember that the label is displayed in the CAST dashboards. Note that if you change the Capture Date, then the Label will not automatically update - if you wish to retain a date based label, you need to update it manually.
- Application Version - by default, the CAST Management Studio will enter the current version name, however you are free to change this if necessary.
- Once all the fields have been filled in to your satisfaction, click Next to continue. The Execution Options screen will then be displayed:
- This page enables you to select:
- Skip Application Analysis - if you have already executed the analysis as suggested in Run the Analysis, then you can tick this option to save valuable time.
- Ignore Empty Module - Yyu should leave this unticked (please see the CAST Management Studio help for more information)
- Send mail report (if configured) - Leave this ticked.
- Upload Snapshots to Measurement Service (if configured) option will be selected by default. This option ensures that the data is uploaded to the Measurement Service for use in the Health Dashboard when a snapshot has been successfully generated.
- If you are generating a first snapshot during an application on-boarding, CAST recommends that you deactivate the Upload Snapshots to Measurement Service (if configured) option. This will avoid unwanted or incorrect information being uploaded to the Health Dashboard.
- If this initial snapshot generation is successful you can manually upload the results to the Measurement Service without needing to re-generate the snapshot: see the section below entitled Upload snapshot data to the Measurement Service.
- Click Finish.
- The CAST Management Studio will then automatically generate a snapshot for the current Application.
- When complete, you should see a step-by-step list of the action's processes in a dialog box:
Please note that CAST supports concurrent snapshot generation on the same workstation (whether through GUI/CLI) with the following conditions:
- only one active execution for a given application/triplet should be run at any one time
- you should ensure that you configure application/triplet specific values for the following CAST locations:
- TEMP (User's temporary path)
This can be achieved by:
- defining an application/triplet specific Windows environment variable (for example %APPLICATION%)
- using this Windows variable in the CastGlobalSettings.ini file (ensuring you uncomment the variable in the CastGlobalSettings.ini file)
- changing the Windows variable path each time you generate a snapshot for a specific application/triplet
For example, set the following in the CastGlobalSettings.ini file:
Snapshot currently in progress
When a snapshot fails, or when it is cancelled by clicking on the Cancel button when the snapshot is running, this means that the Dashboard Service schema will be left in an inconsistent state. When the Take a snapshot option is next used, a pop-up will be displayed, asking whether you want to continue or delete the snapshot in progress:
You should proceed as follows:
- If the snapshot was interrupted due to an error, then you must ensure the Continue execution of currently running snapshot option is not ticked, then click Finish. This will delete the interrupted snapshot.
- If the snapshot was interrupted because the Cancel button was clicked when the snapshot was running, ensure that the Continue execution of currently running snapshot option is ticked, then click Finish. This will continue processing the interrupted snapshot.
"Application X" needs to be analyzed before taking the snapshot
If you receive the warning displayed above when attempting to generate a snapshot there are two possibilities:
- If this is the first time you have generated a snapshot and the job has not previously been analyzed, then the "Skip Analysis Job" option (available in the options wizard displayed when you generate a snapshot) will mean the snapshot is generated without the analysis having been run first. This can lead to incomplete results. Ensure you untick the "Skip Analysis Job" if the job has not previously been analyzed on its own.
- If you receive this warning and your job HAS previously been analyzed, then it is likely that the LISA, LTSA and Log preferences (which are used in an analysis) have changed. This may occur if you are running the CAST Management Studio on an entirely different workstation. If this is the case then the CAST Management Studio will consider that the configuration has changed and will treat the analysis jobs as not having previously been run. In this situation CAST recommends that you untick the "Skip Analysis Job" option before you continue with the snapshot generation.
Performance issues when using an Oracle Server host for the CAST AIP schemas
If you encounter performance issues when generating a snapshot using CAST AIP schemas hosted on an Oracle Server, CAST recommends that you consider making the following changes to force the use of the ALL_ROWS optimizer mode instead of the default RULE mode:
Add the following to the globallysharedsettings.ini file: (located here: %PROGRAMDATA%\CAST\CAST\<version>):
Add the following to the CAST-MS.l4j.ini file (this file does not exist by default therefore you must create it in the root CAST AIP installation folder):
Restart the CAST Management Studio
Restart the CAST Management Studio before you attempt to generate the snapshot again.
Check the snapshot results
The easiest and quickest way to check the results of a snapshot generation is to open the Engineering Dashboard and view your results. If you don't have one set up yet (or your licensing agreement does not allow you to install one), you can invoke the "on the fly" Engineering Dashboard by clicking the Open Engineering Dashboard option in the CAST Dashboard Service editor:
When using the option you will be prompted for credentials to access the dashboard: admin/cast (case-sensitive). Note that this user has the ADMIN role only - see ED - Configuring user authentication.
Tips for checking the results
Detect any third party libraries, generated code or code that is not maintained by the project
- Impact: This source code is not important for the project, because project can't do anything regarding it. It is better to exclude it.
- Remediation: Exclude this source code from the dashboard. It should be analyzed by AIP but it shouldn't appear in the dashboard.
- Details: Most of the time, third party libraries are very complex and not documentation.
- Tips: you can check it in top cyclomatic complexity tab for example. or you can search for some specific string pattern like 'gen', 'test' ...
Check module weight
- Impact: Bad aggregation for modules gives bad assessment quality.
- Remediation: Usually, good aggregation is done with aggregation by Artifacts.
- Details: By default, grades are measured on the entire Application
- Tips: consolidation mode is defined in the Assessment Model in the CAST Management Studio:
Check dead code / Unreferenced functions or methods
- Impact: Some rules dealing with unreferenced objects have a high weight and these rules are very useful for the project to help identify rapidly dead code in the source code.
- Cause: unreferenced objects may come from mistakes in the configuration due to specific frameworks that are not correctly managed.
- Remediation: review your configuration and run the analysis again.
- Tips: in the Engineering Dashboard, you can look at rules starting with "unreferenced XXX".
Check naming convention (if configured)
- Impact: default parameters are often wrong and rules dealing with naming conventions are normally low.
- Remediation: assess the Assessment Model and change the parameters for these rules.
- Tips: be careful with these types of changes, the impact is very low as it is dealing with documentation, transferability.... And people are more focused on performance or robustness. Secondly, to keep a good baseline and to be able to compare apple with apple, it is sometimes better not to correct it.
Click to enlarge:
Check file volumes
- Impact: make sure, in terms of volume, you have the same range of files in input (in the source folder) and in output (Engineering Dashboard).
- Remediation: if some files are missing, you may have to re-analyze the application.
- Tips: some open source tool exist (like cloc) to help you to count files in the source code folder.
Click to enlarge:
If the initial snapshot is not satisfactory, delete it - this will delete it from the Dashboard Service and the Measurement Service (if you chose to upload the results to the Measurement Service):
- Select the snapshot
- Click the delete button as highlighted below
- You will now need to make any configuration changes that you require and then re-generate the snapshot.
Upload snapshot data to the Measurement Service for viewing in the CAST Health Dashboard
If the snapshot now contains the information you expect, then you can upload it to the Measurement Service:
Note that the Health Dashboard can officially support the upload of a maximum of 200 applications. CAST recommends that you choose only the most critical applications from the business view point - i.e the applications that need to be monitored with high visibility by CIOs and managers.
You can perform a manual upload of the snapshot you have just generated to the Measurement Service for display in the Health Dashboard:
When you are generating a snapshot for a subsequent version of the Application (i.e. one that you have already on-boarded), and you are confident that the results of the snapshot generation will be correct (i.e. the new source code changes are relatively minor) then you can upload the snapshot data to the Measurement Service automatically during the snapshot generation using the Upload Snapshots to Measurement Service (if configured) option in the snapshot generation wizard:
Check results in the Health Dashboard
Once the snapshot data has been uploaded to the Measurement Service, CAST recommends that you check the results in the Health Dashboard. However, you may first need to reload the Health Dashboard cache so that results are displayed correctly:
Reload the Health Dashboard cache
The Health Dashboard features a data cache to improve the speed at which data is displayed in the dashboard. This means that when requesting data, the Health Dashboard may return data direct from the cache rather than fetching it from the Measurement Service. This means that data displayed in the dashboard may not be up-to-date - particularly if you have very recently generated a snapshot and uploaded data to the Measurement Service and were expecting to see this new data.
To reload the cache, see HD-ED - Reload the cache
Check the results
Browse to your Health Dashboard, login and check the results: