Skip to main content

Server Upgrade Checklist

Your Server configuration is unique and upgrading it is a project that requires planning and preparatory work to be successful. This checklist ensures you consider all tasks that might be needed for your upgrade and directs you to Help and Knowledge Base articles for detailed step-by-step procedures.

If you would like help preparing or executing your upgrade, please speak with your Account Executive for options.

PLAN

PREP WORK

UPGRADE

TEST

TROUBLESHOOT

  • Determine target version

  • Identify critical workflows for validation

  • Pre-upgrade check workflow (critical)

  • Backup MongoDB

  • Backup key files

Advanced

  • Evaluate Connectors

  • Save Python and R environments

  • Upgrade in Test environment

  • Upgrade live environment

Advanced

  • Upgrade Connectors

  • Restore Python and R environments

  • Review upgrade logs

  • Access Server UI pages

  • Publish from Designer

  • Validate critical workflows

  • Common issues and resolutions

  • Rollback

  • Customer Support

Server Upgrade Overview

Testing your upgrade process prior to upgrading your Production server is the best way to ensure your Server upgrade process will run smoothly in your production environment.

Ideally, start with a same-version Sandbox/Dev/Test Server and upgrade it, see Alteryx Server Sandbox Environment. If you have a multinode environment, testing is still effective on a single machine that runs Controller + Server UI + Worker. Similarly, if you have User-Managed MongoDB, restoring a database backup to the test machine's embedded Mongo can help validate the upgrade. Contact your Account Executive for information on a Sandbox license.

At a bare minimum, you should install the target version of Designer on a user's machine to test critical workflows in the new version. For more information, go to Install Two Versions of Designer on the Same Machine.

Ideal process:

Server_upgrade_checklist_process.png

Server Upgrade Process

Plan

Questions/Steps

Consideration/Links

Choose your target version.

Version-to-Version Server Upgrade Guide - specific items you should be aware of when upgrading.

Know your current version for rollback.

You can find your current version:

  • Private Studio in a browser > select your name in upper right > My Profile > Version.

  • Run Designer on Server, Help > About.

Confirm sufficient free space.

Importante

Upgrade will fail for lack of space.

If you use Embedded MongoDB and the Version-to-Version Server Upgrade Guide indicates the MongoDB Version will upgrade, confirm sufficient free space:

Identify validation workflows.

Identify workflows to validate the upgrade. These are:

  • Critical workflows that must run on the Server

  • Workflows that:

    • Input/output to a network UNC location

    • Input/output to a database

    • Use Connector Tools

    • Use Location or Business Insights Datasets

    • Use Python Tool

    • Use R Tool

Plan how to manage scheduled workflow during your upgrade.

By default, schedules that should have run while the Server was being upgraded will pick up as soon as the Server and nodes restart. You can suspend all schedules and determine what should run on an individual basis (described in the UPGRADE section).

Advanced issues that might not apply to your upgrade:

Do workflows use Connector Tools?

Connectors are installed independently and must be compatible with your new Server version. You can determine the Connectors and versions installed by their folder names under %ProgramData%\Alteryx\Tools.

Review each Connector to ensure compatibility with your new Server version to determine Server+Connector version compatibility:

If the Python version is upgraded as part of your Server upgrade, all Python-based connectors must be reinstalled. The YXI file takes the current Python version into account during the installation process (so the same YXI file will perform a different installation when run in versions of Designer/Server that use a different Python version). View the Python versions used by Server versions in Alteryx Embedded Python.

Do workflows use the Python Tool?

Is your organization required to maintain vendor support from MongoDB?

Is your MongoDB User-Managed?

Are you changing MongoDB between Embedded and User-Managed?

Don't perform a Server Upgrade and MongoDB migration together, these are separate projects.

Are you moving from on-prem to cloud?

Don't perform a Server Upgrade and cloud migration together, these are separate projects.

Do you use the Connect product?

Upgrade Connect to the same version as Server. For more information, go to Connect and Loaders.

Prep Work

Questions/Steps

Considerations/Links

Run pre-upgrade checks.

Importante

Skipping this step is the cause of most server upgrade failures.

Run Crypto Migration Prep Tool if upgrading to or through 2022.3.

Stop Server and backup MongoDB and other critical information.

Stop Server.

Order: Workers (wait for jobs to finish) … Server UIController … [user-managed MongoDB]

Backup Mongo database.

Importante

A server snapshot is not sufficient as it can restore a corrupt MongoDB if the Service was running when the snapshot was taken.

Perform a MongoDB backup from the command line (adjust for your folder structure).

C:\Program Files\Alteryx\bin\AlteryxService.exe emongodump=C:\BKP_DIR

Backup RuntimeSettings.xml, Controller Token, and Service Log On user.

  1. Run Alteryx System Settings > Controller > General > Controller Token > View and copy the Token to a safe location.

  2. Make a backup copy of

    C:\ProgramData\Alteryx\RuntimeSettings.xml

  3. Note the Services App > AlteryxService > Properties > Log On settings.

Optionally backup other settings.

Optionally perform a snapshot backup.

Stop the AlteryxService prior to the snapshot. If rollback is needed, you can try using the snapshot, with the MongoDB backup above being your failsafe.

Upgrade

Questions/Steps

Considerations/Links

If moving to a new Server or testing the upgrade on a test Server:

Perform a Server Host Recovery to new or test Server

Test before upgrading.

Aviso

Don't skip this step.

Follow the TEST section below to ensure the migration was successful before upgrading to make troubleshooting easier.

If upgrading in-place (on the same machine):

Do you want to suspend Schedules after the upgrade?

If you do not want Schedules to run when the Service starts: Run Alteryx System Settings on each Worker, deselect Worker > General > Run unassigned jobs, and give the Worker a unique Job tag. Alternatively, contact Customer Support for assistance in deleting all schedules.

Stop Server

Order: Workers (wait for jobs to finish) … Server UIController … [user-managed Mongo]

Upgrade

  • Download new version from downloads.alteryx.com.

  • Right-click and run the installer As Administrator.

  • Choose the same installation path as your old version.

  • Choose Migrate Mongo Database if the option is presented.

Sugerencia

Save the installer in case you need to roll back to this version after a future upgrade.

Did you have a Service Log On User in the PREP WORK section?

Reset Service Log On User after upgrade:

Windows Services app > right-click AlteryxService > Properties > Log On

Sugerencia

In the future consider using the Alteryx System Settings > Worker > Run As user instead as it is not lost during an upgrade.

Perform version-specific tasks

Advanced issues that might not apply to your upgrade:

Do you have a multi-node environment?

All nodes must be upgraded to the same version.

Restart order: [user-managed Mongo] … Controller … Server UI Workers

Do workflows use Connector Tools?

If Connectors need to be upgraded to remain compatible with the new Server version, install upgraded versions of Connectors and delete incompatible Connector folders.

When a Connector version is removed from the Server, existing workflows using that version will stop running with the error message "Error: Unable to resolve plugin Python 'XXXXX\main.py' (Tool Id: X)".

Users need to:

  1. Install a version of the Connector that matches what's available on the Server.

  2. Delete the old version (simply delete the old version's folder under

    C:\Users\USER_NAME\AppData\Roaming\Alteryx\Tools

  3. Open the workflow, edit the Connector, and re-authenticate it.

    Alternatively: Delete the Connector and re-add it.

  4. Test the workflow is functioning with the new version (some versions change the Tool's UI).

  5. Republish the workflow to the Server.

  6. Verify the workflow runs on the Server as expected.

Test

Questions/Steps

Considerations/Links

If upgrading, review MongoDB Schema Migration File

Confirm the schema migrated to the version expected for your new Server version

%ProgramData%\Alteryx\Gallery\Logs\alteryx-migration.csv

Look for a line near the end with a number matching the expected schema

INFO,1,migrationLogger,MoveNext,Migration 31 Completed.,

See TROUBLESHOOT section if the migration didn't complete to the expected level.

Basic Server Testing

Is the AlteryxService running?

Can you:

  • Access the Server URL?

  • Move around Admin pages and view Users, Collections, etc.?

  • Publish a workflow from Designer to the Server?

  • Run the workflow?

  • If your configuration allows, save and run a workflow specifying your credentials.

Test validation workflows

Test the validation workflows identified in the PLAN section. Confirm these don't output data to production locations or databases if this would produce duplicate records or cause other data integrity issues for your organization.

Troubleshoot

Issues

Troubleshooting

Mongo Schema Migration didn't complete or has an error.

The most common reason for this is that the Pre-Upgrade Checks workflow wasn't run or the issues found weren't corrected.

UNC Network Locations Error in workflow accessing UNC location.

Ensure the Run As User or Service Log On User are properly set and have rights to access the network location.

ODBC / DSNs Error accessing a database using DSN.

Compare the ODBC driver versions and ODBC System DSNs from your old machine. Look for version or spelling differences. Download supported drivers.

In-DB Connection Error accessing an In-DB connection.

Copy file from original Server:

C:\ProgramData\Alteryx\Engine\SystemConnections.xml

Connector Tool Errors

See Connectors Troubleshooting.

Rollback

If you need to rollback, see Downgrade Alteryx Server.

Customer Support Assistance

Customer Support can assist if you experienced an error in the upgrade process and are unable to resolve it with the common troubleshooting articles above. Your Account Executive can provide options if you would like assistance planning or executing an upgrade.

Case Prioritization

Criteria 1:

  • Sev 1 - Production Server is completely down

  • Sev 2 - Sandbox/Dev Server is down or Production Server isn't fully functional

Criteria 2: Paid Support Tier

What to provide to Customer Support?

To ensure Customer Support can start troubleshooting immediately, please include in your support request:

  1. Is this your Dev/Sandbox or Production environment?

  2. Is the Server down completely?

  3. Version upgrading from and to.

  4. Is this a multi-node environment?

  5. Description and screenshot of the error you're receiving.

  6. The following files, adjusting the location based on your installation:

    Server UI Node

    C:\ProgramData\Alteryx\Gallery\Logs\alteryx-migration.csv

    C:\ProgramData\Alteryx\Gallery\Logs (past 48 hours)

    All Nodes

    C:\ProgramData\Alteryx\RuntimeSettings.xml

    C:\ProgramData\Alteryx\Service (past 48 hours)

  7. When upgrading to or through 2022.3, provide CryptoMigration logs (AlteryxServiceMigrator_#.log).