Page tree
Skip to end of metadata
Go to start of metadata

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 typeThis indicates what project type the CAST Delivery Manager Tool has assigned to the projects identified in the source code package.
TechnologyIndicates what technology type the CAST Delivery Manager Tool has assigned to the project.
#SelectedIndicates 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:

  • via a specific exclusion filter or an exclusion rule - see Projects to exclude in the Package Configuration tab - Which project should we take into account for the analysis? For example:
    • you may have chosen to "Exclude all empty projects", in which case projects that are discovered without source code will be ignored.
    • you may have created a filtering rule on a project name, in which case matching projects that are discovered will be ignored.
  • via a specific inclusion rule - see Type of projects to include in the package in the Package Configuration tab - Which project should we take into account for the analysis? For example:
    • you may have unticked "Maven Java project", in which case all matching projects will be ignored.

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.

  • If a project marked as Ignored has no dependencies to other projects that are marked as Selected, then the project will NOT be transformed into an Analysis Unit in the CAST Management Studio.
  • If a project marked as Ignored has one or more dependencies to other projects that are marked as Selected, then the project WILL BE transformed into an Analysis Unit in the CAST Management Studio. In addition the following is true:
    • The option Don't show in Dashboard will be ticked in the corresponding Analysis Unit - this flags the objects belonging to the Analysis Unit as "external".
    • The option Analyze Analysis Unit will be ticked in the corresponding Analysis Unit.

This has the following impact:

  • The corresponding Analysis Unit and its objects WILL be analyzed so as to avoid link resolution errors and will thus be visible in CAST Enlighten, however, the "external" objects resulting from the analysis of the Analysis Unit WILL NOT contribute to any calculations executed for the CAST dashboards and WILL NOT figure in any results displayed in the CAST dashboards.
  • The "external" objects resulting from the analysis of the Analysis Unit WILL NOT be attached to any of the Modules that can be created automatically in the CAST Management Studio:
    • Full Content
    • Analysis Unit content
    • Unassigned Objects content
  • These "external" objects will be included in a User Defined Module that uses an Explicit Content filter if the objects match the filter - in other words, no distinction will be made for "external" objects. In this case, if you need to specifically exclude "external" objects from a User Defined Module that uses an Explicit Content filter, you need to build an SQL query that filters them out.

There are some limitations to these rules:

  • For a project and corresponding Analysis Unit to be marked as "external", all dependent projects must all belong to the same package.
  • Circular dependencies are not supported
#AddedThis column displays the number of projects that are "new" in the current Source Package in comparison to a Source Package in an older Version.
#RemovedThis 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.

 Click here to expand...

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.

Note that:
  • 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.

Technology criterionChoose the technology type that your filtering rule will be applied to. Selecting None will ensure that technology type is ignored and filtering will only occur on the project name or file path.
Project name criterion / Project file path criterionSelect either option to activate the appropriate settings. You can define the following combinations of criteria:
  • Project name criterion alone
  • Project file path criterion alone
  • Project name criterion AND Project file path criterion

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 
(source code provided as .js files)

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 variableA 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 nameIndicates the name of the project derived from the project's configuration files.
Project pathIndicates 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.

 Click to expand...

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.

 Creating a manual remediation for an Undefined Variable

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.
 Creating a manual remediation for a missing item

You can create a manual remediation for any of the following:

  • Missing project
  • Missing library file
  • Missing file
Note that it is not possible to create a manual remediation for a missing folder. These alerts can be resolved by creating a new package that targets the missing item.

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

  • No labels