Run the Migration Prep Tool

Version:
2022.3
Last modified: May 16, 2023

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. 

# Step
1.1

Download the installer at https://downloads.alteryx.com and run it. 

Run the installer of the Migration Prep Tool.
1.2

Accept the EULA.

Accept the EULA.
1.3

Choose the installation path or accept the default path. 

Choose the installation path or accept the default path. 
1.4

Follow the prompts to complete the installation.

Follow the prompts to complete the installation.

Follow the prompts to complete the installation.

Step 2: Start the Migration Prep Tool

Follow these steps to start the Migration Prep Tool. 

# Step
2.1

Open a Command Prompt or PowerShell. 
2.2

Navigate to the chosen installation path (Default: C:\Program Files\Alteryx Migration Tool\). 
2.3

Execute one of these 3 commands to run the Migration Prep Tool. Note: If you use PowerShell, add .\ to the start of each command.
You can run this operation on any host that has access to the MongoDB server. You can safely run it multiple times without downtime.

#Example for use with the embedded MongoDB or a single user-managed MongoDB server:
AlteryxServiceMigrator22_2.exe -p -c "mongodb://{user}:{password}@{host.domain.tld}:{port}/AlteryxService?authSource={authenticationDB}"

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:
AlteryxServiceMigrator22_2.exe -p -c "mongodb://{user}:{password}@{host1.domain.tld}:{port},{host2.domain.tld}:{port},{host3.domain.tld}:{port}/AlteryxService?authSource={authenticationDB}"

#Example for use with MongoDB Atlas:
AlteryxServiceMigrator22_2.exe -p -c "mongodb+srv://{user}:{password}@{atlasCluster.cloudProvider.mongodb.net}/AlteryxService?retryWrites=true&w=majority"

  • Replace these variables in the connection string with the values appropriate for your environment. These are the same credentials used to configure your Server database and can be found in Alteryx System Settings:

    • {authenticationDB} = the database that will authenticate the specified user credential.

      • If your Server is configured to use the embedded MongoDB, you need to use the non-admin MongoDB password. In the connection string, your authSource should be ‘AlteryxService’. 

      • If you are using a user-managed MongoDB, contact your MongoDB administrator to confirm the user credentials and authSource. 

    • {port} = the service port MongoDB uses to provide access to the database.

    • {host.domain.tld} = the fully qualified domain name of your MongoDB server.

    • {password} = credential for the user.

    • {user} = username to access the database.

    • {atlasCluster.cloudProvider.mongodb.net} = the MongoDB Atlas cluster address.

  • Command parameters:

    • -h [ --help ] display help info

    • -q [ --quiet ] output log messages to the command line (progress messages ignore this flag)

    • -s [ --severity ] arg (=7) console logging severity level (migration progress reports are sent at level 5)

    • -p [ --perform ] perform migration

    • -u [ --forcenoprogressupdates ] disable progress update messages from being written to the console (they are still written to the log file)

    • -c [ --connection ] arg connection string (AlteryxService database must be specified)

    • -l [ --loggingpath ] arg (=C:\ProgramData\Alteryx) logging file path, must contain a %N for log rotation purposes

    • --loggingmaxfilesize arg (=64) maximum size in MB for a log file before it gets rotated

    • -r [ --runtimesettings ] arg runtime settings file path

    • -d [ --stagingdirectory ] arg directory where decrypted workflows will be temporarily stored before getting reencrypted
2.4

When the migration starts, it will prompt you to confirm you have made a backup of the database and your runtime settings file:

When the migration starts it will it will prompt you to confirm you have made a backup of the database and your runtime settings file.

2.5

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.

Once you confirm the backups, the utility will check current space usage .
2.6

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.

After confirming sufficient free space is available, the utility will begin migrating the the workflow data in preparation for the upgrade to 2022.3.

Troubleshooting 

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:

  1. Capture a screenshot of the command prompt.
  2. Obscure or remove any sensitive data. 
  3. Capture the log (see validation steps for location and naming). 
  4. Run the migration again.
  5. 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.

# Step
3.1

Download the 2022.3 installer and run it.

Run the installer.
3.2

Accept the license agreement.

Accept the license agreement.
3.3

Choose your installation path or accept the default path.

Choose your installation path or accept the default.
3.4

Start the installation. 

Start the installation.
3.5

Allow the installation to complete. 

Allow the installation to complete.

3.6

Upon completion of the installation, choose the Configure Server Now option. 

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. 

Troubleshooting

If the service shuts down after a period of time, check these logs for migration errors:

  • LastStartupError.txt 
  • AlteryxServiceMigrator_#.log

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: 

  1. 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). 
  2. 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

  1. Navigate to C:\ProgramData\Alteryx\Service\.
  2. Open AlteryxServiceMigrator_#.log.
  3. 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)

  1. Log into Server via the web URI.
  2. 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. 
Was This Page Helpful?

Running into problems or issues with your Alteryx product? Visit the Alteryx Community or contact support. Can't submit this form? Email us.