Summary: These options enable you to configure how Modules are configured in your Application analysis.

Introduction

Modules are used extensively in CAST Imaging and CAST Dashboards as a means to configure analysis results into meaningful groups or sets for display purposes:

Indeed, objects that are not part of a module:

  • cannot be seen in CAST Imaging/CAST Dashboards
  • cannot be included in Architecture Models
  • cannot be included in Transaction/Function Point configurations

The definition of modules within applications also impacts the accessibility and usability of application assessment results. Specifically, in the CAST quality and quantity model, the module is the smallest assessment entity. The definition of a module can improve the relevance of the analysis results by linking modules to development teams and application functional layers etc. See also Defining consolidation weighting settings for more information.

The content of a module is based on source code. CAST offers various automatic module strategies for display of source code, as follows (see Auto Generate below for more information about each strategy):

  • Console ≥ 2.8 when using onboarding with Fast Scan: "Full content"
  • Console ≥ 2.8 when using onboarding without Fast Scan: "per Technology"
  • Console 2.0 - 2.7 all onboarding modes: "per Technology"
  • Console 1.x: "per Technology"

These automatic module strategies can be modified once a Version has been set as the current version (onboarding without Fast Scan) or an initial deep analysis has been completed (onboarding with Fast Scan) using the Modules configuration options shown below:

Click to enlarge

Auto Generate drop downSee Auto generation below.
Ignore Empty ModulesThis option is enabled by default. When enabled, any modules (whether auto created or User Defined modules) will be ignored during the analysis if they do not contain any objects. If you disable this option, please ensure that all modules (whether auto created or User Defined modules) contain at least one object otherwise the analysis will fail.
Add

See User Defined modules below. This button is only active when the Auto Generate option is set to:

  • None (Manual Creation)
  • Unassigned objects

 (Global)

Use this option to delete multiple modules, selected using the check boxes:

Note that when the Auto Generate option is set to None (Manual Creation) and you delete all existing modules, a warning is displayed:

Click to enlarge

List of modules - a list of modules created in the previous analysis or to be created in the next analysisModule NameName of the modules(s) that have been created.
Generation Type

Type of module. This can be either:

  • User defined
  • Full content
  • Per analysis unit
Description

A description of the module:

  • Full content module = corresponds to auto Full Content option
  • Unassigned module = corresponds to the "catch all " module created using auto Unassigned objects option
  • Technology module = corresponds to manual per Technology option
  • Folder path module = corresponds to manual per Subfolder option
  • Analysis Unit module = corresponds to manual per Analysis Unit option
  • Free text/blank =  corresponds to a manual module created using Object Filters

Allows you to edit or delete a User Defined Module (manual creation).

For modules created via an automatic strategy choice (Full Content, Per analysis unit):

  • While you can use the Edit button any changes you make cannot be saved
  • You can delete a module, but it will be recreated at the start of the analysis/snapshot generation process.

Changes made

Any changes made in the Modules configuration page (e.g. changing the module configuration) will cause a banner to appear at the top:

This indicates that the changes you have made will impact your analysis results and therefore that the data that is used for the Architecture Studio, Transaction configuration and upload to CAST Imaging will not be up-to-date. Clicking the Update button in the banner will run a special step called Prepare analysis data that should complete relatively quickly (more quickly than a full analysis or snapshot) and ensures that the data used by the Architecture Studio, Transaction configuration and upload to CAST Imaging is up-to-date based on the changes you have made. 

This step is always actioned when you either run an analysis (without a snapshot) or generate a new snapshot. When the Prepare analysis data step is complete, the banner will no longer be displayed.

Auto Generate

The Auto Generate option enables you to change the automatic module strategy chosen for your Application.  These modules will only be created when you run a new analysis, therefore you cannot view them in this list until the analysis has completed.

None (Manual Creation)

If you select this option, no Modules are created at all in the next analysis. This effectively disables the automatic strategy entirely. In this situation, you should always create a User Defined module so that your results can be consulted. Choosing this option enables the Add button enabling you to create User Defined modules.

Selecting this option and not creating at least one User Defined module or having at least one Module listed in the list of modules will cause the next analysis to fail with the following error:

Error: Internal error occurred. 
Return value: 1000 
  The application is closing. Call CAST support now providing the log file at \AipNode\data\logs\external_logs\c7ea2ce1-77bb-4492-ae85-7342be6a1f48\analyze\analyze-20200722-152438.txt 
  Source Server / My_APP: Missing Generate one module per : 
  Source Server / my_APP: Missing User Defined Modules

CAST recommends using the Unassigned objects option if you wish to use User Defined modules since this will automatically create a module to "catch" any objects that may not have been matched by a user defined module, so there will always be at least one module.

Full content

If you select this "automatic" option, one Module is created for your entire Application during the next analysis, i.e. it will contain all the source code for your ApplicationAny modules you have added yourself (User Defined modules) will ALSO be created. For example:

Per analysis unit

If you select this "automatic" option, one Module is created per Analysis Unit that is created during the next analysis in your Application. Any modules you have added yourself (User Defined modules) will ALSO be created. For example:

Unassigned objects

This option is recommended in situations where you wish to use User Defined modules. When selected, all other automatic strategy options will be disabled and an automatic module called Unassigned will be created to "catch" any objects that were not assigned to one of your User Defined modules, enabling you to see them in the CAST dashboards etc.

Choosing this option enables the Add button enabling you to create User Defined modules.

Changing the module strategy

If you make a change to the module strategy, you will need to run a new analysis in order for the changes to be taken into account - if you want the modules to be visible in the CAST dashboards, then a snapshot will also need to be generated. Remember that:

  • any existing modules created by another automatic strategy will be retained and the modules from the newly selected automatic strategy will be created at the start of the analysis/snapshot generation process. This behaviour is in contrast to the behaviour in previous releases of Console (≤ 1.17) where existing modules were deleted.
  • changing strategy will impact existing results in the CAST Dashboards/CAST Imaging.
  • choosing None (Manual Creation) for the automatic strategy means that you must create at least one User Defined module or have at least one Module listed in the list of modules, otherwise the analysis/snapshot will fail.

User Defined Modules

You can create User Defined Modules if you have not yet run an analysis, however, it will not be possible to check the Object Filters in the User Defined Module until you have run an analysis and have results.

In addition to automatic strategy modules, Console offers you the option to create User Defined Modules - these Modules can be configured to contain the exact content you require for display in the CAST Dashboards. Content is configured using:

  • Filter on your analysis results, either:
    • via the GUI creating an Object Filter (using the Technology, Analysis Units and Object Names filter criteria combination) in order to define the content you require. Certain rules are applicable for User Defined Modules created using an Object Filter::
      • you can add multiple Object Filters per User Defined Module
      • you can choose only one Technology (the drop down will show the technologies found in your application source code)
      • when you have chosen the Technology, the analysis units list will show only analysis units belonging to the selected technology
      • if you do not choose a Technology, the analysis unit list will show all available analysis units in your application
      • you can select multiple analysis units
      • you can add multiple Object Name patterns: the filter result includes all the results of the all the name patterns you have added
      • the Object Name pattern choices are Name, Full Name or Path, with operators Equals, Like or Match
    • via the GUI creating an Explicit Filter using an SQL query
  • Module per Technology
  • Module per Analysis Unit
  • Module per Subfolder

Add a User Defined Module

To add a User Defined Module, first change the auto strategy to either of the following (when the auto strategy is set to any other option, it is not possible to create user defined modules):

  • None (Manual Creation)
  • Unassigned (recommended)

The Add button should now be enabled - click it and choose the option you require:

Click to enlarge

Each option is explained below:

Module - based on a custom Filter

This option allows you to create a module using a custom Filter. You can create:

  • multiple Object Filters via the GUI
  • a single Explicit Filter using a SQL query
  • a combination of either

Object Filter

The Object Filter screen will be displayed:

By default, a new User Defined Module will be provided with an empty filter called "Filter1". This filter contains no configuration at all, however, if left as is, it will return all objects associated with the Application (identical to the Full Content module). This is of particular importance if you choose to configure an Explicit Filter - if the empty "Filter1" is left as is, then it will override any Explicit Filters you create and return all objects (note that you can use Filters and Explicit Filters together - see Behaviour of User Defined Modules using Object Filters).
Module Name

Choose a name for the User Defined Module (the name you give to a User Defined Module will form the name of the Module in the CAST Dashboards). The name of the Module should only use the following permitted characters - any unauthorized characters will result in an error message:

  • 0123456789
  • abcdefghijklmnopqrstuvwxyz
  • ABCDEFGHIJKLMNOPQRSTUVWXYZ
Description

Free text field allowing you to create a description for this module. This description will be displayed in the Description column in the module list:

Filter NameYou can include as many filters as required - enter a name for each Object Filter, or leave as default. 
Technology SelectionClick the drop down list box to choose a Technology to filter on - the list of available technologies results from the most recent source code delivery (you do not need to have run an analysis). All subsequent options in the filter will then be restricted to this Technology. It is not obligatory to select a Technology: if you do not restrict the Technology to one specific technology, then all subsequent options will also not be restricted.
Analysis Unit Selection

Click Add to choose an Analysis Unit to filter on - the list of Analysis Units results from the most recent source code delivery (you do not need to have run an analysis) will be displayed. All subsequent options in the filter will then be restricted to the chosen Analysis Unit(s). It is not obligatory to select an Analysis Unit: if you do not restrict the Analysis Unit, then all subsequent options will not be restricted.

Use the "+" icon to select the Analysis Unit(s) you want to filter on:

A new dialog box will open allow you to select the Analysis Unit(s) - tick the items you want as shown below. This dialog shows all available Analysis Units in the current delivery - by default all Analysis Units will be displayed, even those that are already used in other Modules (the Modules column lists the existing Modules which the Analysis Unit is used in). You can also enable the Show only not used option if you only want to see Analysis Units that are not already used in existing modules:

Selected Analysis Units will automatically appear in the filter:

Object Name Selection

Click to Add to create a new Object Name Selection (you can include as many Object Name Selections as required):

Field
Choose the option you require:
  • Name - the object's short name, for example for a Java function "createStatement"
  • Full Name - the object's full name, for example for a Java function "java.sql.Connection.createStatement"
  • Path - the path to the file storage location of the object.
  • Care should be taken when using the Path criterion for Object Name Selection: in some technologies (such as .NET) objects in one path may hold objects that are present in another path and as a result, you may find that because all children and descendants are included, some objects may be present in multiple paths. As a result an object may be present in multiple modules. As an alternative for the .NET technology, you could:
    • identify namespaces of the items you want and use the Full Name criterion to define the module.
    • use an explicit filter based on a SQL query to define the module.
  • CAST highly recommends consulting the CAST System View "CSV_FILE_OBJECTS" located in the CAST Analysis Service schema to find out how object names and paths have been recorded.
OperatorChoose the operator you require:
  • EQUALS - use this option to exactly match the Pattern you enter (equivalent to the "=" in SQL)
  • LIKE - use this option in conjunction with the % operator to match similar objects (equivalent to the "LIKE" in SQL):
    • The pattern sales% on Name will return objects such as sales, salesdetails, salesaddresses
    • The pattern %.%..%uth% on Full Name will return objects such as SERVER.CASTPUBS..AuthorIDCodes, SERVER.CASTPUBS..on_delete_authors
    • The pattern %.frm on Path will return all objects whose path ends in .frm
  • MATCH (Perl Regular Expression) > Use this option if you require a more complex pattern based on a Regular Expression.
PatternEnter the string or expression you want to match.
Click this button to remove the current Object Filter.

Explicit Filter

This option allows you to define a specific list of objects that will be included in a Module. You can use this tab in conjunction with the Object Filters option - see Combining Object Filters and Explicit Content for more information about how the two filters can function together. The list of objects is determined by the insertion of an SQL query that will be run against the CAST Analysis schema and include any objects that match your query:

The SQL query that needs to be inserted into the editor must use a CAST pre-defined format. The basic format is as follows:

delete from §CI_OBJECTS_SET where set_name = '$(ModuleName)';
 
insert into §CI_OBJECTS_SET(set_name, object_id, error_id)
select '$(ModuleName)', o.object_id, 0
from §CDT_OBJECTS o
where /*fill where clause here*/

This query essentially does the following:

  1. Empties the CI_OBJECTS_SET table in the CAST Analysis schema of any existing entries pertaining to the current User Defined Module you are working on (this is determined automatically by the $(ModuleName) macro). § symbol is replaced with application local schema name. 
  2. Inserts new data into the CI_OBJECTS_SET table that determines which specific objects must be included, based on:
    • the CDT_OBJECTS table in the CAST Analysis schema (a table that lists all objects that have been saved into the CAST Analysis schema as a result of analyses that have been successfully completed)
    • a where clause that lets you extract specific items from the CDT_OBJECTS table

For example, to specify ALL objects in the CAST Analysis schema that are "SQL Tables", modify the basic format SQL by adding the text in the where clause:

delete from §CI_OBJECTS_SET where set_name = '$(ModuleName)';
 
insert into §CI_OBJECTS_SET(set_name, object_id, error_id)
select '$(ModuleName)', o.object_id, 0
from §CDT_OBJECTS o
where object_type_str = 'SQL Table'


SQL editor validation

Behaviour in Console ≥ 1.27.1 and ≥ 2.1

In  Console ≥ 1.27.1 and ≥ 2.1, SQL validation is not performed on Create/Edit or on Check Content. If the editor contains a syntax error:

  • When you click Create/Edit and the editor contains a syntax error, then the content is saved regardless, but when you try to run the job an error will occur.
  • If you click Check Content and the editor contains a syntax error, an error will occur).

It is possible to enable SQL validation, if required see Configuring SQL validation.

Behaviour in Console ≤1.27.0 and ≤ 2.0

In Console ≤1.27.0 and ≤ 2.0, an SQL validation process is in place on Create/Edit or on Check Content. The following rules apply:

  • Select can be performed on any table. Only "droptemporarytable" function is allowed in select
  • Insert is allowed only into "ci_" tables or temporary tables with "maint_tmp_" prefix
  • Only temporary table records can be updated
  • Only "ci_" or temporary table records can be deleted
  • Only temporary tables can be created or deleted

Creating the filter

When the Object Filter configuration is complete, use the Create button in the bottom right corner to create the module:

Click to enlarge

Your new User Defined Module will be listed in the list of modules:

Check a User Defined Module - Check Content

If you have already run an analysis, you can use the Check Content button to check which objects will be matched by the User Defined module and the filters you have defined:

Click to enlarge

Objects matched by the User Defined module and filters will be displayed in two panels to the right:

Summary

Displays a list of objects matched by the filter (by object type and number of objects matched).

Details

Displays a detailed list of each object matched by the filter, including Name, Full Name and Path.

Click to enlarge

Module per technology

This option will create Modules based on the Technologies that have been "discovered" in your source code. One Module will be created for each Technology that has been delivered in the Version. The modules will be created immediately and then generated at the start of the next analysis/snapshot:

Module per Analysis Unit

This option will create Modules based on the Analysis Units that have been "discovered" in your source code.  One Module will be created for each Analysis Unit that has been discovered in the Version. The modules will be created immediately and then generated at the start of the next analysis/snapshot:

Module per Subfolder

This option allows you to create Modules based on the folders delivered in your source code Version. A configuration screen will be displayed allowing you to select the folder. One module will be created for each Subfolder that is a child of the selected folder. The modules will be created immediately and then generated at the start of the next analysis/snapshot:

Editing an existing User Defined Module

To edit an existing User Defined Module, find it in the list of modules and click the Edit button:

For modules created via an automatic strategy choice (Full Content, Per analysis unit), while you can use the Edit button any changes you make cannot be saved.

Deleting a User Defined Module

To delete an existing User Defined Module, find it in the list of modules and click the Delete button:

  • Deleting a module does not delete the module as stored in the Application schemas, therefore CAST dashboards will not be impacted. Changes are only visible in the CAST dashboards when a new analysis or snapshot is generated.
  • For modules created via an automatic strategy choice (Full Content, Per analysis unit), you can delete a module, but it will be recreated at the start of the analysis/snapshot generation process.

Behaviour of User Defined Modules using Object Filters

Combining Object Filters and Explicit Content

When defining a User Define Module, it is possible to combine various different filter options. A User Defined Module can consist of 0 to N Object Filters (defined in the Filters tab) and 0 to 1 Explicit Filters (defined in the Explicit Filters tab). The result of these options is derived using a UNION between the Object Filter(s) and the Explicit Filter.

By default, a new User Defined Module will be provided with an empty filter called "Filter1". This filter contains no configuration at all, however, if left as is, it will return all objects associated with the Application (identical to the Full Content module). This is of particular importance if you choose to configure an Explicit Filter - if the empty "Filter1" is left as is, then it will override any Explicit Filters you create and return all objects.

Filters

A Filter will target objects using an INTERSECTION of the various filter types. A target object must:

  • (if the filter is active) belong to a filtered Technology
  • (if the filter is active) AND belong to one of the selected Analysis Units that function using a UNION between Analysis Units
  • (if the filter is active) AND match one of the expressions on the Name, Full Name and Path that function using a UNION between expressions
  • (if the filter is active) AND group together all conditions on the same field (Object Name, Object Full Name, or Object Path) using the same operator (= or LIKE): these grouped expressions are handled as UNIONS between their respective criteria (OR); then, these three groups are handled as intersections (AND). For example:
Example for the fourth filter type:
Given the following:

Object Name = 'A'
Object Name = 'B'
Object Name LIKE 'C%'
Object Name LIKE 'D%'
Object Full Name = 'X.Y'
Object Full Name = 'X.Z'
Object Full Name LIKE 'Z.T%'
Object Full Name LIKE 'Z.U%'
Object Path = 'a/b'
Object Path = 'c/d'
Object Path LIKE 'x/y%'
Object Path LIKE 'z/t%'

Leads to the following logical criterion:

(Object Name = 'A' OR Object Name = 'B')
AND
(Object Name LIKE 'C%' OR Object Name LIKE 'D%')
AND
(Object Full Name = 'X.Y' OR Object Full Name = 'X.Z')
AND
(Object Full Name LIKE 'Z.T%' OR Object Full Name LIKE 'Z.U%')
AND
(Object Path = 'a/b' OR Object Path = 'c/d')
AND
(Object Path LIKE 'x/y%' OR Object Path LIKE 'z/t%')

Behaviour with regard to child objects

User Defined Modules will always include child objects, i.e:

  • children of directly matched objects
  • children of children and so on.

This can sometimes be confusing when using user defined modules defined on full paths in CAST dashboards: violations will be displayed for objects that may not necessarily match the the full path defined in the filter. This is because some objects may be child objects. CAST recommends using object filters based on Analysis Units rather than on the full path to avoid having violations returned for child objects that are not specifically part of the filter.

Take the following example. If the filter is based on the full path, for instance SomeCode\NextCode\Comments\src, it will retrieve the file comment1.cs and its children, and children of these children etc. In this situation, we can expect that the Namespace viewComment and objects of the class comment1 to be part of the module. However, since we have matched the namespace viewComment (a child of the comment1.cs file), the class comment2 will also be part of the module as it is a child of the namespace.