Alteryx Server provides a scalable server-based analytics solution that lets you create, publish, and share analytic applications, schedule and automate workflow jobs with increased processing power, create, manage, and share data connections, and control data access.
To understand a little more about the Alteryx Server universe, please see our comprehensive blog, Establishing an Analytical Culture with Alteryx Server.
Some of the main concerns that you as a user or even an Alteryx Server administrator may have when updating an Alteryx Server are:
What will happen to existing workflows in the Gallery?
Did they continue to run without compatibility issues?
Do end users need to take any action?
How to carry out this upgrade smoothly without impacting productivity?
The main objective of this blog is to demonstrate in practical terms how to upgrade an Alteryx Server safely. Specifically, we will be upgrading from version 2023.1 to version 2023.2. It is also important to highlight that our environment is a single-node environment, which means that only one server has the functions of Controller, Worker, Gallery, and Persistence (MongoDB).
We can consider the Alteryx Server upgrade in three main steps:
Backup
Installation
Post-upgrade check
So, let’s start our adventure!
Backup
Alteryx System Settings Backup
I particularly like manually backing up the existing settings in the Alteryx System, both by copying the runtimesettings.xml file and collecting screenshots of all screens (I admit that this part is boring and far from mandatory, but I’m on the team that prefers to be safe than sorry).
The runtimesettings.xml file can be found at the following location (please make sure to use the correct disk letter and partition relative to the path where Alteryx Server was installed):
Remember that all configuration information displayed in the Alteryx System Settings Wizard is stored in the runtimesettings.xml file. The Wizard collects this information directly from there.
Macros Backup
Another very important step is to ensure the continuity of existing macros in the environment even after the upgrade. Not only user-created macros but also custom tools that are not native, such as the Publish to Tableau Server Tool or even Crew Macros.
Typically, the files related to these tools/macros are available in the following folder:
C:\ProgramData\Alteryx\Tools
Again, please make sure to use the correct disk letter and partition relative to the path where Alteryx Server was installed.
Copy the contents of this folder to a safe and accessible location for use after the upgrade.
In our case, we only have three non-native macros/tools in the environment:
It is important to note that the macros must be compatible with the most recent version. Some macros may be incompatible with newer versions or require an upgrade.
Macros that use Python or R require special attention during updates since the Python or R version may change after the upgrade for some Alteryx Server versions. Some libraries are incompatible with newer versions of the environment. So always be aware of the versions used.
We will return to them in topic three (after the upgrade) to copy the files from the backup folder to the folder of the new version of Alteryx Server. Keep in mind that during the installation wizard, it is possible to modify the Alteryx installation folder, so pay attention to specifying the precise location.
It can also be beneficial to get a list of Python and R libraries installed in the environment to validate that they will stay after the installation or if they will need to be reinstalled. If the environment does not have any Python or R workflows, this step can be skipped.
Keep in mind that the Update Wizard for the version in question of Alteryx Server already includes the standard Python and R packages. In other words, they are updated and installed automatically.
MongoDB Backup
If you are using a user-managed instance of MongoDB, it is recommended that you contact the team that manages your MongoDB Server as a whole, not just the Alteryx database. This communication will be essential to align the backup procedures to be performed so as not to impact other databases in the environment.
On the other hand, if you are using an Alteryx Server with the embedded version of MongoDB, this is the easiest scenario. This is the scenario of our server that will be updated.
In any case, in all cases, always consult the official Alteryx documentation.
The first step is to stop the Alteryx Service. In the case of multi-node environments, be aware that there is a shutdown order for nodes/services: Workers, Gallery, Controller, and MongoDB.
After the upgrade, the initialization sequence to be followed is: MongoDB, Controller, Gallery/Worker nodes.
After that, basically, to perform a MongoDB backup, we will need to open the command prompt (cmd) with admin privileges and navigate to the folder where the binary files of the current Alteryx Server instance are stored.
From there, we can run the following command:
alteryxservice emongodump=path_to_backup_location
Adapting the command parameters to our environment:
AlteryxService.exe emongodump="D:\Alteryx Backup"
After successfully executing the command, a new cmd window will automatically open, demonstrating in real time the backup activities being done:
The estimated time for this step will vary depending on the use of Alteryx Gallery. The more workflows, macros, and input files (among others), the longer this backup will take. As our environment does not have many users/workflows, the backup was performed in a few seconds.
Once the backup has finished, the additional cmd window will close automatically, and you will return to the main screen demonstrating that the procedure was successful:
An important tip for specifying the location of the folder to store the backup in the command is to use double quotes. Especially if the destination folder has more than one name and one or more spaces between them, such as: "Alteryx Backup".
Do not proceed with the update if there is an error in the MongoDB backup process. Analyze and correct the error and only perform the update when ensuring that the MongoDB backup has been made successfully.
Migration Prep Tool
Additionally, to assist with the latest versions of Alteryx Server, Alteryx has created and made available a tool to assist with the pre-migration process called Migration Prep Tool.
This is basically a utility that allows for a pre-migration of a database of workflows and apps to be more quickly migrated to the new AES256 standard.
This Migration Prep Tool is optional and a separate command line utility. You only need to run it once before you upgrade from Server 2022.1 (or earlier versions) to 2022.3.x or newer.
The complete documentation for using the Migration Prep Tool on the current version of our server can be found at this URL.
It is important to note that there are some specific situations where the use of the tool is recommended; these are:
If the Server installation you are upgrading is a production system or a development system that can’t be down for more than a few hours
You have more than a few hundred workflows
You are running on MongoDB Atlas or user-managed MongoDB
Even if your environment does not fit into any of the above conditions, Alteryx still recommends using the Migration Prep Tool before upgrading for a successful process.
Additionally, If you choose to not run the Migration Prep Tool before the upgrade, the tool will be installed and run as part of the 2022.3 upgrade installation or above.
The first step is to download and install the Migration Prep Tool from the official Alteryx website. We suggest taking advantage of this moment and also downloading the installation file for the new version of Alteryx Server:
Note that on this screen, there are also instructions and useful documentation links to assist with the upgrade process. One of them in particular catches our attention: “Please follow instructions here to retain the Publish to Tableau Server Tool, which has been removed from the installer.” This reinforces the importance of backing up all non-native macros/tools to ensure their continuity after the upgrade.
Once you have completed the Migration Prep Tool installation process, let’s run it:
There are three command options to run the Migration Prep Tool. Review the documentation to run the correct command for your environment. In our case, as we are talking about a single node environment with MongoDB embedded, this is the command to be used:
AlteryxServiceMigrator22_2.exe -p -c "mongodb://user:NON_ADMIN_MONGO_PASSWORD@localhost:27018/AlteryxService?authSource=AlteryxService"
Once the command has been executed successfully, we can say that all preparations are done. We can finally start the upgrade!
Installation
The first step to check before installation is the compatibility between the version of Alteryx Server and the version of MongoDB in your environment. Use this document to reveal compatibility information.
In our case, as we will be upgrading the Alteryx Server from version 2023.1 to version 2023.2, it will be necessary to upgrade the MongoDB version as well. Specifically from version 4.2 to version 6.0.
Even more important is to check if the upgrade can be done directly from your current version to the desired version. In some cases, especially when you want to upgrade from a more defended version to the most current version, it will probably be necessary to upgrade to an intermediate version that supports upgrading to the desired version.
Always pay attention to this information and consult the official documentation.
Once we have confirmed that there is compatibility between the versions of Alteryx Server and MongoDB, we can begin the installation process. As it will also be necessary to upgrade MongoDB from version 4.2 to version 6.0, and we will use the embedded version, at the end of the Alteryx Server installation wizard, a second installation wizard for the new version of MongoDB will automatically start.
Let’s start the installation process. We will only cover some wizard screens with important information.
On the screen above, you can modify the Alteryx Server installation location if desired. You can also choose to keep the installation location.
Don’t worry about the native installed R and Python packages; at some point, the wizard will install all their dependencies automatically. See the screenshot below:
Once the Wizard responsible for upgrading the Alteryx Server has finished, the following message will be displayed:
This message reinforces the information that it will also be necessary to upgrade MongoDB. In this specific case, there is already a built-in wizard that will carry out this process right after the Alteryx Server upgrade.
Click the Finish button, and then the MongoDB upgrade process will start automatically:
During the process, another backup of the database is made to a local folder of your choice.
Once the installation is finished, the following success message will be displayed:
After that, the installation process for both Alteryx Server and MongoDB will be completed.
The last step here is to copy the files used for the custom tools from the backup folder we created at the beginning of the process to the equivalent folder where Alteryx Server was installed (in our case: C:\ProgramData\Alteryx\Tools).
After the installation, we can also upgrade to any macro version if needed and re-install Python and R libraries previously installed by the user in case they don’t come natively in the newer version.
Post-Upgrade Check
Now that the hard part is done, it’s time to do some checks to make sure everything is working perfectly.
Here are some steps (which are not mandatory; they are just good practices that I learned from some of my colleagues and have used in several upgrades) to check the proper functioning of your Alteryx Server:
Check if the Gallery is live
Open the Windows Services menu and make sure the Alteryx Service is up and running
Open the Gallery URL and log in with your username
For multi-node environments, confirm that all worker nodes are up and running
Try to run a workflow, schedule a workflow
Publish a flow from the Designer to the Gallery
Create and delete a collection
Access the scheduling page (jobs) and check whether all your appointments are listed there
Again, these procedures are not mandatory, but I personally prefer to check more than necessary than not check at all. As the saying goes, better safe than sorry.
Closing
The upgrade of an environment with Alteryx Server is not an easy task, especially if it is a multi-node environment. However, by reading the official documentation and using the available resources in a correct and efficient way, it is possible to facilitate the upgrade tasks and, at the same time, maintain a high standard of security to keep the process safe.
If you’re looking for professional help on how to manage your Alteryx Server environment or simply how to get the most value out of the platform and its features, phData would love to help!
Reach out to us today for any questions, advice, and best practices.
