Summary: This section of documentation provides an explanation of how to automate the process of upgrading to CAST AIP 8.2.x using the CLI of the various tools involved.

Introduction

The process of upgrading to CAST AIP 8.2.x is described in detail in Upgrading to CAST AIP 8.2.x. This process relies heavily on the GUI of the various tools and software involved, however it is possible to automate most of the upgrade tasks. This page of documentation therefore provides an explanation of how to automate the process of upgrading to CAST AIP 8.2.x using the CLI (command line interface) of the various tools involved.

You should read and fully understand Upgrading to CAST AIP 8.2.x and make any preparations before you attempt to automate the upgrade process using the CLI!

Workflow

This guide uses the same workflow as described in Upgrading to CAST AIP 8.2.x (click to enlarge). It is possible to automate the first and third steps (marked in red in the image below) - this guide will concentrate on those steps.

In this section:

Target audience:

  • CAST administrators

Step 1: Prepare the upgrade

Summary: This step provides instructions for actions that must be executed BEFORE the new CAST AIP release and Service Pack setup is installed. 

Backup existing schemas on CAST Storage Service 2

Before starting the upgrade, CAST strongly recommends that any existing analysis and result data from previous releases of CAST AIP is backed up. You can automate the backup of any schemas you intend to upgrade and that are hosted on a CAST Storage Service 2 using the CLI based CSSBackup or CSSBackupAll tools. See Appendix - CAST Storage Service maintenance activities for more information.

CSSBackup or CSSBackupAll can be found in the CSSAdmin folder at the root of your CAST installation.

Examples

To backup one schema (repeat for each schema you would like to backup):

CSSBackup.exe -schema <schema_name> -password <CSS_Operator_password> -file <path_and_name_of_backup_file.cssdmp> -log <path_and_name_of_log_file.log>

To backup all schemas hosted on the CAST Storage Service 2:

CSSBackupAll.exe -password <CSS_Operator_password> -dumpdir <path_to_the_dump_folder> -log <path_and_name_of_log_file.log>

Step 2: Update process

CAST Update Tool upgrade process without extensions in CLI mode

To perform the CAST Update Tool (CUT) upgrade in CLI mode, use CUT-CLI.exe located at the root of your new CAST AIP installation (i.e the installation you are upgrading to) use the following command line (please see Automating CAST Update Tool tasks for more information about the CLI options):

CUT-CLI.exe -productInstallationDir "C:\Program Files\CAST\<version>" -pmxFileLocation "%APPDATA%\CAST\CAST\<version>\cast-ms.connectionProfiles.pmx" -assessmentModelUpgrade <choose option> -y -logfile "D:\CUT-CLI.castlog2"

You must choose a parameter for the -assessmentModelUpgrade option depending on your requirements. Please see Automating CAST Update Tool tasks for more information.

This command line will:

  • run the upgrade using the cast-ms.connectionProfiles.pmx file located in the %APPDATA%\CAST\CAST\<version> folder
  • ALL CAST Management Services schemas declared in the cast-ms.connectionProfiles.pmx (together with their associated Analysis and Dashboard Service schemas) will be upgraded!
  • the CAST Assessment Model will undergo the chosen upgrade process
  • the use of the -y option will force you to interact with a decision prompt to start the upgrade process
  • output the process to a log file.

When complete, please ensure you Validate the CAST Upgrade Tool execution to check additional logs generated by the CLI process.

Note that in CLI mode, ALL CAST Management Services schemas declared in the cast-ms.connectionProfiles.pmx (together with their associated Analysis and Dashboard Service schemas) will be upgraded! If you do not want to upgrade ALL CAST Management Services schemas declared in the PMX file, please comment out all the lines in cast-ms.connectionProfiles.pmx located in the %APPDATA%\CAST\CAST\<version> folder (using a text editor) that refer to Management Service schemas you DO NOT want to upgrade.

CAST Update Tool upgrade process with extensions in CLI mode

If you have installed and been actively using extensions - whether supplied by CAST, or custom extensions created by yourself - with the previous release of CAST AIP, you must ensure that you follow a specific upgrade process as detailed below.

To upgrade you must:

  • use the CAST Update Tool (the tool used to process the upgrade) in CLI mode and use a specific option (retain) that prevents the Assessment Model from undergoing any upgrade changes
  • use CAST Server Manager to upgrade any existing extensions to the most recent release
  • once the upgrade process is complete, you must then use the CAST Management Studio in CLI mode to upgrade just the Assessment Model

Each of these steps is explained below.

Run the upgrade in CLI mode using the "retain" option

See Automating CAST Update Tool tasks for more information about the CAST Update Tool (CUT) CLI options.

CUT-CLI.exe -productInstallationDir "C:\Program Files\CAST\<version>" -pmxFileLocation "%APPDATA%\CAST\CAST\<version>\cast-ms.connectionProfiles.pmx" -assessmentModelUpgrade retain -y -logfile "D:\CUT-CLI.castlog2"

This command line will:

  • run the upgrade using the cast-ms.connectionProfiles.pmx file located in the %APPDATA%\CAST\CAST\<version> folder
  • ALL CAST Management Services schemas declared in the cast-ms.connectionProfiles.pmx (together with their associated Analysis and Dashboard Service schemas) will be upgraded!
  • the CAST Assessment Model will NOT undergo any upgrade process at all and will be left exactly as it was in the previous release of CAST AIP
  • the use of the -y option will force you to interact with a decision prompt to start the upgrade process
  • output the process to a log file.
Note that in CLI mode, ALL CAST Management Services schemas declared in the cast-ms.connectionProfiles.pmx (together with their associated Analysis and Dashboard Service schemas) will be upgraded! If you do not want to upgrade ALL CAST Management Services schemas declared in the PMX file, please comment out all the lines in cast-ms.connectionProfiles.pmx located in the %APPDATA%\CAST\CAST\<version> folder (using a text editor) that refer to Management Service schemas you DO NOT want to upgrade.

Upgrade your extensions with Server Manager in CLI mode

You now need to upgrade any extensions that you were using prior to the CLI mode upgrade process you just completed. To do so, you need to use CAST Server Manager from your new installation of CAST AIP in CLI mode:

SERVMAN.EXE -INSTALL_CONFIG_FILE ("path_to_xml_file") -LOG(path_to_castlog,IMMEDIATE)
  • Instructions for the extension update must be placed in an XML file on disk.
  • You will need one XML file for each schema into which the extensions are installed (Analysis/Dashboard/Management). Extensions are NOT installed to the Measurement Service schema. In otherwords, you will need to run the CLI above three times: one for each schema in the "triplet".

An example XML file for an Analysis Service schema hosted on CSS is shown below:

<?xml version="1.0" encoding="ISO-8859-1"?>
<CAST-AutomaticInstall>
 <ServerInstall ProfileSystem="<name>" ServerType="CASTStorageService" UserSystem="operator" SystemPassword="CastAIP" ConnectionString="LIBPQ:<server_name>:2280" >
  <InstallDatabase DbName="<analysis_service_database_name>" >
    
   <!-- Extensions: install a specific version -->
   <Plugin id="com.castsoftware.angularjs" version="1.3.0-funcrel"/>
    
   <!-- Extensions: install most recent that has been downloaded -->
   <!-- <Plugin id="com.castsoftware.html5"/> -->
    
   <!-- Extensions: automatically install any required dependencies, using the most recent version that has been downloaded -->
   <InstallDependencies strategy="TakeLatest"/>
 
   <!-- Extensions: prevents installation from the legacy %programdata%\CAST\CAST\<version> location -->
   <SkipLookupLegacyUADefaultLocation/>  
 
  </InstallDatabase>
 </ServerInstall>
</CAST-AutomaticInstall>

Upgrade the Assessment Model with the CAST Management Studio in CLI mode

You now need to upgrade your Assessment Model. To do so, you need to use the CAST Management Studio from your new installation of CAST AIP in CLI mode:

Choose Assessment Model handling option

Please refer to Upgrading to CAST AIP 8.2.x for more information: Choose Assessment Model handling option

Run the Assessment Model upgrade in CLI mode

Please refer to Upgrading to CAST AIP 8.2.x for more information: Run the Assessment Model upgrade in CLI mode

Update process for CAST Measurement Service (CAST Server Manager)

The update process for the CAST Measurement Service used by the CAST Application Analytics Dashboard, is (exceptionally) carried out with the end user application CAST Server Manager - see Automating CAST Server Manager installation tasks for more information.

  • when migrating from CAST AIP 8.2.0 (baseline) to a Service Pack or between CAST AIP 8.2.x Service Packs, this CAST schema does NOT require an update and you can SKIP this section.
  • CAST Server Manager must not be used for updating Management, Analysis and Dashboard Services

Run the CLI as follows, ensuring that the -UPGRADE switch is used:

SERVMAN.EXE -INSTALL_CONFIG_FILE ("path_to_xml_file") -UPGRADE -LOG(c:\log.castlog, -IMMEDIATE)

The XML file specified in the -INSTALL_CONFIG_FILE option should take the following form:

<?xml version="1.0" encoding="ISO-8859-1"?>
<CAST-AutomaticInstall>
<!-- Use either ServerName= or ConnectionString= -->
 <!-- <ServerInstall ProfileSystem="PROFILE_NAME" ServerType="CASTStorageService" UserSystem="operator" SystemPassword="CastAIP" ServerName="CEIRIAD:2280" > -->
 <ServerInstall ProfileSystem="PROFILE_NAME" ServerType="CASTStorageService" UserSystem="operator" SystemPassword="CastAIP" ConnectionString="LIBPQ:CEIRIAD:2280" >
  <InstallDatabase DbName="DB_NAME" >
    <PackName >AAD_MAIN</PackName>
  </InstallDatabase>
 </ServerInstall>
</CAST-AutomaticInstall>