Run the Migration Prep Tool
Before You Begin
The Migration Prep Tool creates a staged copy of the workflow data stored in your database. During this process, the Migration Prep Tool will give you an estimate of the space required to proceed. Do not proceed unless you have sufficient space available.
You must manually verify that you have sufficient space available to complete this process. The Migration Prep Tool cannot verify the space available.
Step 1: Install the Migration Prep Tool
Follow these steps to install the Migration Prep Tool.
Download the installer at https://downloads.alteryx.com and run it.
Accept the EULA.
Choose the installation path or accept the default path.
Follow the prompts to complete the installation.
Step 2: Start the Migration Prep Tool
Follow these steps to start the Migration Prep Tool.
Open a Command Prompt or PowerShell.
Navigate to the chosen installation path (Default: C:\Program Files\Alteryx Migration Tool\).
Execute one of these 3 commands to run the Migration Prep Tool. Note: If you use PowerShell, add
#Example for use with the embedded MongoDB or a single user-managed MongoDB server:
This might look like in the following example. Please note that 'NON_ADMIN_MONGO_PASSWORD' and 'localhost' should be changed based on your current setup.
AlteryxServiceMigrator22_2.exe -p -c "mongodb://user:NON_ADMIN_MONGO_PASSWORD@localhost:27018/AlteryxService?authSource=AlteryxService"
#Example for use with MongoDB replica sets:
#Example for use with MongoDB Atlas:
When the migration starts, it will prompt you to confirm you have made a backup of the database and your runtime settings file:
Once you confirm the backups, the utility checks the current space usage. It will give you an estimate of the additional space needed for the migration. You must check your system and continue only if you are sure that you have sufficient free space available to proceed.
After you have confirmed that there is sufficient space available, the utility begins migrating the workflow data. You will see console messages indicating the start time and completion time, along with progress messages.
If an error occurs during the migration, the error displays in the console and is also captured in the log file.
If you encounter an error, follow these steps:
- Capture a screenshot of the command prompt.
- Obscure or remove any sensitive data.
- Capture the log (see validation steps for location and naming).
- Run the migration again.
- If the migration is unsuccessful again, contact Support and include the screenshot and log file in your report.
Step 3: Upgrade to Server 2022.3
Before you upgrade, make a backup copy of your Mongo database and the RuntimeSettings.xml. The encryption performed during the maintenance window is not reversible. The backup protects your installation from data loss or additional downtime.
The migration progress is not visible during the 2022.3 upgrade.
For more information about the upgrade, go to Install or Upgrade Server.
Download the 2022.3 installer and run it.
Accept the license agreement.
Choose your installation path or accept the default path.
Start the installation.
Allow the installation to complete.
Upon completion of the installation, choose the Configure Server Now option.
After the installation of Server 2022.3 is complete, there might be a delay in starting the service.
|3.7||Alteryx System Settings opens. Navigate through System Settings to check that your settings are correct. Then select Finish and Done to start the service.|
|3.8||Once the service starts up, Server enters maintenance mode to migrate RuntimeSettings and the database values that could not be migrated beforehand. During the maintenance mode, your Server instance will be unavailable.|
|3.9||The Migration Prep tool does a final check for database changes since the last run. Then it performs the migration (including any newfound changes) and moves the staged migration into use.|
|3.10||This final migration might take several hours. The time depends on the size of your configuration and if the Migration Prep Tool was run before the upgrade. Once this process is complete, Server will exit the maintenance mode and enter a functional state.|
If the service shuts down after a period of time, check these logs for migration errors:
If migration errors were encountered, attempt to restart the AlteryxService. After attempting to restart the AlteryxService might resolve the issue. If the problem persists, collect the logs and reach out to customer support for assistance. Depending on the errors, attempting to restart the AlteryxService might resolve the issue as it will re-attempt any incomplete migration steps.
What could cause a migration to fail?
There are 2 failure cases:
- The record could not be decrypted. This implies a corrupted record that the user needs to remove from the table (after backing it up, if appropriate).
- The record could not be re-encrypted. The solution is the same as in the previous case.
Other failure cases are usually environmental issues. These get resolved by fixing the environmental issue and then running the utility again. Lost connection to MongoDB and insufficient disk space are some examples.
Step 4: Validate Migration Success
To validate that the Migration Prep Tool was completed successfully, follow any of the following options.
Validation via Log
- Navigate to C:\ProgramData\Alteryx\Service\.
- Open AlteryxServiceMigrator_#.log.
- Review the log for error or failure messages. Search for status 3 displayed as ';3;' in the log.
Validation Post Upgrade to 2022.3 (After Final Migration)
- Log into Server via the web URI.
- Verify the following:
- You can manually run workflows and apps.
- Schedules are active and running with their expected results.
- You can view, edit, create, and use workflow credentials.
- You can view, edit, create, and use Server data connections.
- Retrieve a workflow package from the API, import that package to Designer, and run the workflow in Designer.