Page tree

On this page:

Target audience:

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


Although it is possible to upgrade CAST AIP 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 Service) in a "combined schema install"
    • Delivery folder associated to the Management Service schema in the "combined schema install"
  • Upgrade of:
    • The Management Service schema in the "combined schema install"
    • All associated Analysis and Dashboard Service 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

What doesn't the script do?

The batch script does not:

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


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

(tick)Target CAST AIP release must be installed from setup.
(tick)Ensure you have read Preparing for upgrade and completed any required actions.


Locate the batch script and associated configuration files

The pre-prepared batch script is available in the CAST AIP installation folder under tools\Upgrade\template:

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 CAST AIP 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, 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 CAST AIP installation folder. Please open this file and check it as follows:

  • In older releases of CAST AIP, the installation location of CAST AIP is hardcoded into this file (e.g. C:\Program Files\CAST\8.3) and assumes that AIP is installed in the default location. Therefore, IF the file contains a hardcoded path to CAST AIP, please ensure that the path is correct for your own environment and adapt it if necessary (i.e. if you have installed AIP in a non-standard location).
  • In more recent releases of CAST AIP, a variable called %CAST_HOME% is used to define the location of CAST AIP. 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.


This file allows you to specify the host CAST Storage Service on which the specified CAST AIP triplet(s) is located. You can only choose one host CAST Storage Service and therefore all CAST AIP triplets must be located on the same host:

8.3.0 - 8.3.9
8.3.10 - 8.3.11

Available parameters:




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





Note: This field is valid only for versions  8.3.11


Note: This field is valid only for versions ≥ 8.3.10

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




This files defines various technical parameters:

8.3.0 - 8.3.9

#To activate the debug, put 1
≥ 8.3.10

#To activate the debug, put 1

Available parameters:




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.


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 CAST AIP 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 ( \ ).

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:


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.


Set to 1 to activate debug mode for logs.


This file allows you to specify a set of one or multiple CAST AIP schemas (installed in "combined mode") 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
≥ 8.3.8

Available parameters:




8.3.0 - 8.3.7

Enter the prefix used for the combined schema install you would like to upgrade. The prefix can be found in the CAST Management Studio > Application editor > Execute tab and will precede the words _local, _central, _mngt. In the example below, the prefix is v830:


≥ 8.3.8

Enter the name of the Management Service schema for the combined install that you want to upgrade. This can be found in the CAST Management Studio connection profile:


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 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\Extensions 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>: :


Choose from one of the following options for your triplet (and all its Applications) as described in Preparing for upgrade. You must choose an option:

  • activateNewRules
  • disableNewRules
  • replaceByNewAssessmentModel


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:

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

≥ 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


8.3.0 - 8.3.7

TRIPLET3PREFIX:com.castsoftware.flex:replaceByNewAssessmentModel:HTML5 project;XML scanner
TRIPLET4PREFIX: :replaceByNewAssessmentModel:

≥ 8.3.8

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


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
#To limit the consistency to the snapshot (after the update of the AM with extensions), set the option CONSISTENCY_MODE to SNAPSHOT

Available parameters:




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

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


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


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.


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


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


Set to N. This option is not yet supported.


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.


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 Automating CAST Server Manager installation tasks 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.
  • Once the upgrade has completed, please read Post upgrade action items for information about what you should expect after completing an upgrade and any action items you may need to complete.
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 as discussed in Post upgrade action items.

Error numbers

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

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.

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.
  • No labels