As we already know from reading other blogs here on the phData website, 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.
If you are new to this world and want to understand more about the Alteryx Server universe, please see our comprehensive blog, Establishing an Analytical Culture with Alteryx Server.
Additionally, suppose this is the first Alteryx Server update you will perform. In that case, you must understand the main points of attention and concerns that we have as administrators of Alteryx Server instances. Please see our blog about the important considerations when updating the Alteryx Server.
Our main goals in this blog are to:
Understand some of the new functionality provided by the new version of Alteryx Server 2024.1
Pre-update recommended tasks
Installation steps
Post-upgrade check
Without further ado, let’s start this new journey of knowledge!
New features in Alteryx Server 2024.1
Beforehand, we will not cover all the new features. Only the most relevant ones for our update process and day-to-day use. Let’s go to them:
SQL Database Support
Transfer Asset Ownership
Crypto Migration Improvements
UI Search and Sort for Workflows and Schedules
Server SAML Authentication Without Using CEF
Service Timestamps Moved to UTC Format
SQL Database Support
Finally, the prayers of many Alteryx Server administrator users have been heard, and we now have SQL database support!
This addition provides the flexibility to leverage relational databases according to your preferences and requirements. But keep in mind that, at the moment, only Microsoft SQL Server is supported.
To start using this DB backend solution, you must make some adjustments in the Alteryx System Settings wizard, specifically in the Controller and Server UI sections.
We will be making a specific blog available for this type of migration in the very near future.
Transfer Asset Ownership
Another important feature added, which was also a clamor from the Alteryx community, is the possibility of transferring asset ownership.
The problem of having to add a user to a studio other than their own has always been very common, especially when an employee who had many assets (workflows, macros, schedules) left the company. Depending on the number of assets, republishing them, specifically workflows, has always been a very tedious and extremely manual task.
According to the documentation, when a workflow is transferred to a new owner, it moves from the old user’s studio to the new user’s studio, and the ownership field is updated. When workflows are transferred, the version history remains essential for audit compliance and version control.
Additionally, this process brings a notification system that is automatically on when you upgrade. The notifications are sent when users transfer workflows via the Server UI and API. Both past and new owners are notified.
Crypto Migration Improvements
During the process of updating Alteryx Server to the latest versions, Alteryx strongly recommends the use of an auxiliary tool called the Migration Prep Tool. This tool’s objective is, among other things, to automate the pre-migration process that exists in a version update, including the MongoDB backup.
However, in some specific scenarios where error messages were generated, they were not as clear as they should have been. Something that has been corrected, as we now have more detailed and assertive error messages.
There are also 3 new Migration Prep Tool run options:
Default: Run the pre-migration and pre-migration check simultaneously (
-p)Run just the pre-migration (apps) (
--appsonly)Run just the credential validation step (
--credonly)
UI Search and Sort for Workflows and Schedules
Another improvement requested by the community was better search results and indexing of assets in the Alteryx Gallery. We often find ourselves searching for a workflow using a keyword in the title, and even so, the query result is unsatisfactory.
In the new version, this problem has been resolved for both administrator and regular users, including the following search options:
Search by Workflow ID on Schedules and My Workspace
Search by Owner on Schedules and My Workspace
Filter by engine AMP on Schedules and My Workspace
Filter by Type on My Workspace
Server SAML Authentication Without Using CEF
The Designer’s SAML authentication browser has been changed from Chromium Embedded Framework (CEF) to the machine’s default browser. Although it does not greatly affect the end user’s life, this change brings a good security perspective from a governance point of view because it will help to avoid security issues with CEF becoming out of date before the Designer can be released with an updated version.
Service Timestamps Moved to UTC Format
Something that has also always caused some confusion among users is the possibility of choosing a specific timezone when creating schedules. This could be considered an issue, especially when considering daylight-saving periods. This “problem” is being resolved in this update by converting all timestamps to UTC format.
By default, the user interface now displays all the date-time fields according to the user’s profile time zone. The only exception is the frequency field, which shows the time zone chosen when creating the schedule.
In general and summarized, these new features caught the most attention in this new version. If you want to understand all the new features, we recommend reading the official documentation, which can be found at the following link:
Pre-update Tasks
As we described in the previous version’s update blog, the preparations for the update remain the same but contain only a few details to pay attention to.
It is worth remembering that we will not yet use Microsoft SQL Server as a backend database solution here. This will be covered in another specific blog on the topic in the near future. Therefore, we will continue to use MongoDB for this update.
Let’s get started!
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 better 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 important step is to ensure the continuity of existing macros in the environment even after the upgrade. This includes user-created macros and 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 use the correct disk letter and partition relative to the path where the 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 that are used.
After the upgrade, we will return to them 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, the Alteryx installation folder can be modified, 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 whether they will stay after the installation or need to be reinstalled. This step can be skipped if the environment does not have any Python or R workflows.
Keep in mind that the Update Wizard for the Alteryx Server version in question 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 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. Our server will update this scenario.
In all cases, always consult the official Alteryx documentation.
The first step is to stop the Alteryx Service. In multi-node environments, be aware that there is a shutdown order for the following nodes/services: Workers, Gallery, Controller, and MongoDB.
After the upgrade, the initialization sequence to follow is MongoDB, Controller, and Gallery/Worker nodes.
After that, 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 how Alteryx Gallery is used. The more workflows, macros, and input files (among other things), the longer this backup will take. Our environment does not have many users/workflows, so 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 called the Migration Prep Tool to assist with the pre-migration process.
This utility 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, but it is highly recommended that you use it. 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 the above conditions, Alteryx recommends using the Migration Prep Tool before upgrading for a successful process.
Additionally, if you choose not to run the Migration Prep Tool before the upgrade, it will be installed and run as part of the 2022.3 upgrade installation or above.
The first step is downloading and installing 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 this screen also includes instructions and useful documentation links to assist with the upgrade process. One of them, in particular, catches our attention:
“With the 2024.1 release, the Insight tool has reached end-of-life and is no longer available in Alteryx Server.”
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" -i <host/IP_Address> -t <Controller_Token>
Note: Unlike the previous version update, we must now specify the Controller token!
Once the command has been executed successfully, we can say that all preparations have been completed. We can finally start the upgrade!
Installation
The first step to check before installation is the compatibility between the Alteryx Server version and the MongoDB version in your environment. Use this document to reveal compatibility information.
As we will be upgrading the Alteryx Server from version 2023.2 to version 2024.1, it will not be necessary to upgrade the MongoDB. Both versions of Alteryx Server use Embedded MongoDB 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, upgrading to an intermediate version that supports upgrading to the desired version will probably be necessary.
Always pay attention to this information and consult the official documentation.
Once we have confirmed compatibility between the Alteryx Server and MongoDB versions, we can begin the installation process.
Note: We will only cover some wizard screens with important information.
You can modify the Alteryx Server installation location on the screen above if you desire. 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:
Based on the options above, we prefer to continue with the installation process, this time with Predictive Tools. However, feel free to choose other options as needed and manually install Predictive Tools at a later time.
Click the Finish button, and the Predictive Tools Install will start automatically.
Once the installation is finished, the following success message will be displayed:
In our scenario, there is still one more installation, the patch 2024.1.1.1.49. Let’s then run the AlteryxServerPatchInstall_2024.1.1.1.49.exe file wizard.
If you receive the following message when opening the file, do not worry about it. This means that the patch has already been installed automatically along with the main Wizard:
Patching will generally only be necessary if you install a release and a few weeks or months after Alteryx releases a bug fix. Generally, if you download the installer, the patch is already included.
After that, the installation process for Alteryx Server will be completed.
The last step 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 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 we have learned from some of our 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 running.
Open the Gallery URL and log in with your username or configured authentication method.
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 we prefer to check more than necessary than not check at all. As the saying goes, it is better to be safe than sorry.
Closing
Upgrading an environment with Alteryx Server is not easy, especially if it is a multi-node environment. However, by reading the official documentation and using the available resources correctly and efficiently, it is possible to facilitate the upgrade tasks and maintain a high standard of security to keep the process safe.
If you’re looking for professional help managing your Alteryx Server environment or simply getting the most value out of the platform and its features, phData would love to help! Reach out to us today for any questions, advice, or best practices.
