Created by James Hurrell on Jun 07, 2021

Summary: this page discusses how to use CAST Server Manager GUI or CLI to perform an application and schema upgrade.

Step 1 - Determine the schemas to be upgraded

Browse to your AIP Console URL http://<server>:8081/ui/index.html, login to AIP Console with a user that has the ADMIN role and switch to the Admin Center:

Now move to the Applications panel:

Locate your Application in the list, click the options button and select View Details:

Expand the Database Schemas section to view the names of the schemas assigned to the Application. These are the schemas that require upgrading:

Step 2 - Run the upgrade

This step describes the upgrade process which will upgrade the following to the new release of AIP Core:

  • The Application
  • The Management, Analysis and Dashboard schemas associated to your Application
  • The Assessment Model associated to your Application
  • The Application's specific Delivery folder files
  • Optionally upgrading existing and/or installing new Extensions

Show me how to do this with the GUI

Click here to expand...

Run CAST Server Manager from the new release of AIP Core on the relevant AIP Node. This application can be found in the in the Windows Start menu (you can also find it in the AIP Core installation folder - called servman.exe):

The Open Server Connection Profile dialog will then be displayed allowing you to connect to the RDBMS server hosting the CAST AIP schemas you wish to upgrade. A connection profile to a Windows CAST Storage Service instance will be available in the dialog box if, during the installation of the new release of AIP Core, a Windows CAST Storage Service was detected on the current workstation:

If no connection profiles are available a message will be displayed as shown below. Please create a new connection profile to the CAST Storage Service/PostgreSQL instance on which the AIP schemas you wish to upgrade are installed:

Select the profile you require and click Open. CAST Server Manager displays all the upgradable schemas located on the host CAST Storage Service/PostgreSQL instance under the Combined Installations (Out-of-date) node. In the image below, the highlighted set of AIP schemas has "Upgrades Available", indicating that they can be upgraded:


Select (in the left hand panel) the root item of a set of schemas that you would like to upgrade and then click Schema Installation > Upgrade Installation on the toolbar:

The wizard "Select Extensions to install" is then displayed:

You now need to ensure that each Extension is at the correct release number:

  • extensions shipped with AIP Core and not already installed will be pre-selected for installation and it will not be possible to change this
  • any previously installed extensions will not be automatically selected for upgrade, even if a more recent release of an extension is shipped with the new release of AIP Core or has been downloaded to the AIP Node manually. To benefit from latest improvements and bug fixing in the most recent extension release, you need to explicitly select the new release of the extension for upgrade knowing that moving to a new release of an extension may impact your analysis results.
  • if you see the <all users dir> option this indicates that custom legacy Universal Analyzer language packs exist in <CAST_ALL_USERS_PATH> and will be installed as part of the upgrade process.

If you would like to upgrade/install an extension, use the drop down list in the Version column:

Any additional extensions that your selected extension requires (i.e. Dependencies) will also be selected for upgrade/installation automatically:

Once all required extensions have been selected for installation/upgrade, click the Next button to continue:

The wizard Assessment Model Upgrade Options is then displayed. You will be asked to choose an option with regard to the handling of the Assessment Model during the upgrade - note that no option will be pre-selected so you MUST choose an option that meets your needs (see the Prerequisites in AIP Core - Application - schema upgrade on each AIP Node for an explanation of the available options):

OptionDescription
Preserve Assessment Model customizations, activate new rules from AIP 8.3.x

These two options will preserve the current Assessment Model assigned to your CAST Dashboard Service schemas and merge in any new rules delivered with the AIP Assessment Model provided in the new release of AIP Core - depending on your option choice, these new rules will either be activated (provides the benefits of the new release with all options active) or disabled (therefore making post upgrade results more stable and in-line with the previous release of AIP Core but not benefiting from updates in the new release). Please see Assessment Model updates for more information about new Quality Rules that may have been added in this release of AIP Core.

If you choose either of these options, the following Assessment Model values will be retained:

  • the status of active/inactive Quality Rules
  • thresholds
  • weights
  • critical contributions
  • parameter values
  • custom indicators
  • custom Quality Rules

However, the Assessment Model will still be subject to an upgrade process to modify some values to make them compatible with the chosen release of AIP Core for example:

  • SQL and property implements
  • applicable technologies
  • associate values
  • documentation
Preserve Assessment Model customizations, leave new rules disabled
Use default Assessment Model from CAST AIP 8.3.xIf you choose this option, the new Assessment Model provided in the new release of AIP Core will be assigned to the CAST Dashboard Service schemas selected for update, therefore replacing any existing Assessment Models.

Click Next to continue after having chosen an option:


Accept the warning and summary dialog boxes and let the upgrade proceed:

On completion, the Combined Installation is now displayed as up-to-date:

Note that:

  • The update of a Management Service schema will be cancelled if one of the Analysis or Dashboard Service schemas associated with the respective Management Service schemas is invalid, unreachable or already updated. In this situation CAST recommends restoring your backup database/schemas and starting again.
  • The above upgrade process will retain your existing CAST AIP global license key for use with the new release of CAST AIP.

Logs and error numbers

All logs associated with the schema upgrade are stored in the following location on the AIP Node (by default):

%PROGRAMDATA%\CAST\CAST\Logs\ServMan

The following section lists the error numbers that may be returned when attempting to run the upgrade:

NumberDescriptionSolution
3001An attempt was made to upgrade Application schemas that were installed with a version of AIP Core ≤ 7.3.x. This is not supported.Ensure that all Application schemas involved in the upgrade are installed with AIP Core ≥ 8.3.x.
3002An attempt was made to upgrade Application schemas in which no snapshot exists.Ensure that at least one Snapshot exists in the Application schemas you want to upgrade.
3003An attempt was made to upgrade Application schemas where not all schemas are installed with the same release of AIP Core.Ensure that all Application schemas involved in the upgrade are installed with the same release of AIP Core.
3004The Application schemas you want to upgrade have no Delivery folder defined.Only occurs when attempting to upgrade from AIP Core 7.0.x, which is not supported.
3005

The Delivery folder associated to the Application schemas you want to upgrade cannot be found on disk or is not accessible.

Ensure that the Delivery folder associated to the Application schemas you want to upgrade exists and can be accessed from the server you are running the upgrade on.
3006The Delivery folder associated to the Application schemas you want to upgrade is more recent than the current release of CAST Server Manager you are using.Ensure that you are using the correct release of CAST Server Manager to perform the upgrade and that you are not attempting to perform an upgrade on a Delivery folder that is assigned to a more recent release of AIP Core
3007An error exists in the AIP Core metamodel that is preventing the upgrade from proceeding.Please contact CAST Support for help with this error.
3008An SQL error has occurred during the upgrade process.Please contact CAST Support for help with this error.

Show me how to do this with the CLI

Click here to expand...

CAST provides a dedicated batch file that can automate the upgrade of your Application schemas. You can find out more about this in Application and schema upgrade using a batch script.

Step 3 - Restart AIP Node

Restart the AIP Node - re-run the start shortcut or restart the the Windows service.

Step 4 - Check new AIP Core release is registered in AIP Console

Browse to your AIP Console URL http://<server>:8081/ui/index.html, login to AIP Console and in Application - Overview check that your Applications are showing the correct release of AIP Core - i.e. which release of AIP Core the schemas are set at - this release number should show the new AIP Core release number you have upgraded to:

Step 5 - Perform an Application resync in AIP Console

In AIP Console, perform an Application resync to ensure that AIP Console is fully up-to-date with the changes performed during the upgrade:

Step 6 - Run analysis and generate a new post upgrade snapshot

Although not mandatory, CAST highly recommends that a new analysis is run and a new snapshot is generated because it provides a way to compare the analysis results of the same source code in two distinct releases of AIP Core. If you don't want to generate a snapshot at this time, you can skip this step.

Pre-snapshot actions for specific technologies

Customers using the Siebel extension

Click here to expand...

If you have used the CAST Siebel extension and have generated a snapshot in the previous release of AIP Core, then you must follow the instructions explained in the Siebel extension documentation about re-running the Vanilla analysis BEFORE you generate a new snapshot with the new release of AIP Core. Please see Note about running a CAST AIP upgrade or an Extension upgrade for more information.

Customers upgrading with legacy BusinessObjects Analyzer results

Click here to expand...

CAST has provided support for analyzing SAP BusinessObjects source code via its BO Analyzer (provided out-of-the-box in AIP Core

  ≤ 8.2.x) for some time now. This "legacy" analyzer requires the following:

  • SAP BusinessObjects (the BO Designer module) must be installed on the workstation on which the CAST Management Studio is being run from.
  • you must manually define a connection to the SAP BusinessObjects instance on which your Universe files are used - this instance must be available during the analysis process in the CAST Management Studio - this is known as an "online" analysis.

These requirements can sometimes present significant difficulties for the process of on-boarding a SAP BusinessObjects application into CAST AIP. As a direct result of this and wanting to simplify the approach, CAST has developed the SAP BusinessObjects Analyzer as a standalone extension. The extension (introduced in CAST AIP 8.2.5) provides a means to analyze SAP BusinessObjects source code "offline", i.e. no connection to the SAP BusinessObjects instance is required. In addition there is no longer any requirement to have BusinessObjects (the BO Designer module) installed on the workstation on which the CAST Management Studio is being run from.

From CAST AIP ≥ 8.3.x, the legacy BO Analyzer (provided out-of-the-box in CAST AIP) is no longer available, therefore:

  • to analyze new SAP BusinessObjects applications, you must use the SAP BusinessObjects Analyzer (together with the CAST SAP BusinessObjects Extractor - not delivered with CAST AIP) which is delivered and installed automatically with CAST AIP 8.3.x with new CAST AIP triplets and as part of an upgrade.
  • for upgrades to CAST AIP ≥ 8.3.x, existing SAP BusinessObjects analyses will no longer function and will block the post-upgrade consistency snapshot. As such, CAST recommends that you transition to the SAP BusinessObjects Analyzer AFTER an upgrade, but BEFORE you generate a post-upgrade consistency snapshot (see Switching from legacy to new delivery/analysis method in SAP BusinessObjects Analyzer).

Customers upgrading from CAST AIP 8.1.0 (baseline) - snapshot validation

Click here to expand...

If you are upgrading from CAST AIP 8.1.0 (baseline) ONLY, you should check your snapshots for errors that may have occurred during the upgrade of the Measurement Service schema with CAST Server Manager. To do so:

  • connect and login to the Health Dashboard from the previous release of CAST AIP (this should still be available).
  • navigate through all the Applications that have been upgraded to the new release of CAST AIP and check the list of snapshots in the snapshot selector for each Application:


  • any snapshot Version name that contains the string "MIGR_ERROR_ALG_xxx_x_x" (for example "MIGRERROR_ALG_1106776204_3_4") was subject to an error that occurred during the upgrade of the Measurement Service schema with CAST Server Manager. It has not been possible to automatically repair this error and therefore the snapshot may produce erroneous data in the Health Dashboard or in the CAST Report Generator.

Resolution

If any existing snapshots are marked as containing an error, you need to perform a specific set of actions to remove and re-consolidate the snapshot (containing the error) in the Measurement Service schema. To do so: 

  • Launch the AadConsolidation-GUI.exe located in <CAST_AIP_installation_folder>\AAD\GUI:


  • In the GUI, tick the Reset option as shown above
  • Fill in the fields in the AAD Connection tab (as highlighted above) to connect to the Measurement Service schema in which the snapshots with errors have been consolidated. See HD - GUI common fields for more information.
  • Move to the Reset tab and fill in the three fields as follows, according to the Version name given to the snapshot that contains an error, for example: "MIGRERROR_ALG_1106776204_3_4"


  • the first figure, (here 1106776204) represents the site_id
  • the second one, (here 3), the application_id
  • the third one (here 4) the snapshot_id
  • Finally click the Run Application button to start the removal process:


  • Repeat this process for ALL snapshots in your upgraded Application that have an error in the Version name.
  • Finally, open the CAST Management Studio from the new release of CAST AIP, open the Application editor and move to the Execute tab
  • Click the Upload Snapshots to Measurement Service option to re-consolidate all snapshots for the current Application. Repeat for each Application as necessary.

Generate a new snapshot

To generate a new snapshot, move to the AIP Console screen if you are not already there:

Locate the Application and click it:

The Application - Overview page will be displayed. Scroll down to the bottom of the page and click the config icon:

Now choose the following options (untick those are not required) and click Run Analysis:

Alternatively you can click the Snapshots icon in the left panel to access the Application - Snapshots page and click the run button in the bottom right corner to choose your options:

You can check the results using the Engineering Dashboard - this is a quick and easy way to view the results. If you are using "embedded" dashboards, then you can click the Dashboard icons and instantly view the results - otherwise, you will need to log in to your standalone dashboards:

Step 7 - Run analysis and Upload to CAST Imaging

Just as with an analysis/snapshot, you can optionally run a new analysis and upload to CAST Imaging, or simply upload to CAST Imaging (without running a new analysis). To do so move to the AIP Console screen if you are not already there:

Locate the Application and click it:

The Application - Overview page will be displayed. Scroll down to the bottom of the page and click the config icon:

Now choose the following options (untick those are not required) and click Run Analysis:

Post upgrade

What happens to Assessment Models?

During the upgrade process, the following actions will have been performed:

  • Regardless of the Assessment Model Strategy you chose, the existing Assessment Model assigned to the Dashboard schema at the point of upgrade will have been upgraded and two copies of this Assessment Model will have been created:
    • one with the new CAST AIP Quality Rules merged in and enabled (Preserve Assessment Model customizations, activate new rules)
    • one with the new CAST AIP Quality Rules merged in and either disabled (Preserve Assessment Model customizations, leave new rules disabled) or enabled and set to zero weight (Preserve Assessment Model and get new rules for information)
    • Note that when there are no new rules available, a duplicate copy of the existing Assessment Model is NOT made.
  • If the Use default Assessment Model from CAST AIP 8.3.x option was chosen, a new default Assessment Model will have been created and any Assessment Model fragments from CAST AIP Extensions that were present in the Assessment Model assigned to the Dashboard schema at upgrade time will have been merged into this new Assessment Model
  • One of the above mentioned Assessment Models will have been assigned to the upgraded Dashboard schema, dependent on the Assessment Model Strategy option you chose

Assessment Model labels in CAST Management Studio

Click here to expand...

Assessment Models in the Assessment Models view will be labelled as follows after the upgrade:

Option chosen during upgradeAssessment Model label in CAST Management Studio

Preserve Assessment Model customizations,
activate new rules from AIP 8.3.x

"[current label] (upgraded, [version] new rules enabled)"

Preserve Assessment Model customizations,
leave new rules disabled		"[current label] (upgraded, [version] new rules disabled)"

Use default Assessment Model from
CAST AIP 8.3.x

"Default Assessment Model ([version] + Extensions)"

Unassociated Assessment Models will retain their existing label:

Validation message

Click here to expand...

If there are now more than three Assessment Models in the Assessment Models view in the CAST Management Studio following the upgrade process, a message will be logged in the Validation view:


The full message states as shown below. CAST highly recommends that you remove any Assessment Models that you no longer require so as to improve performance. You can export the Assessment Models to file (using the File > Export File option in the CAST Management Studio) prior to removing them.

Warning : There are more than 3 Assessment Models declared in the current management base, 
this can degrade the performances of CAST Management Studio. You should consider removing those which are no longer needed.

Custom tablespace

If you have configured any of the AIP schemas to use custom tablespace (i.e. tablespace other than pg_default which is automatically used when schemas are installed with AIP Console), following the schema upgrade you may find that some tables will now be using the default tablespace (pg_default) and some will still using the custom tablespace. If you wish to ensure that all your tables are using the same custom tablespace, you can run the following query to generate the required execution statements that will need to be run to do this. Ensure you update the following first:

  • <schema_name> = replace with the name of the schema
  • <tablespace_name> = replace with the name of the custom tablespace you want to use
SELECT 
  query 
FROM 
  (
    SELECT 
      1 as id, 
      'Set statement_timeout=0 ; ' as query 
    UNION 
    SELECT 
      2, 
      ' ALTER TABLE ' || schemaname || '.' || tablename || ' SET TABLESPACE <tablespace_name>;' 
    FROM 
      pg_tables 
    WHERE 
      schemaname ilike '<schema_name>' 
      and tablespace is null 
    UNION 
    SELECT 
      2, 
      ' ALTER INDEX ' || schemaname || '.' || indexname || ' SET TABLESPACE <tablespace_name>;' 
    FROM 
      pg_indexes 
    where 
      schemaname = '<schema_name>' 
      and tablespace is null
  ) a 
ORDER BY 
  a.id;