Migration Prep Tool
The Migration Prep Tool for Server is a utility that allows for a pre-migration of a database of workflows and apps to be more quickly migrated to the new AES256 standard.
This Migration Prep Tool is optional and a separate command line utility. You only need to run it once before you upgrade from Server 2022.1 (or earlier versions) to 2022.3.x or newer.
Important
If you are upgrading from 2022.1 or prior, please run the Migration Prep Tool prior to upgrading to 2022.3+.
If you are upgrading from 2022.3+, your database has already been Crypto Migrated and you do not need to run the Migration Prep Tool.
Note
Why Did We Create This Tool?
Server is updating its cryptography to use AES256 for data at rest. All existing cryptographically stored data needs to migrate from its current encryption method to the new one. Some of this data can be migrated in advance of the upgrade to 2022.3 while your Server is in production.
The most time-consuming data that needs to migrate are the apps and workflows stored in Server. This data can be migrated in advance to save time when performing the upgrade to Server 2022.3.
Alteryx created the Migration Prep Tool to assist you in migrating this data before the upgrade.
When to Use the Migration Prep Tool
We recommend you run the Migration Prep Tool in these cases:
If the Server installation you are upgrading is a production system or a development system that can't be down for more than a few hours, and
You have more than a few hundred workflows, and
You are running on MongoDB Atlas or user-managed MongoDB.
Even if these cases do not apply to you, it is best practice to run the Migration Prep Tool before attempting an upgrade to ensure success.
Further, you might also consider the size of db.AS_App_Chunks.dataSize() and AS_PackageDefinitions. We don’t have recommendations related to the database size for when you should run the Migration Prep Tool in prep mode.
If you only have a few workflows or you don’t mind if Server takes several hours to days to upgrade, you can skip using the Migration Prep Tool and run the standard Server installer to upgrade to 2022.3. The downtime will be longer than usual since the crypto migration will be part of the upgrade.
Note
If you choose to not run the Migration Prep Tool before the upgrade, the tool will be installed and run as part of the 2024.2 upgrade installation.
Pre-Flight Check
To evaluate any anticipated issues you might need to address prior to upgrading to 2022.3 or later, run the pre-flight check as part of the Migration Prep Tool.
Important
You can only perform a pre-flight check on Server instances using a 64-character Controller Token.
If your Server is on version 2021.3 or earlier, you need to first upgrade to version 2022.1 before proceeding with the next steps.
Check the length of your Controller Token in Alteryx System Settings > Controller > General > Token > View.
If your token is 40 characters long, select Regenerate to create a new token. Then select OK to restart the AlteryxService and create the new token.
During the pre-migration or full migration process, you will be able to see error logs that allow you to resolve the issues yourselves. This enables you to take the recommended action to ensure the full migration is completed successfully despite any errors.
We have added 3 new run options when running the Migration Prep Tool:
Default: Run the pre-migration and pre-migration check simultaneously (-p)
Run just the pre-migration (apps) (--appsonly)
Run just the credential validation step (--credonly)
While running the Migration Prep Tool, you must provide the controller token (-t) and hostname/IP Address (-i) of the controller. This also means you can now run the Migration Prep Tool on a multi-node setup by providing the controller's hostname/IP address and controller token.
Please note that 2 instances of the Migration Prep Tool tool cannot run simultaneously for the same controller.