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.
|
Advanced
|
Advanced
|
|
|
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 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:
|
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:
|
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 UI … Controller … [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). |
Backup RuntimeSettings.xml, Controller Token, and Service Log On user. |
|
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 UI … Controller … [user-managed Mongo] |
Upgrade |
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:
|
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 Look for a line near the end with a number matching the expected schema See TROUBLESHOOT section if the migration didn't complete to the expected level. |
Basic Server Testing | Is the AlteryxService running? Can you:
|
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: |
Connector Tool Errors | |
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:
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:
|