Upgrade Your Alteryx Server
Before the upgrade
There are several things to consider prior to upgrading your Alteryx Server.
Have you checked your MongoDB for common issues?
There is a really great article in the Knowledge Base with an associated tool here that checks for common MongoDB issues and gives advice on how to fix them.
What version are you going from and to?
This is an important consideration for several reason. There have been upgrades to different components. The key component upgrades that affect the server upgrade are MongoDB, R and Python.
MongoDB
You need to check the version crosswalk to ensure that you can upgrade from your current version to the new version you want without having to do an intermediate upgrade to a different version.
If you can upgrade directly then you may be presented with the “Migrate Mongo Database” option if you are on a different version. This option must be used if presented before the Server can be restarted. If you have performed the checks above for common issues and corrected any that have occurred, then the upgrade should be a lot smoother.
R Tools
The version of the R Tools has been upgraded in recent versions of the Alteryx Platform and so you need to consider if you have published workflows that rely on them. If you do, you may need to re-publish them after the upgrade as the underlying folder changes with the upgrade. Also, if you have added additional R libraries then you will need to re-install them after the upgrade.
Python
The Python environment has also gone through an upgrade in recent versions of the Alteryx Platform and so you also need to consider if you have published workflows that rely on them. If you have installed additional packages installed, then you will need to re-install them after the upgrade.
Moving to 2022.3
Moving to 2022.3 updates the cryptography settings of Alteryx server for increased security. This means that all Workflows stored on the Server requiring migrating to the latest settings and there is a Migration Prep Tool (available to download from the Alteryx License Portal) to assist with this. It can be done prior to the upgrade and is recommended to be done if you have a lot of Workflows, otherwise the upgrade process could take a very long time. Please see this quote from Alteryx: -
“If you only have a few workflows or you don’t mind if Server takes several hours to days to upgrade, you can skip using the Migration Prep Tool and run the standard Server installer to upgrade to 2022.3. The downtime will be longer than usual since the crypto migration will be part of the upgrade. “
Backup prior to upgrade
There are a couple of different options for backup prior to the upgrade dependent on the installation of your Alteryx Server.
Backup on virtual environment
If you have installed your Alteryx Server in a virtual environment and you can perform snapshots, then this probably the best and most complete option. One thing to note is that you must stop the Alteryx Service prior to the snapshot to ensure consistency in the MongoDB.
MongoDB backup
The MongoDB backup should be taken if you aren’t able to do a snapshot. The service must be stopped before the backup to ensure consistency. There is a MongoDB command that can be run, but it is also essential that you take copies of some key files. These are :-
RuntimeSettings.xml from the ProgramData\Alteryx folder.
SystemAlias.xml from the ProgramData\Alteryx\Engine folder.
SystemConnections.xml from the ProgramData\Alteryx\Engine folder.
And finally, it is also important to use the Alteryx Service command to get the server secret.
Testing the upgrade
A test plan is essential when going through an upgrade of Alteryx Server to ensure a smooth transition to the new version.
The best way to test an upgrade is to have an Alteryx Sandbox Server and run the process on there first. Whilst this doesn’t absolutely guarantee a smooth upgrade because you will still need to follow the pre-upgrade steps, it greatly improves the chances and allows for safer fuller testing. It will also allow you develop and document the upgrade, test and sign-off process.
When developing a test plan the main areas to consider are:-
Workflows that contain Python.
Workflows that contain R.
General Workflows that cover the general mix of tools.
Designer considerations
There is a challenge with version compatibility between Alteryx Designer and Alteryx Server when using Built-in authentication (see below) and a mix of versions 2022.1 (and above) and 2021.4 (and below).
This change with version 2022.1 and above means that there is need to have a more coordinated approach when performing a Server upgrade to this version or above. You will need to upgrade the Alteryx Designer version at the same time as the server to maintain connectivity, because the issue manifests itself by not allowing an Alteryx Designer of 2021.4 or below to connect to the Gallery to open or publish workflows. If you are on the same version, then there is no issue.
Backout plan
Before embarking on the upgrade process, it is essential you make sure that you have a robust backout plan in place using the backups mentioned above, and if possible that it has been tested.
Troubleshooting
The following are some potential issues and how to solve them that we have experienced when working with clients.
Service not starting
There can be several reasons why the Alteryx Service might not start after an upgrade.
System settings
Check the system settings to ensure that if the MongoDB has been migrated that the path in the Data Folder section of Persistence has been updated to reflect the new path.
Error Duplicate Key
If you see a message in the Gallery log referencing “duplicate key error”, take a copy of the log and the AlteryxServiceLog.log and then contact Alteryx support (support@alteryx.com) as you will need to manually remove entries from the MongoDB. This can be pre-empted by doing the pre-upgrade checks mentioned above.
Chained Apps
If you have previously updated your Alteryx.config int the Alteryx\bin\server\config folder to extend the timeout between Apps, then you will need to re-add this setting back in as it is non-standard.
Https settings on Base Address and Web API Address
In recent versions an extra Web address has been added to the Gallery section of System Settings and this can cause a small issue if you are already using an SSL Gallery address. You will need to ensure that the Web API Address also has the “https” in the address.