Alteryx Server Knowledge Base
Definitive answers from Server experts.Alteryx Server Upgrade Guidelines - Checklist to upgrade Alteryx Server
How to perform mandatory pre-upgrade checks in Alteryx Server:
Server upgrades are a critical part of a product, especially in Production environments. This article outlines the mandatory checks that are required to be verified before the upgrade of an Alteryx Server environment.
Prerequisites:
- Alteryx Server
- All
Procedure:
Checklists to verify before the upgrade:- Back-up of your Alteryx Server:
- Alteryx Server MongoDB backup
- Alteryx Server Best Practices
- Backup of RuntimeSettings.xml across all the nodes
- If there are any customizable changes done in the RuntimeSettings.xml file, taking a backup of this file is important, as the upgrades would overwrite this file.
- By default, this file is found under – C:\ProgramData\Alteryx\ location.
- Backup of alteryx.config file across all the nodes
- If the alteryx.config file is customized to include any additional parameters, for instance – customized HTTP headers, etc, taking a backup of this file is important, as the upgrades would overwrite this file.
- By default, this file is found under – C:\Program Files\Alteryx\bin\server\config\alteryx.config
- Take note of the "Controller --> General" section, "Worker --> General" section and "Engine --> General" section of Alteryx Server's System settings, if the server is going to be upgraded to 2022.1, because of the new auto-config changes introduced from 2022.1 .
- Controller --> General section of Alteryx System Settings, specifically the configuration for AMP Engine:
image.png
- Worker --> General section of Alteryx System Settings, specifically the number of workflows allowed to run simultaneously
image.png
- Engine --> General section of Alteryx System Settings, specifically the Engine type, Memory limit and the number of processing threads
image.png
- Controller --> General section of Alteryx System Settings, specifically the configuration for AMP Engine:
- Take note of the “Log-on” user details and the Run-as permissions for the Run-as user, as you would need to verify these after the upgrade:
- After the upgrade, the Log-on user would need to be re-configured based on your pre-upgrade configuration, as this is a Windows-based setting:
image.png
- Also, “Run-as” user configuration and permissions must be verified as per your pre-upgrade configurations:
image.png
- After the upgrade, the Log-on user would need to be re-configured based on your pre-upgrade configuration, as this is a Windows-based setting:
- Ensure no backup processes should be running at the backend:
- As a regular process of maintenance and backup, there would be backup processes pre-scheduled on the Alteryx Server machines during a maintenance window across organizations.
- Make sure that the scheduled backup processes of Alteryx Server, are completed, before initiating an upgrade of the Alteryx Server.
- If not, the backup process would end up with the lock on the MongoDB, causing the upgrade to fail.
- Ensure that there are no active schedules running during the upgrade:
- Before initiating an Alteryx Server upgrade, make sure the Alteryx Server machines do not schedule any workflows.
- If there are any scheduled workflows before the upgrade window, make sure those schedules are completed without any issues, and the Alteryx Server queue is empty.
- This will also prevent corruption of schedules and helps in a smoother upgrade.
- Upgrading while the active schedules are running would result in the following error, as outlined in this article:
Error Message : "There was an error in Slave_Thread::DoWork: Server Error: 500 Server Error Key fields must be a WString: AS_Schedules__ID”.
- No manual workflows are running on any of the Server nodes:
- This can be verified by opening the “Task Manager” and navigating to the “Details” tab.
- Make sure that there are no “AlteryxEngineCmd.exe” processes running on the Server nodes’ Task Manager.
- If there are any “AlteryxEngineCmd.exe” processes running, it means that there are workflows executed at the moment, and it is required to make sure that these workflows are completed successfully and there are no “AlteryxEngineCmd.exe” processes anymore on the Server nodes’ Task Manager window.
image.png
- Ensure that the Alteryx Service is down across all the nodes.
- If this is a single node Alteryx Server, make sure you are stopping the “AlteryxService” from the Services window.
- If this is a multi-node, please note the order of shutting down the processes matters and would be as below:
- Shutdown the Worker nodes (Please note – The AlteryxService would be in “Stopping” status for a long time if there are any active jobs/workflows running at the moment and we need to wait until all the jobs are completed, or you could also kill the “AlteryxEngineCmd.exe” process to forcefully kill the running jobs/workflows)
- Shutdown the Gallery nodes
- Shutdown the Controller node
- Shutdown the Mongo-DB
- From/To version of your Upgrade:
- The version from which the server is upgraded to which version is a major checkpoint to verify, as the MongoDB structure varies for each upgraded version.
- The table on our help documentation illustrates the version of each MongoDB version, and the corresponding Alteryx Server version
- Make sure that the Alteryx Services are down across all the nodes.
- Launch the command prompt as an administrator on the Alteryx Server Machine
- Navigate to <%Program File%>/Alteryx/bin folder location and run the command -
mongod --dbpath <Your MongoDB folder in the Persistence location> --port 27018
For example:
image.png
- The database would be started with the focus moved to following line at the end of your command prompt:
image.png
- Now that the MongoDB is started, launch another command prompt as an administrator, and run the below command to connect to your mongoDB and verify the versions collection:
mongo localhost:27018/AlteryxGallery
image.png
- Enter the following command to execute and get your latest version of the MongoDB
db.versions.find({},{Number:1, _id:0}).limit(1).sort({$natural:-1})
image.png
- The “Number” field's value in the above step should match with your current Alteryx Server version that you have installed (you can verify in the Control panel as well) as pointed in our help documentation here. For instance, the Number value of 28 corresponds to Alteryx Server version between - 2020.2 to 2021.1.
- Besides these, when you query the "show collections" command on the above command prompt, it will list all the collections on the AlteryxGallery schema. Please verify if you have any collections with the suffix - “_InProcessMigration” collections anywhere:
- For example – appInfos_InProcessMigration – These InProcessMigration collections would appear, if there were any earlier failed/partial migrations.
- Take a backup of the MongoDB and contact Alteryx Support to fix these collections.
- If you had successful Alteryx Server upgrades in the past, you would see - “database migration successful” message in your Alteryx Gallery logs. Until your last upgrade is successful, you would only see the collection names suffixed with _postMigration_xx, where xx is less than or equal to your Alteryx server version's MongoDB schema number, as listed in this documentation. These collections mean that your last upgrade was successful and there are no dirty upgrades.
- Please note - there are only a few collections that are upgraded in each version (for example, if you are upgrading to 2020.4, you would only see appInfoPostMigration_28. The other collections will have lesser migration schema numbers like subscriptionsPostMigration_27.
- If you have recently upgraded to 2020.4 and above and if you do not see this collection named - appInfosPostMigration_28, please take a backup of your MongoDB and contact Alteryx Support.
- Python Upgrades
- If the Alteryx Server version is to be upgraded to 2020.4 and above from 2020.3 or below, you would need to take a backup of the workflows that have the Python tool or Python-based Connector tools (Salesforce Input, ADLS, Power BI, Dynamic CRM, Google BigQuery, OneDrive), and make sure the Python version is upgraded on the Alteryx Server versions on or above 2020.4. i.e - Prior to 2020.4, there were multiple tools within Alteryx that leveraged the embedded Python version 3.6. After upgrade to 2020.4 and above, these tools would be using embedded Python version 3.8.
- If you are already on 2020.4+ and your upgrade path is from 2020.4+ to a later version, in that case, the Python version would have been upgraded already and this step can be ignored
- Please refer to the links below for more information on the Python upgrades:
- Custom Python Packages
- During upgrade, our Python environment is re-built and this might uninstall the custom Python packages.
- Please make sure that you take a note of the custom Python packages in the environment, and make sure this is re-installed after the upgrade.
- This link would help to guide the steps on installing custom Python packages in Alteryx environment.
- Note - If the environment is a multi-node setup, please make sure that the required custom python packages are installed across all the worker nodes of the environment, after the upgrade.
- Verify that the metadata of the important MongoDB collections are valid
- This points to the business metadata like user information, subscriptions, AD information, etc, and this needs to be verified to have valid values, and there are no metadata corruptions, to ensure there is a smooth upgrade.
- Please refer to this article to verify each of your business metadata is valid, before the Server upgrade.
Additional Resources
@lepome : I have tried Chrome (Version 93.0.4577.82), Edge (Version 93.0.961.52) and Internet Explorer. None work.
The image below is what I see in Chrome and Edge.
