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 - 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.

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 migration: 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.

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.