Created by James Hurrell on Mar 24, 2023

Summary: this page discusses how to use the pre-prepared batch script to perform an application and schema upgrade silently. This script uses the Command Line Interface of various CAST AIP tools.

Introduction

Although it is possible to upgrade to a new release using GUI tools, CAST has also provided a batch script to do the job for you. The advantage of this batch script is that:

  • It completes the upgrade silently
  • Is a one click solution meaning you can avoid having to use multiple tools to achieve the same result
  • It is pre-prepared meaning you don't need to search CAST AIP documentation to locate CLI documentation for the required tools

What does the batch script do?

The batch script functions on a per "combined schema install" basis, therefore it can perform the following upgrade related actions on each defined "combined schema install":

  • Backup of:
    • All CAST AIP schemas (Management, Analysis, Dashboard) in a "combined schema install"
    • Delivery folder associated to the Management schema in the "combined schema install"
  • Upgrade of:
    • The Management schema in the "combined schema install"
    • All associated Analysis and Dashboard schemas
    • All associated Applications
    • All associated Assessment Models
    • Associated Delivery folder
    • All CAST AIP extensions that are already installed in the "combined schema install"
  • Installation, on demand, of:
    • any new releases of CAST AIP extensions that have already been downloaded
  • Run a post-upgrade consistency snapshot - optionally

What doesn't the script do?

The batch script does not:

  • Upgrade the Measurement schema. Note that upgrading the Measurement schema  is NOT required when using AIP Console to manage your Applications.
  • Upgrade "combined schema install" hosted on multiple host CAST Storage Services/PostgreSQL instanced: all "combined schema installs" must be located on the same host CAST Storage Service/PostgreSQL instance. However, if you need to upgrade multiple combined schema installs located on multiple CAST Storage Services/PostgreSQL instance, then you should duplicate the "tools\Upgrade\template" folder for each CAST Storage Service/PostgreSQL instance you want to work with - see Copy the template folder below for more information about this.

Prerequisites

To use the batch script, you must ensure the following prerequisites are met:

(tick)Target AIP Core release must be installed from setup - see AIP Core upgrade.

Preparation

Locate the batch script and associated configuration files

The pre-prepared batch script is available in the AIP Core installation folder under tools\Upgrade\template - ensure you are using the new AIP Core installation/upgrade:

Copy the template folder

The script provided at tools\Upgrade\CASTUpgrade.bat must NOT be changed. It contains parameters which can be defined in the files provided in the sub-folder tools\Upgrade\template. Copy the entire content of tools\Upgrade\template into a new folder (you might not have the correct privileges to modify them in a new folder located within the AIP Core installation folder), for example D:\CAST\Upgrade and use the copies to run the upgrade.

If you need to upgrade multiple combined schema installs located on multiple CAST Storage Services/PostgreSQL, then you should duplicate the "tools\Upgrade\template" folder for each CAST Storage Service you want to work with.

Update the CASTUpgradeRun.bat file 

The file CASTUpgradeRun.bat located in your copied template folder contains a line which identifies the location of the AIP Core installation folder. Please open this file and check it as follows:

  • In older releases of AIP Core, the installation location of AIP Core is hardcoded into this file (e.g. C:\Program Files\CAST\8.3) and assumes that AIP Core is installed in the default location. Therefore, IF the file contains a hardcoded path to AIP Core, please ensure that the path is correct for your own environment and adapt it if necessary (i.e. if you have installed AIP Core in a non-standard location).
  • In more recent releases of AIP Core, a variable called %CAST_HOME% is used to define the location of AIP Core. Therefore, if you see this variable, then there is nothing further to do. The variable is defined in the file CASTUpgrade_Config.txt (see below).

Set the variables

Open each of the following files in the copied template folder and configure each of them for your environment.

CASTUpgrade_ServerConnection.txt

This file allows you to specify the host CAST Storage Service/PostgreSQL on which the specified CAST AIP schemas are located. You can only choose one host CAST Storage Service/PostgreSQL instance and therefore all  CAST AIP schemas must be located on the same host:

8.3.0 - 8.3.9
HOST=<host_machine_name_or_IP_address>
PORT=<CAST_Storage_Service_port_number>
USER_ID=operator
PASSWD_CRYPTED=<encrypted_password_for_USER_ID>
8.3.10 - 8.3.11
HOST=<host_machine_name_or_IP_address>
PORT=<CAST_Storage_Service_port_number>
USER_ID=operator
PASSWD_CRYPTED=<encrypted_password_for_USER_ID>
DATABASE=<CAST_Storage_Service_database_name>
≥8.3.12
HOST=<host_machine_name_or_IP_address>
PORT=<CAST_Storage_Service_port_number>
USER_ID=operator
DATABASE=<CAST_Storage_Service_database_name>

Available parameters:

Option

Example

HOST

All of these items can be found in the following file:

%APPDATA%\CAST\CAST\<AIP_target_version>\cast-ms.connectionProfiles.pmx


PORT

USER_ID

PASSWD_CRYPTED

Note: This field is valid only for versions ≤ 8.3.11

DATABASE

Note: This field is valid only for versions ≥ 8.3.10

Specify the database name. In the majority of situations this will be "postgres".

Example:

HOST=SERVER1
PORT=2282
USER_ID=operator
PASSWD_CRYPTED=CRYPTED2:90B8661401B724DB5AC34595
DATABASE=postgres

CASTUpgrade_Config.txt

This files defines various technical parameters:

8.3.0 - 8.3.9 
OUT_PATH=<path_to_working_folder>
DUMP_PATH=<path_to_backup_folder>
LOG_PATH=<path_to_log_folder>
CAST_HOME=<path_to_target_CAST_AIP_installation_folder>
EXCEL_EXE=<path_to_EXCEL.EXE_file>
DELTA_FILE=C:\ProgramData\CAST\CAST\Extensions\com.castsoftware.deltareportsanpshot.1.0.0\Upgrade_Delta_Explanation.xlsm
ANALYSIS_DELTA_FILE=C:\ProgramData\CAST\CAST\Extensions\com.castsoftware.deltareportanalysis.1.0.0\Upgrade_Delta_Explanation.xlsm 

#To activate the debug, put 1
_DEBUG_=1
≥ 8.3.10
OUT_PATH=<path_to_working_folder>
DUMP_PATH=<path_to_backup_folder>
LOG_PATH=<path_to_log_folder>
CAST_HOME=<path_to_target_CAST_AIP_installation_folder>
PSQL_PATH=<path_to_PSQL.exe>

#To activate the debug, put 1
_DEBUG_=1

Available parameters:

Option

Example

OUT_PATH

Folder in which temporary working files will be generated during the process, e.g.: D:\Data\Upgrade\Out\ - this folder will be created on disk if it does not already exist.

DUMP_PATH

Folder in which backup files will be stored (i.e. CAST AIP schemas and Delivery folder), e.g.: D:\Data\Upgrade\Dump\ - this folder will be created on disk if it does not already exist.
LOG_PATHFolder in which log files for the process will be generated, e.g.: D:\Data\Upgrade\Log\ - this folder will be created on disk if it does not already exist.
CAST_HOMEPath to the AIP Core installation folder - this must be the release you are upgrading to (i.e. the target release). This path must not end with a back slash ( \ ).
PSQL_PATH

This optional parameter is used to define the locations of the psql.exe binary that is used to perform the upgrade. Unless you specifically need to change this, you should leave this parameter empty (recommended). This will ensure that the default path (%PROGRAMFILES%\CAST\<version>\CSSAdmin\3rdParties\x64pg11) is used:

PSQL_PATH=

If you need to use a different psql.exe binary, you can define a new path as follows - note that this path must not end with a back slash ( \ ):

PSQL_PATH= <path_to_psql.exe>
EXCEL_EXEPath to an installation of Microsoft Excel, used to generate a "delta comparison". See ACTIVATE_DELTA in CASTUpgrade_Steps.txt below for more information.
DELTA_FILELeave this path as is.
ANALYSIS_DELTA_FILE

_DEBUG_

Set to 1 to activate debug mode for logs.

CASTUpgrade_Schemas.txt

This file allows you to specify a set of one or multiple CAST AIP schemas for upgrade. Use one line per Management Service schema/extension list/Assessment Model strategy/discoverers to enable using the following syntax - multiple lines (and therefore multiple combined schema installs) are supported, however, all combined schema installs must be located on the same host CAST Storage Service.

8.3.0 - 8.3.7
<mb_prefix>:<extension_list_to_install>:<assessmentModelUpgrade>:<discoverers_to_enable>
≥ 8.3.8
<management_schema_name>:<extension_list_to_install>:<assessmentModelUpgrade>:<discoverers_to_enable>

Available parameters:

Option

Example

<mb_prefix>

8.3.0 - 8.3.7

Enter the prefix used for the combined schema install you would like to upgrade. To find the prefix, 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. The schema prefix is highlighted:

<management_schema_name>

≥ 8.3.8

Enter the name of the Management Service schema for the combined install that you want to upgrade. To find the Management schema name, 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. The Management schema name is highlighted:

<extension_list_to_install>

List the IDs, separated by commas, of the extensions you want to install or upgrade as part of the upgrade process - the extensions listed will be automatically installed  or upgraded in all combined schema installs specified for upgrade. These extensions should already exist in the following location on the current Node:

%PROGRAMDATA%\CAST\CAST\Extensions

The extension ID can be found in the extension's .nuspec file, usually in the root folder of the extension, for example:


  • This option is for extensions that have not yet been installed and that you would like to install during the upgrade process, or for extensions that have already been installed but require upgrading during the upgrade process.
  • Any extension that is already installed on the combined schema installs specified for upgrade and where a newer version exists in %PROGRAMDATA%\CAST\CAST\Extensionson the Node will NOT be upgraded to the newer release unless it is listed in this file.
  • If you do not want to specify any extensions, you must use empty white space between the colons as follows:
8.3.0 - 8.3.7
<mb_prefix>: :

≥ 8.3.8
<management_schema_name>: :


<assessmentModelUpgrade>

Choose from one of the following options for your triplet (and all its Applications) as described in AIP Core - Application - schema upgrade on each AIP Node. You must choose an option:

  • activateNewRules
  • disableNewRules
  • replaceByNewAssessmentModel

<discoverers_to_enable>

This optional setting is available in CAST AIP ≥ 8.3.5. It allows you to choose which discoverers should be automatically enabled when the post-upgrade consistency snapshot is generated by the batch script (ACTIVATE_CONSISTENCY = Y in the CASTUpgrade_Steps.txt file). In normal circumstances, no discoverer is enabled for existing CAST Delivery Manager Tool packages (to eliminate the impact to post-upgrade snapshot results), however in some circumstances, it is desirable to enable a particular discoverer.

The following discoverers can be enabled automatically:

DiscovererDescription
HTML5 project

This discoverer is provided in the Web Files Discoverer, which is shipped and installed by default with CAST AIP 8.3.x as part of the upgrade. When enabled, Web File Discoverer (i.e. HTML5 projects) projects will be identified and corresponding Analysis Units will be generated. All files "captured" in these "HTML5 project" Analysis Units will be analyzed (predominately HTML and JavaScript files).

CAST highly recommends enabling this option if the Application you are upgrading contains HTML/JavaScript files and you need them to be analyzed. In previous releases of CAST AIP, HTML/JavaScript files were analyzed by the JEE and NET Analyzers, but in CAST AIP ≥ 8.3.x, this is no longer the case (now handled by the HTML5 and JavaScript extension), therefore to retain consistency, we recommend enabling this option to allow HTML/JavaScript files to be analyzed.

XML scannerThis discoverer is provided in the DMT Framework Scanner, which is shipped and installed by default with CAST AIP 8.3.x as part of the upgrade. When enabled, the information generated by the DMT Framework Scanner extension can be seen in the CAST Delivery Manager Delivery Report for existing packages that have been upgraded.

Both discoverers can be enabled (separate them with a semi-colon - ;), just one, or none at all. For example:

8.3.0 - 8.3.7

TRIPLET1PREFIX:com.castsoftware.flex:replaceByNewAssessmentModel:HTML5 project;XML scanner
TRIPLET1PREFIX:com.castsoftware.flex:replaceByNewAssessmentModel:HTML5 project
TRIPLET1PREFIX:com.castsoftware.flex:replaceByNewAssessmentModel:XML scanner
TRIPLET1PREFIX:com.castsoftware.flex:replaceByNewAssessmentModel:

≥ 8.3.8

<management_schema_name>:com.castsoftware.flex:replaceByNewAssessmentModel:HTML5 project;XML scanner
<management_schema_name>:com.castsoftware.flex:replaceByNewAssessmentModel:HTML5 project
<management_schema_name>:com.castsoftware.flex:replaceByNewAssessmentModel:XML scanner
<management_schema_name>:com.castsoftware.flex:replaceByNewAssessmentModel:

Example:

8.3.0 - 8.3.7

TRIPLET1PREFIX:com.castsoftware.angularjs,com.castsoftware.flex:replaceByNewAssessmentModel:
TRIPLET2PREFIX:com.castsoftware.angularjs:activateNewRules:
TRIPLET3PREFIX:com.castsoftware.flex:replaceByNewAssessmentModel:HTML5 project;XML scanner
TRIPLET4PREFIX: :replaceByNewAssessmentModel:

≥ 8.3.8

<management_schema_name_1>:com.castsoftware.angularjs,com.castsoftware.flex:replaceByNewAssessmentModel:
<management_schema_name_2>:com.castsoftware.angularjs:activateNewRules:
<management_schema_name_3>:com.castsoftware.flex:replaceByNewAssessmentModel:HTML5 project;XML scanner
<management_schema_name_4>: :replaceByNewAssessmentModel:

CASTUpgrade_Steps.txt

This files defines the upgrade steps to perform. This provides flexibility in how you want to work, i.e. you can choose only to run the backup step, or only the upgrade:

#Activation of the different steps for each application
ACTIVATE_BACKUP=Y
ACTIVATE_CLEANUP=N
ACTIVATE_UPGRADE=Y
EXTENSIONS_LATEST_DEPENDENCIES=Y
ACTIVATE_CONSISTENCY=Y
#To limit the consistency to the snapshot (after the update of the AM with extensions), set the option CONSISTENCY_MODE to SNAPSHOT
CONSISTENCY_MODE=
ACTIVATE_RECOVERY=N
INSTALL_CUSTOM_UA_LEGACY=N

Available parameters:

Option

Example

ACTIVATE_BACKUP

Y (to execute the step) or N. Allows you to choose whether to perform the backup of the CAST AIP schemas and Delivery folder.
ACTIVATE_CLEANUP

Y (to execute the step) or N. Allows you to choose whether to run the following scripts files which are provided empty in your copied folder (you will need to provide the script):

  • analysis_cleanup.sql
  • dashboard_cleanup.sql
  • management_cleanup.sql

Note that the following script files (provided in the target CAST AIP installation folder are also run

  • duplicate_entry_in_transaction.sql
  • ghost_project_object_cleanup.sql
  • update_existing_UA.sql

ACTIVATE_UPGRADE

Y (to execute the step) or N. Allows you to choose whether to perform the upgrade step.

EXTENSIONS_LATEST_DEPENDENCIES

Y (to execute the step) or N. By default, extensions specified in the CASTUpgrade_Schemas.txt file will be installed automatically. This option allows you choose whether to ALSO install the most recent versions of dependent extensions (if available on disk) for extensions specified in the CASTUpgrade_Schemas.txt file.

ACTIVATE_CONSISTENCY

Y (to execute the step) or N. Option to run the post upgrade consistency process step. This includes the following CMS CLI options:

  • AutomateDelivery
  • SetAsCurrentVersion
  • Run Analysis
  • GenerateSnapshot

CONSISTENCY_MODE

Setting this option to SNAPSHOT - will limit the ACTIVATE_CONSISTENCY option to GenerateSnapshot (i.e. to a snapshot only).

ACTIVATE_DELTA

Set to N. This option is not yet supported.

ACTIVATE_RECOVERY

Y (to execute the step) or N. Allows you to choose whether to perform the recovery step - the items backed up in the ACTIVATE_BACKUP step will be restored.

This option should be used in isolation - i.e. if you need to run a recovery, then set all other options to N. Similarly if you are running any other ACTIVATE_* option, then ensure you set ACTIVATE_RECOVERY to N.

INSTALL_CUSTOM_UA_LEGACY

Y (to execute the step) or N (default).

When set to N (default) any custom legacy language packs that are present in <CAST_ALL_USERS_PATH>\configuration\languages where <CAST_ALL_USERS_PATH> is the value defined in the CastGlobalSettings.ini file (the default value is %PROGRAMDATA%\CAST\CAST\<version>) will NOT be installed as part of the upgrade.

The <CAST_ALL_USERS_PATH>\configuration\languages is known as the <all users dir> in the Manage Extensions dialog box in CAST Server Manager:

 

You should set this option to Y if you have explicitly copied any custom legacy language packs that were present in the previous CAST AIP installation into <CAST_ALL_USERS_PATH>\configuration\languages where <CAST_ALL_USERS_PATH> is the value defined in the CastGlobalSettings.ini file (the default value is %PROGRAMDATA%\CAST\CAST\<version>) AND you would like these custom legacy language packs to be installed in the new release of CAST AIP.

Note that this is equivalent to the <SkipLookupLegacyUADefaultLocation/> in the CAST Server Manager CLI. See SRV - Command Line for more information.


Run the upgrade

  • To run the upgrade, double click CASTUpgradeRun.bat in the copied template folder. Do not attempt to run the tools\Upgrade\CASTUpgradeRun.bat file as the process will error.
  • You will first be prompted to enter the password for the operator user on your target CAST Storage Service. Even though this password is defined in the CASTUpgrade_ServerConnection.txt file you will be prompted for it as a security mechanism to prevent accidental or malicious upgrades from being run. In CAST AIP versions ≥ 8.3.12, an environment variable called "CSSPASSWORD" has been introduced to prevent the upgrade batch from prompting for a password for the CAST Storage Service operator user. This variable can be set by entering SET CSSPASSWORD=<PASSWORD> in a cmd window prior to running the CASTUpgradeRun.bat file in the same cmd window.
  • Finally you can follow the upgrade progress in the console. The same information will be made available in the main log file <timestamp>_CASTUpgrade.log created in the log folder you’ve defined using t he LOG_PATH variable in the CASTUpgrade_Config.txt file.
If you have set the ACTIVATE_CONSISTENCY option to Y in the CASTUpgrade_Steps.txt file, you will not need to generate a new snapshot.

Error numbers

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

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.