Step 1 - Backup your data

This documentation is only valid for installations of CAST Imaging on Microsoft Windows.

Overview

This initial step involves taking a backup copy of your v2 data on your v2 machines and transferring it to the relevant machine where your CAST Imaging v3 components are installed. These backups will be restored as part of the migration process. All backup actions are performed on machines where v2 components are installed.

Note that when you are migrating from a CAST Console v2 standalone installation it is not necessary to backup any Console related data since in this scenario, CAST Imaging v3 needs to be installed on the same machine and therefore the transfer of data between CAST Console v2 and CAST Imaging v3 is automated as part of Step 2 - Migrate your data. The backup of CAST Imaging Viewer v2 data is still required and must be actioned (see Step 1 - Backup your CAST Imaging Viewer v2 results).

Requirements

See Requirements.

You should also ensure:

that you have a copy of the com.castsoftware.imaging.migrationtool extension on the machines where the CAST Console v2 backup will be run:
- for an enterprise/distributed migration, any machine acting as a CAST Console v2 node.
- for a standalone migration, the machine where all CAST Imaging v2 components are installed.
that you have access to the Neo4j backup tool provided with your v2 installation in %PROGRAMFILES%\CAST\ImagingSystem\neo4j\bin\neo4j-admin.

Process

Step 1 - Set-up the backup configuration file

Valid for ≥ 1.1.0-funcrel of com.castsoftware.imaging.migrationtool - you should follow the instructions in Appendix below if you are using an older release.

The backup process is run via a batch file which refers to a configuration file containing various options that determine how the backup is actioned. Therefore, the first step is to set-up this configuration file: you can find it at the root of the unzipped migration tool extension, called backup.conf.

The configuration file contains three distinct sections, described below:

General options
Neo4j options
Console options

General options

Option Description

option= Choose one of the following - all options should ONLY be run once:

- All: backup both CAST Imaging Viewer v2 and Console v2, i.e. for a standalone/single machine deployment of CAST Imaging Viewer v2 and CAST Console v2 where both components are all installed on the SAME machine.

- Neo4j: backup only CAST Imaging Viewer v2, must be run on the machine where the CAST Imaging Viewer v2 component is installed.

- Console: backup only CAST Console v2, must be run on a machine where the CAST Imaging Console v2 component is installed.

Option	Description
`option=`	Choose one of the following - all options should ONLY be run once: - `All`: backup both CAST Imaging Viewer v2 and Console v2, i.e. for a standalone/single machine deployment of CAST Imaging Viewer v2 and CAST Console v2 where both components are all installed on the SAME machine. - `Neo4j`: backup only CAST Imaging Viewer v2, must be run on the machine where the CAST Imaging Viewer v2 component is installed. - `Console`: backup only CAST Console v2, must be run on a machine where the CAST Imaging Console v2 component is installed.

Neo4j options

These options define the CAST Imaging Viewer v2 backup:

Option	Description
`neo4j_adminpath=`	Path to the Neo4j administration tool `neo4j-admin` in your CAST Imaging Viewer v2 installation. Unless you have customized this location, use the default path (using standard Microsoft Windows back slashes): `C:\Program Files\CAST\ImagingSystem\neo4j\bin`.
`neo4j_backupdir=`	Specifies an absolute path to the target folder for the resulting backup. This folder must already exist.
`neo4j_host=`, `neo4j_port=`	The details of your Neo4j instance, i.e. as installed with CAST Imaging Viewer v2. Unless you have customized this, use the default options provided in the configuration file.

Console options

These options define the CAST Console v2 backup:

Option	Description
`process=`	Determines the type of backup: use `All` unless directed to use a different option by CAST Support.
`log=`	A local folder for storing the migration log files. Use a standard Microsoft Windows path with back slashes, e.g.: `C:\temp\logs`. The tool will attempt to create this folder if it cannot be found.
`casthomedir=`	CAST AIP Core 8.3 installation folder (using standard Microsoft Windows back slashes), e.g.: `C:\Program Files\CAST\8.3` (mandatory).
`nodedatadir=`	CAST Console AIP Node v2 data folder containing the `application-default.yml` file (using standard Microsoft Windows back slashes), e.g.: `C:\ProgramData\CAST\AIP-Node` (default: None).
`nodeschema=`	Name of the CAST Console AIP Node v2 specific schema (default: `aip_node`).
`configschema=`	Name of the CAST Console v2 configuration storage schema (default: `aip_config`).
`workingdir=`	Temporary processing location on disk (using standard Microsoft Windows back slashes) which MUST exist before using the tool e.g. `C:\temp\workingdir`. If not specified, this path is calculated automatically based on the `CAST_CURRENT_USER_TEMP_PATH` value defined in the `CastGlobalSettings.ini` file (part of CAST AIP Core 8.3).
`outputdir=`	Location on disk (using standard Microsoft Windows back slashes) where the output ZIP file will be stored, e.g. `C:\temp\output`. This folder MUST exist on disk before running the action.
`zipfilename=`	Name of the output ZIP file.
`css_host=`	Hostname/IP address of the database instance where the v2 `aip_node` and `aip_config` schemas are stored (default: `localhost`).
`css_user=`	Username used to connect to database instance defined by `css_host=` (default: `operator`).
`css_port=`	Port for database instance defined by `css_host` (default: `2284`).
`css_database=`	Name of the database in which the v2 `aip_node` and `aip_config` schemas are stored on the database instance (default: `postgres`).
`psqldir=`	`psql.exe` file location. By default `psql.exe` provided in CAST AIP Core 8.3 (defined by the `casthomedir=` option) is always used therefore unless you need to use a different `psql.exe` file, leave this option empty.
`validationreport=`	Sets the path for the validation report which is generated each time the batch is run.

Step 2 - Run the backup

Valid for ≥ 1.1.0-funcrel of com.castsoftware.imaging.migrationtool - you should follow the instructions in Appendix below if you are using an older release.

To run the backup:

Connect to your chosen CAST v2 machine, depending on the backup options you have configured in the backup.conf file.
Open a brand new CMD window (do NOT re-use any existing CMD windows that you may have used to perform other actions) with elevated permissions (right click, Run as administrator) and navigate to the root of the unzipped migration tool extension.
Execute the following command to set the password for the database user defined by the option css_user= in the backup.conf file (otherwise you will be prompted to enter this during the backup):

SET CSSPASSWORD=CastAIP

Now execute the Cast_Node_V2_Backup_Enterprise.bat file provided at the root of the unzipped migration tool extension with the option reportonly:

Cast_Node_V2_Backup_Enterprise.bat reportonly

This will run the backup in test mode only: no backup actions will be performed, instead checks are performed and a report will be generated and output to the path defined by the option validationreport= in the backup.conf file. The report contains information about each application and its suitability for migration and you should check it before proceeding. See Compatibility/validation reports for more information.
If all checks have passed you can now proceed with the “real” backup by running the same batch file without any options:

Cast_Node_V2_Backup_Enterprise.bat

On completion, check the log file (defined by the option log= in the backup.conf file). If the backup log shows errors, you should investigate and contact CAST Support if you are unable to proceed.
Finally, locate the output ZIP generated by the tool and transfer it to a machine hosting the v3 analysis-node component (i.e. a v3 node machine). If you have multiple v3 nodes you can copy the output ZIP to any of them.

What’s next?

You must now perform the migrate action as described in Step 2 - Migrate your data. This will migrate the v2 data to CAST Imaging v3.

Appendix

This section contains alternative Step 1 and Step 2 instructions and is specifically and only for use with older releases of com.castsoftware.imaging.migrationtool, i.e. ≤ 1.0.x-funcrel.

Appendix - Step 1 - Backup your CAST Imaging Viewer v2 results

These instructions are specifically for those that are using CAST Imaging Viewer v2 (i.e. via this extension ) with analyzed applications who want to migrate to CAST Imaging v3.

On the machine hosting your CAST Imaging Viewer v2 installation, run a backup of your existing Neo4j databases using the Neo4j backup tool provided with your v2 installation. This backup will be restored to the CAST Imaging v3 installation (described in a later step). For example:

set HEAP_SIZE=4G
"%PROGRAMFILES%\CAST\ImagingSystem\neo4j\bin\neo4j-admin" backup --from=localhost:6362 --backup-dir=C:\\temp\\backup --database=* --include-metadata=all --pagecache=4G

Where:

--from defines the machine on which CAST Imaging is running - set this to localhost:6362. “6362” is the default listening port for backup operations.
--backup-dir specifies an absolute path to the target folder for the resulting backup. This folder must already exist. You must use escaped backslashes in the path.
--database=* the * option will backup all databases (one “tenant” in CAST Imaging v2 is equal to one database)
--include-metadata set this to all to ensure that any roles you have defined are also backed up
--pagecache defaults to 8MB, so use this option to ensure you specify a large amount of RAM (e.g. 4GB) to improve performance.

A consistency check will be actioned by default - this is recommended, but can be disabled using --check-consistency=false. The resulting backup of each CAST Imaging v2 database (i.e. tenant) will be stored in a dedicated sub folder of the folder defined by the --backup-dir command.

See also https://neo4j.com/docs/operations-manual/4.2/backup-restore/online-backup/ for more information.

When the backup is complete:

If the CAST Imaging v3 imaging-viewer component is installed on the same machine, there is nothing further to do - the target folder needs to be referenced during the migration, see Step 2 - Migrate your data.
If the CAST Imaging v3 imaging-viewer component is installed on a different machine, transfer the folder and its entire contents to this other machine.

Appendix - Step 2 - Backup your CAST Console v2 enterprise installation

These instructions are specifically for those that are currently using CAST Console v2 in “enterprise” mode (i.e. via this extension ) with analyzed applications who want to migrate to CAST Imaging v3.

Connect to a v2 node machine (if you have multiple nodes this step only needs to be run once on any node machine). Obtain the Console-V2-Node-Backup-Enterprise.exe tool (provided in the com.castsoftware.imaging.migrationtool extension). The tool will generate an output ZIP file containing:

all data from the v2 delivery/deploy/common-data folders
the v2 aip_node and aip_config schemas

Create a .bat file and use it to execute the backup tool (you can run the tool direct from the CMD/PowerShell window if you prefer). When using a batch file, CAST recommends setting the password for the database user defined by the option --user, otherwise you will be prompted to enter this during the migration. To set the password, use the following syntax on the first line of your batch file:

SET CSSPASSWORD=CastAIP

Define the required command line using the available parameters and options as shown below:

Command	Required?	Description
`-h`, `--help`	N/A	Show this help message and exit.
`--process`	❌	Determines the type of backup: use `all` unless directed to use a different option (`schemaonly`, `sharedfolderonly`) by CAST Support (default: `all`).
`--casthomedir "<path>"`	✅	CAST AIP Core 8.3 installation folder, e.g.: `%PROGRAMFILES%\CAST\8.3` (default: None)
`--nodedatadir "<path>"`	✅	Available in ≥ 1.0.2-funcrel CAST Console AIP Node v2 data folder containing the `application-default.yml` file, e.g.: `C:\ProgramData\CAST\AIP-Node` (default: None).
`--outputdir "<path>"`	✅	Location on disk where the output ZIP file will be stored, e.g. `C:\temp\outputdir`. This folder MUST exist on disk before running the action. Not required when running `--reportonly` (default: None).
`--zipfilename "<name>"`	✅	Name of the output ZIP file (without the `.zip` extension). Not required when running `--reportonly` (default: None).
`--log "<path>\|<file>"`	✅	Either: a path such as `C:\temp\log` where a log file called `backup_v2.log` will be automatically created (this folder MUST exist on disk before running the action) or a file name such as `log.log` which will be stored in the same folder as the batch script running the action, or alongside the `Console-V2-Node-Backup-Enterprise.exe` if running from a CMD window (default: None)
`--host "<hostname>"`	❌	Hostname/IP address of the database instance where the v2 `aip_node` and `aip_config` schemas are stored (default: `localhost`).
`--user <user>`	❌	Username used to connect to database instance defined by `--host` (default: `operator`).
`--port <port>`	❌	Port for database instance defined by `--host` (default: `2284`).
`--database <database>`	❌	Name of the database in which the v2 `aip_node` and `aip_config` schemas are stored on the database instance (default: `postgres`)
`--nodeschema <schema_name>`	❌	Available in ≥ 1.0.2-funcrel Name of the CAST Console AIP Node v2 specific schema (default: `aip_node`).
`--configschema <schema_name>`	❌	Available in ≥ 1.0.2-funcrel Name of the CAST Console v2 configuration storage schema (default: `aip_config`).
`--workingdir "<path>"`	❌	Temporary processing location on disk which MUST exist before using the tool e.g. `C:\temp\workingdir`. If not specified, this path is calculated automatically based on the `CAST_CURRENT_USER_TEMP_PATH` value defined in the `CastGlobalSettings.ini` file (part of CAST AIP Core 8.3) (default: None).
`--psqldir "<path>"`	❌	`psql.exe` file location. By default `psql.exe` provided in CAST AIP Core 8.3 (defined by the `--casthomedir` option) is used (default: None).
`--reportonly`	❌	Available in ≥ 1.0.2-funcrel If set, runs only the initial checks defined by the tool and does not perform any backup actions (default: False).
`--validationreport "<path>"`	❌	Available in ≥ 1.0.2-funcrel A path to a `.txt/.csv file` which will contain an application compatibility report. This report is always generated, however when the option is not used, the report is output in the log rather than to file (default: None). This report is the same report as described in Compatibility Inspector.
`--force`	❌	Available in ≥ 1.0.2-funcrel If set, the script will continue the backup even if critical errors are found (default: False).

Example with absolute minimum command line options, which assumes that the database is running locally and with default port/login credentials:

SET CSSPASSWORD=CastAIP
Console-V2-Node-Backup-Enterprise.exe  --casthomedir "%PROGRAMFILES%\CAST\8.3" --nodedatadir "C:\ProgramData\CAST\AIP-Node" --outputdir "C:\temp\v3_migration\output" --zipfilename "migration_backup" --log "migration_backup.log"

Execute the batch file with elevated permissions (right click, Run as administrator). On completion, check the log file. If the process is successful, the last line of the log will show “Done”.

Finally, locate the output ZIP generated by the tool and transfer it to a machine hosting the v3 analysis-node component (i.e. a v3 node machine). If you have multiple v3 nodes you can copy the output ZIP to any of them.