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.
To use the batch script, you must ensure the following prerequisites are met:
|Target AIP Core release must be installed from setup - see AIP Core upgrade.|
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.
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.
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|
|8.3.10 - 8.3.11|
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|
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_PATH||Folder 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_HOME||Path 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 ( \ ).|
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 ( \ ):
|EXCEL_EXE||Path to an installation of Microsoft Excel, used to generate a "delta comparison". See ACTIVATE_DELTA in CASTUpgrade_Steps.txt below for more information.|
|DELTA_FILE||Leave 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 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.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
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:
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
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:
List the IDs, separated by commas, of the extensions you want to install as part of the upgrade process - the extensions will be automatically installed in all combined schema installs specified for upgrade. These extensions should already exist in the following location on the current AIP Node:
The extension ID can be found in the extension's .nuspec file, usually in the root folder of the extension, for example:
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:
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:
Both discoverers can be enabled (separate them with a semi-colon - ;), just one, or none at all. For example:
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:
|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):
Note that the following script files (provided in the target CAST AIP installation folder are also run
|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:
|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 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.
The following section lists the error numbers that may be returned when attempting to run the upgrade via the batch script:
|3001||An 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.|
|3002||An 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.|
|3003||An 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.|
|3004||The 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.|
|3006||The 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|
|3007||An error exists in the AIP Core metamodel that is preventing the upgrade from proceeding.||Please contact CAST Support for help with this error.|
|3008||An SQL error has occurred during the upgrade process.||Please contact CAST Support for help with this error.|