Step 2 - Migrate your data

Overview

This step involves migrating the following data to your CAST Imaging v3 installation, i.e.:

• data backed up in Step 1 - Backup your data from CAST Imaging Viewer v2 and CAST Console v2 enterprise
• data in-situ from CAST Console v2 standalone

All migration actions are performed on machines where CAST Imaging v3 components are installed.

Requirements

See Requirements.

You should also ensure that you have completed Step 1 - Backup your data.

Process

Step 1 - Download and unzip the migration tool

Starting release 1.2.0-funcrel, the migration tool extension has two different variants:

• one for migrating to CAST Imaging v3 installed on Microsoft Windows
• one for migrating to a Linux based CAST Imaging v3 installation

Ensure you choose the correct variant when downloading:

Download and unzip the com.castsoftware.imaging.migrationtool  extension on the machine(s) where the migration will be run:

• the machine where the CAST Imaging v3 imaging-viewer component is installed
• for a v2 CAST Console enterprise/distributed migration, a machine where the CAST Imaging v3 analysis-node component is installed (any node can be used)
• for a v2 CAST Console standalone migration, the machine where all CAST Imaging v3 components are installed
• for a migration to Linux/Kubernetes, the machine on which the migration tool will be run must have kubectl  installed and configured to connect to the cluster. Ensure that kubectl is also configured on the PATH by running kubectl version in terminal

Use one of the following download methods based on your target CAST Imaging v3 platform:

• Microsoft Windows: download from the CAST Extend portal .
• Linux: run the following curl command:

$ curl -# -O -J "https://extend.castsoftware.com/api/package/download/com.castsoftware.imaging.migrationtool/<version>?platform=linux_x64" -H "x-nuget-apikey: <api-key>" -H "accept: application/octet-stream"

Where:

• <version>: use latest for the most recent release, or specify a version such as 1.2.0-funcrel.
• <api-key>: your CAST Extend API key — obtain from your CAST Extend profile settings .
• -#: shows a download progress bar.
• -O (--remote-name): saves the file to the current folder using the server-provided filename.
• -J (--remote-header-name): uses the filename from the server’s Content-Disposition header instead of the URL.
• -H (--header): passes an additional HTTP header with the request.

Step 2 - Set-up the migration configuration file

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

• For CAST Imaging V3 installed on Microsoft Windows: migration.conf
• For CAST Imaging V3 installed on Linux (Docker/Podman/Kubernetes): migration_linux.conf

The configuration file contains various distinct sections, described below:

1. General options
2. Neo4j options
3. Console options
4. Container options

General options

Option	Description	migration.conf	migration_linux.conf
option=	Choose one of the following - all options should ONLY be run once: - All: migrate both CAST Imaging Viewer v2 and Console v2, i.e. for a standalone/single machine deployment of CAST Imaging v3 where imaging-viewer, imaging-services and analysis-node components are all installed on the SAME machine. - Neo4j: migrate only CAST Imaging Viewer v2, must be run on the machine where the CAST Imaging v3 imaging-viewer component is installed. This option must be run BEFORE the Console option. - Console: migrate only CAST Console v2, must be run on a machine where a CAST Imaging v3 analysis-node component is installed. This option must be run AFTER the Neo4j option. When using ≥ 1.2.0-funcrel, you must also set noviewer=Yes (you may need to uncomment this option).	✅	✅
log=	A local folder for storing the migration log files. For Microsoft Windows use a standard Microsoft Windows path with back slashes, e.g.: C:\temp\logs. For Linux, use forward slashes, e.g.: /tmp/migration/logs. The tool will attempt to create this folder if it cannot be found.	✅	✅
apikey=	A CAST Imaging v3 API key - you can obtain this by clicking the user icon in the top right corner of the screen and selecting Profile:	✅	✅
GATEWAY_HOMEPAGE_URL=	The “public access URL” of your CAST Imaging v3 installation (defined during the installation), relative to the machine on which you are running the migration action. For example if all your v2 and v3 components are installed on one machine, you can leave this set to the default http://localhost:8090. Otherwise, set this URL to match the location of the imaging-services component in your network.	✅	✅
noviewer=	Available in ≥ 1.2.0-funcrel Commented by default. Uncomment and set to Yes when using option=Console (i.e. if you do not use CAST Imaging Viewer v2, or when CAST Imaging Viewer V2 is installed on a separate machine.) By default the tool performs checks on the CAST Imaging Viewer Service before proceeding - this option bypasses those checks. Do not use with option=All or option=Neo4j.	✅	✅
install_path=	Available in ≥ 1.2.0-funcrel Path to your CAST Imaging V3 installation for Docker/Podman if using a non standard path. Set by default to /opt/cast.	❌	✅

Neo4j options

These options define the CAST Imaging Viewer v2 migration:

Console options

These options define the CAST Console v2 migration:

Container options

These options define options used when migrating specifically to a containerized platform on Linux (Docker/Podman/Kubernetes):

Step 3 - Run the migration

To run the migration:

• Connect to your chosen CAST Imaging v3 machine, depending on the migration options you have configured in the migration.conf / migration_linux.conf file.
• Depending on your target infrastructure:
  • On Microsoft Windows, 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.
  • On Linux for Docker/Podman/Kubernetes, navigate to the root of the unzipped migration tool extension in terminal.
• Execute the following command to set the password for the database user defined by the option css_user= in the migration.conf / migration_linux.conf file (otherwise you will be prompted to enter this during the migration):

Microsoft Windows
SET CSSPASSWORD=CastAIP

Linux
$ export CSSPASSWORD=CastAIP

• Now execute the script file provided at the root of the unzipped migration tool extension with the option reportonly:

Microsoft Windows
Cast_Imaging_V3_Migration.bat reportonly

Linux
$ ./Cast_Imaging_V3_Migration.sh reportonly

• This will run the migration in test mode only: no migration 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 migration.conf / migration_linux.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” migration by running:

Microsoft Windows
Cast_Imaging_V3_Migration.bat

Linux
$ ./Cast_Imaging_V3_Migration.sh

Step 4 - Check the migration log

On completion, check the log file (defined by the option log= in the migration.conf / migration_linux.conf file).

Step 5 - Check CAST Imaging v3

Connect to CAST Imaging v3 and login with a user that has the default Admin profile or a custom profile with the Administrator role - see User Permissions. Check that all your applications are visible in CAST Imaging v3.

Successfully migrated applications will show the following:

The status Migration in process in the Application landing page - you can still view their results if required by clicking the status, but you will be informed that to finalize the migration, you will need to complete additional steps - see What’s next?:

• For an application that has “imaging-viewer” results (i.e. data in the Neo4j database):

• For an application that has no “imaging-viewer” results:

In addition, a banner in the Application analysis configuration - Overview panel informing you about the need to perform Step 3 - Perform the application schema update and re-analysis in CAST Imaging v3 - note that some features in this panel will be disabled until this step is fully completed.

Step 6 - Check the migration report

As part of the migration process, a status report will be generated and stored on disk in text format: this report will contain key information regarding the migration status, details about each migrated application, the technologies they contain, the extensions that require an update, and advice about what to do next. This report must be consulted BEFORE you proceed with Step 3 - Application update and re-analysis as it will tell you whether you should complete this step or not.

The migration report is located at the root of the unzipped migration tool extension (along side the Cast_Imaging_V3_Migration.bat / Cast_Imaging_V3_Migration.sh file), called MigrationReport.csv. The report contains the following information:

Example report for hypothetical applications that fall into each STATUS category described previously:

What’s next?

You must now perform the application update and re-scan as described in Step 3 - Perform the application update and re-scan in CAST Imaging v3.