Introduction
When you have configured a Version and packaged some source code successfully but your packages contain warnings, errors or alerts, you must ensure that these warnings/errors will not impact the analysis and that any alerts are dealt with correctly. This will involve fine tuning your Version and Packages, remediating/ignoring alerts and then re-running the packaging action. This is explained below.
Validate at Package level
Validate package content
The first thing you should do is to check the Package Content tab for each Package in your Version. This tab displays information about what the CAST Delivery Manager Tool has discovered in the source code package according to the selected discovered and other configuration settings set in the Package Configuration tab:
Click to enlarge
Check the following:
Projects found
That at least one Project has been identified and selected in the Projects found section - projects that are marked with Selected will be automatically transformed into Analysis Units when the Version is accepted in the CAST Management Studio. Note that it is entirely possible for no projects to have been identified and selected in the in the Projects found section - this can occur when packaging a supported technology for which no "discoverer" exists (for example when using the SQL Analyzer extension to package DDL). In this case it is safe to continue - you just need to ensure that you create the required Analysis Units in the CAST Management Studio.
| Project type | This indicates what project type the CAST Delivery Manager Tool has assigned to the projects identified in the source code package. |
|---|---|
| Technology | Indicates what technology type the CAST Delivery Manager Tool has assigned to the project. |
| #Selected | Indicates the total number of projects identified by the CAST Delivery Manager Tool in the most recent Source Package and which will be packaged for Delivery. Projects that are marked as Selected will be transformed into Analysis Units in the CAST Management Studio. If no projects are marked as Selected, then no Analysis Units will be created: you may need to review your package configuration. |
| #Ignored | Indicates the total number of projects that have been ignored. A project can be ignored in various ways:
Information about excluded/ignored items and how they are handled in the CAST Management Studio When a project is marked as ignored after an initial run of the Package action, the following rules determine how the corresponding project is handled in the CAST Management Studio when the Set as current version option is actioned.
This has the following impact:
There are some limitations to these rules:
|
| #Added | This column displays the number of projects that are "new" in the current Source Package in comparison to a Source Package in an older Version. |
| #Removed | This column displays the number of projects that are no longer present in the current Source Package in comparison to a Source Package in an older Version. |
Define exclusions if necessary
You may now need to exclude some projects that have been discovered and marked as Selected during the initial Package action so that they are not included in the delivery. For example, you may not want to deliver projects that are not directly used by the projects you need to deliver. The information gathered during the Application Architecture Review (see Qualification) will help guide the validation of the application boundary and decide what should be excluded from the internal objects and link representation of the analyzed application.
Excluding third party components and, in general, any artifacts which are not relevant to the scope of the analysis will improve the relevance of the results. To do so, you need to return to the Package Configuration tab for EACH package you have packaged and scroll down to the Projects to exclude section:
Click to enlarge
*
Exclusion rules
This section enables you to configure the "exclusion" rules that you require. When the Package action is re-run, and an exclusion rule is matched, then the project in question will be marked as Ignored in the results displayed in the Package Content tab.
- the option Exclude all empty projects refers to projects that do not have associated source code.
- the option Exclude Test code will exclude all folders named "test" that are discovered during the Package action.
Filtering rules
You can use this section to define Filtering rules to exclude specific projects from the package. The filtering rules can be based on:
- The project technology type
- the name of the project using a Regular Expression
- the project's path using a Regular Expression
When the Package action is re-run, and an exclusion rule is matched, then the project in question will be marked as Ignored in the results displayed in the Package Content tab.
| Use this button to add a filtering rule - a dialog box will appear and you can define the rule: Click to enlarge
Note that the Close button will save the changes you make.
Note that if you activate more than one filtering criteria in the above dialog box, the AND operator is used to combine the criteria. In other words, all selected criteria must match to exclude the project. CAST therefore recommends that you avoid activating for example the Project Name criterion to exclude Project A AND the Project File Path criterion to exclude Project B within one single Filtering rule - the result will be that the Filtering Rule is ignored and no projects will be excluded. If you need to exclude more than one project, you should instead create an individual Filtering Rule for each project. | ||||
|---|---|---|---|---|---|
| Use this button to edit an existing filtering rule - a dialog box will appear in which you can modify the existing filtering rule. | ||||
| Use this button to remove an existing filtering rule from the list. |
Project exclusion
This section is designed to exclude projects that have been extracted and are already "selected" in the package. When the Package action is re-run, then the selected projects will be marked as Ignored in the results displayed in the Package Content tab.
| Use this button to exclude a project - a dialog box will appear and you can select the project you want to exclude:
Only projects that have already been extracted and are part of a Source Package will be listed here. In addition, projects will not appear in this dialog box if they have already been added to the exclusion list. |
|---|---|
| Use this button to remove an existing project from the list of excluded projects. |
Exclusion best practices
Strategies and CAST recommended best practices for exclusion/inclusion of various source code types are summarized in the table below:
| Source code type | Strategy |
|---|---|
Source code created and maintained by Application Team | include |
Automatically generated source code | include - as it will be required to discover all links |
Test code | exclude (an Exclusion Rule tick box is available to exclude test code). |
External binary libraries - Java/App server/frameworks/JARs (contain .class files) | include |
Source libraries - Javascript libraries | include |
Please note that if you exclude a folder and subsequently during the Package action the discoverer finds a reference to the excluded folder, then a Package Alert will be generated. There is no way to resolve this alert with a standard remediation as such, if you still need to exclude the folder and want to avoid an alert, you can exclude its contents only using a specific Regular Expression. For example, you have a subfolder entitled "unittests" that you do not want to include in the Package - you exclude this folder. However, other code in the Package references this folder and as such a Package Alert will be generated when the Package action is run. Use forward slashes around the folder name in your Regular Expression to force the CAST Delivery Manager Tool to ignore the contents of the folder but keep the folder itself:
/unittests/
No Package Alert should be generated.
Files found
The Files found (only when working with file based source code as oppose to a database or schema) - ensure that the file extensions listed and the number of files are as expected.
Log Summary
The errors or warnings in the Log Summary section, for example in the image below, a warning is present in this package - click the log button to view the log file and identify what the issue is:
Click to enlarge
Manage packaging alerts
Alerts generally indicate that the source code package is incomplete, that there is a configuration issue or simply that there is something wrong in the source code. If these alerts are not dealt with and the Version is delivered, then there is a risk that the source code analysis executed in the CAST Management Studio will be erroneous or may not even complete.
Package Alert tab
Any alerts are shown in the Package Alert tab:
Click to enlarge
This section displays a list of any "alerts" that were raised during the Package action. Alerts can come in various different types (non-exhaustive list):
| Undefined variable | A variable has been discovered in the source code in the source package. The CAST Delivery Manager Tool cannot detect a value for this variable and therefore an alert has been created. |
|---|---|
| Missing project | A reference to a project, library file, folder or resource has been discovered in the source code package. The CAST Delivery Manager Tool cannot detect this specific item anywhere in the source code package and therefore an alert has been created. When packaging Eclipse based Java code in the CAST Delivery Manager Tool, you may receive Missing source folder alerts even though the source folder that is recorded as being missing is actually present in the source code. This alert is usually generated when no .project file has been found in the folder that is recorded as being missing. To resolve this alert, you can manually add the missing .project file and then re-run the packaging action. |
| Missing library file | |
| Missing source folder | |
| Missing resource |
Selecting an alert type will show the list of specific alerts that have been raised for that type:
| Alert | Indicates the item that has caused the alert - a reference to an item in the source code package that cannot be detected, or a variable that is undefined. Note that a source code "version number" will be added to the Alert column when a Technology that uses source code versioning has been packaged, see the example below:
|
|---|---|
| Project name | Indicates the name of the project derived from the project's configuration files. |
| Project path | Indicates where the project is located in the Source Code Package - this refers to a folder (for file based source code packages) and to a database (for databases based source code packages). If a dot "." is displayed, this indicates that the project is located at the root of the source package. |
It is up to you as the Delivery Manager to manage these alerts. Initially, you should always attempt to remediate alerts using the following methods:
- by altering the source code package configuration (for example the root path defined in Package Configuration tab - Where is your source code? may be incorrect) and then re-running the Package action
- by creating additional source code packages that target the missing projects, files and folders and then re-running the Package action
- by altering your original source code and then re-running the Package action
If you still have alerts after performing the above actions, you may need to use an ignore action or remediate them manually as discussed below.
Ignoring alerts
If you know that an alert is false or will not impact the source code analysis, then it is possible to ignore the alert. This action is, however, generally used when re-delivering a new Version of your source code: by ignoring alerts from the current Version, you can easily identify new alerts in the new Version.
To ignore an alert, select the alert (1) and then click the ignore button (2):
A new dialog will be displayed (click to enlarge):
- Enter a Justification (1) for ignoring the alert. This is for information only and will be displayed in the Any alert to ignore? panel.
- Now choose (2) whether you want the ignored alert setting to be applied to all projects in which the alert was identified, or whether you want it to apply to specific projects only (select the projects in the table using the check box).
- Click Finish to save the ignored alert.
- The ignored alert will then be displayed in the Any alert to ignore? panel. Next time you run a Package action, the ignored alert will be removed from the Packaging alerts panel.
Using manual remediation items
If you know that an alert can be resolved because a missing item is located in another source code package, you can create a manual remediation item that will "tell" the CAST Delivery Manager where the missing items are located. In the same way, missing variables can be manually remediated by defining the variable that is required.
When you next run the Package action, the CAST Delivery Manager Tool will use the remediation item to fix the alert. The alert will then be cleared.
Select the alert (1) and then click the add button:
A new dialog will be displayed (click to expand):
- Enter the value (1) for the selected variable in the Value field
- Choose (2) whether you want the value entered in 1 to be applied to all projects in which the undefined variable was identified, or whether you want it to apply to specific projects (select the projects in the table using the check box).
- Click Finish to save the remediation.
- The remediation will then be displayed in the Any manual remediations to apply for alerts? panel. Next time you run a Package action, the remediation you created will be taken into account and the alert will be removed from the Packaging alerts panel.
You can create a manual remediation for any of the following:
- Missing project
- Missing library file
- Missing file
Select the alert (1) and then click the add button:
A new dialog will be displayed (the example below is for a missing project alert, but the dialog is similar for other alerts - click to enlarge):
- (2) Locate the missing item using the list of discovered items (you can filter the list using the Search box (1)) and select it
- Now choose (3) whether you want the remediation to be applied to all projects in which the alert was identified, or whether you want it to apply to specific projects only (select the projects in the table using the check box).
- Click Finish to save the remediation.
- The remediation will then be displayed in the Any manual remediations to apply for alerts? panel. Next time you run a Package action, the remediation that you created will be taken into account and the alert will be removed from the Packaging alerts panel.
Re-run the Package action
To ensure that the exclusions/alert remediations you have defined are taken into account, you need to re-run the packaging action at Version level (i.e. all packages are re-packaged):
