Server Upgrade Best Practices
Although upgrading from one version of Alteryx Server to another is a straightforward process, there are several considerations and preparation steps that can help ensure a smooth upgrade. This page will provide a topical overview of the process, including links to useful documentation, and a step-by-step approach to consider when planning your upgrade.
Not every step or recommendation in this document is applicable to every environment or installation. Your plan might differ.
In general, the upgrade process should consist of the following high-level steps:
The following sections describe these steps and add narrative to help plan your work. Links to detailed instructions, where they exist, will be shown inline, and an aggregated list of all the links provided in this document can be found in the Guides and Help Articles section.
Find a checklist of these steps in the Server Upgrade Checklist.
Alteryx and its partners are available to assist in planning and executing an upgrade. Speak to your Account Executive if you need assistance with this process.
New Terminology
With the release of Server 2022.3, the term Gallery has been deprecated in favor of Server UI. Although the legacy term still exists in the software and documentation at the time of this writing, this document uses Server UI to refer to the applicable services, nodes, configurations, and others.
Section 1. Document Your Environment
Capture Your Architecture and Configuration
It is necessary to have complete understanding (and documentation) of your environment. At a minimum, you need to know:
How many servers are installed, and what are their functions?
How many each of Controllers, Server UI instances, Workers, MongoDB Servers do you have in each of your environments (Dev/QC/Production)?
Do you run a High Availability (HA) Environment?
Is there an architectural diagram which visualizes the environment? If not, this is a good opportunity to create one.
What software version of Alteryx Server is running in your environment?
What additional software has been installed?
Custom R libraries
Custom Python libraries
Third-party utilities
Connectors
Not every connector needs to be upgraded, and some might not have an upgrade available.
Data packs: Location Insights, Business Insights, Intelligence Suite, and so on.
Best practice is to install matching versions of these add-ons during the upgrade, if available.
Custom tools designed by your users or downloaded from Community, other purchased or free third-party tools and connectors. Make a list of these, along with versions.
The configuration options which have been set via the Alteryx System Settings configuration tool, including but not limited to:
Workspaces
Logging Directories
Scheduler and Engine enablement settings
Persistence settings, including:
Database type
Data folder
Retention options
Server UI settings (URLs and security)
Authentication methods and IDP information
SMTP
Run-as User
Note
These configuration options (such as Scheduler, Engine, Persistence, Server UI, SMTP settings, Run-as User, and more) are captured in C:\ProgramData\Alteryx\RuntimeSettings.xml, so an admin doesn’t need to separately record settings. A copy of RuntimeSettings.xml provides all of these in a plain text XML file.
Service Log-On User
Physical and virtual server specifications
Cores and memory
OS version
For more information, go to Server System Requirements.
MongoDB and Python versions
User-managed MongoDB: User-managed MongoDB version is independent of a Server upgrade. You might need to separately upgrade your User-managed MongoDB in parallel to a Server upgrade. In the case of the user-managed instance, Alteryx doesn't provide support. For more information, go to Version Support Policy .
Embedded MongoDB: Embedded Mongo and Python versions follow from the Server version and don’t need to be separately noted. For more information about embedded MongoDB versions, go to MongoDB Schema Reference or Version Support Policy.
Note
If you are using the Python tool, please check the Server Upgrade Python Tool Environment Checklist before upgrade.
Note
Your list of scheduled jobs, collections, workflows, and memberships is part of the MongoDB and is not lost during the upgrade.
We have prepared a Configuration and Architecture Checklist to make this step easier for you. Completing this checklist will give you an overview of your infrastructure and configuration.
Identify Business Critical Workflows
An important part of planning your upgrade is to identify business critical workflows that you want to protect and test as part of the upgrade process. These are generally workflows that are run on a schedule, act as dependencies to downstream work (inside or outside of Alteryx), and/or provide critical data/output to key stakeholders in the company. Essentially, you want to identify any workflow which, if unavailable for any significant amount of time, will have a deleterious effect on your business.
Identifying critical workflows can help you choose your target version. If the critical workflow contains tools or connectors that are not compatible with a particular version, you’ll want to take that into consideration when selecting your target version (see Section 3 below for the Server Upgrade Version-to-Version Guide). These workflows can also be modified for post-upgrade testing (below) and included in your QA plan.
Create Test Versions of Business-Critical Workflows
When you test critical flows during your post-upgrade QC, you’ll need to disable or edit any outputs that write data to other production systems, or produce outputs that will reside in the production environment.
A common methodology here is to create dedicated test versions of these flows which still access the target systems and directories, but will not overwrite data in production files and tables.
For data operations, change the outputs to write to dedicated test versions of tables.
For file operations, write files with a different file naming convention, or to a testing subfolder.
This allows you to do end-to-end testing that does not impact production. These test workflows should be used in production testing for the same reason.
Additional Considerations
Plan and schedule your upgrade activities to minimize disruption to your organization’s ongoing operations. Schedule the upgrade window outside of normal business hours (if possible), and during periods of "lighter" utilization. For example, do not schedule during fiscal year-end close, quarter-end processing, monthly audits, and so on.
Some clients use an upgrade window to revisit Operating System (OS) versions on their Alteryx machines. Please work with your IT Department if this is something you wish to do and review the System Requirements. Be sure to document in your upgrade plan whether you are upgrading the OS at the same time. If problems occur after the Alteryx upgrade, support engineers will be made aware of them.
Section 2. Perform a Server Health Check (Optional)
An Alteryx Server Health Check is a valuable resource for understanding usage patterns of an Alteryx Server environment. It analyzes historical usage patterns to determine how busy the Server environment is, what kind of optimization activities might be needed, and whether the environment is sized appropriately.
If you’d like to learn more, contact your Alteryx Account Executive.
Section 3. Select a Target Version or Versions
Select the target version of the Server software. Depending on your internal upgrade cadence, you might be one to several versions behind the current software release. There are considerations that apply depending on the number of versions between your current version and your target. Most clients do not upgrade each time a new version is released (there can be multiple releases in any given year), nor do they always run the current release; many clients opt for current-release-minus-1.
Note
All major releases are supported for 24 months. If your organization has adopted infrequent updates, this should be critical to your decision.
Review the Release Notes
The first step in the selection process is to read the Release Notes. These detail new features and programming changes in the potential target versions, and detail bug fixes and known issues.
Understand the Upgrade Path - Where You Are Now to Where You Want to Go
Some releases have additional considerations if coming from certain prior versions, and some versions are not appropriate for all customers. For example, you might be required to upgrade your MongoDB in order to traverse between versions, or in the case of version 2022.3, you will need to upgrade Server and Designer together because of data encryption enhancements in the software that make that version of Server incompatible with prior versions.
The Alteryx Help & Support site has a Server Upgrade Version-to-Version Guide, which highlights tasks and considerations you need to be aware of when upgrading through versions of Alteryx Server. The guide is especially helpful if you are upgrading through multiple versions at once, such as migrating from 2019.1 to 2022.1. To ensure a smooth upgrade, you might need to take some incremental steps.
Select Your Version
Now that you have educated yourself on the various available versions and the special considerations that line your upgrade path, you are ready to select your target version. From here, proceed to the Downloads site.
Section 4. Download the Software
Visit the Alteryx Licensing portal. You need an account to visit the site. Once there, you’ll find all the downloads available to you, including but not limited to:
Alteryx Server (current and previous versions)
Alteryx Designer
Alteryx Intelligence Suite and Insights Data
Alteryx supported Database Drivers
Download all the software you need and continue to the next step in the process. For help downloading, visit the Download and Install a Product help page.
Version Parity
In general, it is best practice to keep Server and Designer on the same version. So, downloading the matching Designer installer at this time makes the most sense. However, since upgrading Designer across a large user base requires additional planning and resources, you might not wish to complete the upgrade at the same time as the Server upgrade.
Server is generally backwards compatible with older versions of Designer, with the caveat that new features supported on the target version of Server won’t be available in older versions of Designer.
In the case of Server and Designer 2022.3, this backward compatibility does not exist due to data encryption enhancements across the platform. If you are planning to upgrade to or beyond this version, Designer must be updated at the same time. There are special instructions found on the Migration Prep Tool help page for preparing an upgrade to this version. If you are trying to download an older version no longer available on the Downloads page, please contact Fulfillment.
Section 5. Perform a Sandbox/Dev Server Upgrade and Test the Results
Testing the upgrade in a non-production environment and documenting your process steps prior to upgrading your production Server is the best way to ensure the process will run smoothly in your production environment, and that your business-critical workflows and third-party tools continue to run as expected. In the event they do not, it provides an opportunity to explore and remediate these issues and add these remediation steps to your production upgrade plan. The steps you follow in this test upgrade, plus any additional remediation steps you add in the QC phase, will become your upgrade “script” for production.
Ideally, start with the same-version Sandbox/Dev/Test Server and upgrade it. See the Alteryx Server Sandbox Environment Community article for more information on Sandbox environments.
If you have a multi-node environment, testing is still effective on a single machine that runs Controller + Server UI + Worker. Similarly, if you have a User-Managed MongoDB, restoring a database backup to the test machine's embedded MongoDB 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. Instructions can be found on the Install Two Versions of Designer on the Same Machine help page.
1. Perform a Backup
Perform a backup for:
2. Complete Pre-Upgrade Checks
You can avoid many Server upgrade problems by performing the pre-upgrade checks/workflow found in the Alteryx Server: Pre-Upgrade Checks Community article. This procedure addresses the most common issues a client will face performing an upgrade and lists the recommended solutions/steps for each.
It’s important to run the pre-upgrade checks in each of your environments before performing the upgrade. For example, you are testing on a development machine, then you’ll want to rerun the checks on your prod environment and take the indicated steps before completing that upgrade.
Disable Scheduler on Worker Nodes During Upgrades
By default, schedules that should have run while the Server was being upgraded will pick up as soon as the Server and nodes restart. Keep this in mind when running the test upgrade on your Sandbox, as you likely don’t want to have workflows kick off and impact your production systems.
We recommend to disable all schedules prior to upgrade and determine what should run on an individual basis.
If you do not want schedules to run when the Service starts:
Run Alteryx System Settings on each Worker (and main Server node).
Deselect Worker > General > Run unassigned jobs.
Give the Worker a unique Job tag (for instance “UPGRADETESTING”).
Alternatively, contact Customer Support for assistance in deleting all schedules.
3. Perform the Upgrade
Performing the upgrade is a straightforward process if you are upgrading in place. There are different steps if you are performing a fresh installation of the new version on a target machine, which include the application of licenses which is not part of the upgrade path; existing active licenses continue to work on upgraded machines without intervention. The general upgrade steps are shown on the Install or Upgrade Server.
The different instructions for new installations and upgrades-in-place are detailed, and the document includes links to associated help files/articles on licensing, system requirements, preparatory checklists, MongoDB upgrades, and more. Many of these are included in the Guides and Help Articles section at the end of this document.
Please note that Predictive Tools should be upgraded with the main installation. If you had a Service Log-On User set, you need to set it again after the upgrade; upgrades remove and reinstall the Alteryx Service.
Upgrading a Multi-Node Environment
In multi-node environments, all nodes should be upgraded to the same version and nodes must be shut down in the order shown in the Shutdown section of the document in the How to Restart the Services in a Multi-Node Alteryx Server Community article.
After you upgrade all nodes, follow the proper restart order listed in the Startup section of the same document.
Once everything is up and running, upgrade any connectors, data packs, drivers, add-ons (such as Intelligence Suite), and third-party tools that need to be.
4. Test/QC the Upgrade
Now that the Server software and any applicable connectors have been upgraded, it is time to start testing.
Alteryx Services
The first tests are basic and you can find them in the Test section of the Server Upgrade Checklist.
Can you:Is the Alteryx Service running?
Can you:
Access the Server URL?
Move around Admin pages and view Users, Collections, and so on?
Publish a workflow from Designer to the Server?
Run the workflow?
If your configuration allows, save and run a workflow specifying your credentials?
Configuration Options
Next, examine the configuration options in the Alteryx System Settings configuration tool to ensure that no settings have been lost. These settings were documented in the Document Your Environment section. If there are any changes you need to make, such as persistence settings, SMTP configurations, etc., now is a time to make them. Also, make a note of these changes to reuse them in your upgraded production environment.
Note
Some settings are actively changed across some of the upgrades. For example, 2022.1 set AMP on for the Server and changed the number of workflows allowed to run simultaneously.
Always check the Release Notes for more information.
Connectors and Drivers
The next step is to test your connectors and drivers to critical systems, such as SharePoint and O365 connectors, and ODBC/OleDB connectors to SQL Server, Snowflake, Databricks, and so on. Make sure you can connect, read, and write data.
Critical Workflows
Now, test your business-critical flows and flows that utilize the connectors also documented in the Document Your Environment section. This set of tests will use the test versions of the workflows created in the Create Test Versions of Business-Critical Workflows section of this guide. If you run unmodified productions versions of these flows, then your production destinations will be impacted as if these flows were running normally.
Scheduler and Server UI
Finally, if you are running Scheduler and Server UI, test these as well:
Can a workflow be scheduled, and does it run?
Do analytic apps run correctly?
Important
Make sure that any apps you publish and schedule/run in this environment are not production versions. If you run unmodified productions versions of these flows, then your production destinations will be impacted as if these flows were running normally.
5. Note Any Errors and Get Help
Catalog any problems your testing uncovers, such as:
Services that don’t start or report errors.
MongoDB Schema or crypto migrations that fail.
Workflows that don’t run or run with unexpected results or errors.
Connectors that don’t work.
Errors in MongoDB.
The Server Upgrade Checklist includes some common troubleshooting steps in the last section. Customer Support can assist if you experienced an error in the upgrade process and are unable to resolve it with the common troubleshooting steps shown in the guide. Your Account Executive can provide options if you would like assistance planning or executing an upgrade.
6. Perform a Rollback/Restore
If you were unable to resolve issues that were uncovered during the Test and QC phase, it’s time to do a rollback or restore. Prior to rolling back or restoring, you might wish to gather log files from the Server machines to provide to Customer Support or for internal review prior to the next upgrade attempt. If you have a snapshot/backup, you can revert to it now, and plan your next upgrade attempt. If a snapshot methodology was not possible, then you can follow the conventional rollback methodology shown in the How To: Downgrade Alteryx Server Community article.
Section 6. Schedule the Production Upgrade
Once you have successfully tested the upgrade in your non-production environment, and have your documented upgrade process, it is time to plan your production environment upgrade.
Note
Your production upgrade should follow the “script” you created in your test environment, with changes specific to any architectural differences between the environments. For example, if your tested environment was a single node architecture, but your production environment has separate nodes for Workers and Server UI, then the production environment will have additional installation steps. Be aware of this as you plan.
Pro tip: Use Server Notifications via Alteryx Server UI as an additional communication channel to inform users about pending upgrades. You can also post upgrade information in your internal Alteryx community (for example, SharePoint, Confluence, Yammer, Teams, and so on).
You’ll need to schedule an appropriate amount of downtime and inform the users that workflows on Server will not be running during the upgrade. For business-critical flows, users can run them in your newly upgraded test environment, run them locally, or simply plan for the outage and inform affected downstream audiences about the delay.
If you are planning to upgrade Designer as well, whether via packaging/automation methods or manual installation process, plan for the extra time and resources needed to complete the installations, and be sure to inform your user base as well. Remember that Server is backward-compatible with Designer, up until version 2022.3, but newer versions of Designer do not work with older versions of Server. So, Server upgrades must always precede Designer upgrades.
Important
Remember to plan your upgrade at a time that minimizes disruptions to your business. Refer to Additional Considerations for more detail and recommendations.
Section 7. Perform the Production Upgrade
Upgrade Server
The high level steps in this section are a mirror to steps 1-6 in Section 5. Refer to the appropriate section for additional details and help links.
Back up the environment.
Perform the upgrade, including connectors, data packs, add-ons, third-party tools, etc.
Check that scheduled jobs, collections, memberships, and published workflows still exist and work as expected (where testable).
Perform a rollback/restore if necessary.
Restore from backups or follow the process in the How to: Downgrade Alteryx Server Community article.
Upgrade Designer (optional)
Once your production environment is up and running, you can upgrade your Designer installs if they are part of your plan. Remember that Designer cannot be a greater version than what has been installed on Server, and this upgrade affects users’ machines directly. Steps for upgrading Designer can be found in Upgrade Designer.
Designer and Server Compatibility
Designer version needs to be equal to or older than the Server version it connects to. The exception is Server 2022.3 (or later) which requires at least Designer 2022.3 due to changes in encryption.
Designer version can NOT be newer than the Server it connects to.
Only the version (Year.Release) needs to match, not the specific patch.
Similar to a Server upgrade, upgraded Designer versions should be tested to ensure that workflows continue to run, and that connections to Server can still be made. As with the best practices for Server upgrades, plan to test your Designer upgrade on a small subset of user machines.
Guides and Help Articles
On this list you can find links to all resources mentioned in this document, as well as additional resources which can be helpful in the Server upgrade process.