• Alteryx Server
  • Version 2018.3+
• Embedded MongoDB or User-Managed MongoDB replica set where you can identify the Master node with the following conditions:
  • All three MongoDB databases (AlteryxGallery, AlteryxService, AlteryxGallery_Lucene) must have the same username and password
    • MongoDB user must have readWrite access 

1. Download and run the appropriate Alteryx application for the version of Alteryx Server you are currently using, attached to this article (.yxzp file).
   • Note: Our current version of this Application is Server Pre-Upgrade Check (2018.3+) [2.2.5 - Public].yxzp
   • For continuity, the previous version of this Application is still available for download but is no longer supported by Alteryx Support:
     • Server Pre-Upgrade Check (2018.3 - 2022.3) [2.2.0 - Public].yxzp
     • Server Pre-Upgrade Check (2018.3 - 2022.3) [2.2.1 - Public].yxzp
   • It is highly recommended that you run this workflow from the Controller machine that holds the database. This will allow the workflow to perform additional checks for issues that may prevent the Alteryx Service from starting post-upgrade.  If you are running it from a different machine, you must replace localhost (see Step 2) with the machine name of the Controller machine that holds the database. The machine you are running from must be able to communicate with the Controller.
     • i.e.: localhost:27018 would be replaced with myservermachine:27018
2. Gather the Server MongoDB's host name, username, and password.
   • If using the embedded MongoDB, the Host, Username, and Password can be found in the Alteryx System Settings > Controller > Persistence section:

• For a user-managed MongoDB, contact the MongoDB Admin for the details

There are some major MongoDB changes starting in Alteryx Server version 2020.1. These database changes (also known as schema changes) are completed by a process referred to as a "schema migration". This schema migration is triggered the first time the AlteryxService restarts after the upgrade.

In order to help minimize the risk of errors during this schema migration process, we have provided an Alteryx application that will run checks on your Mongo database prior to upgrade.

The output of this application is a .pdf document with a summary of what changes (if any) must be made prior to the upgrade.

Note: This application is only intended to validate issues commonly faced during customer upgrades and may not cover every issue.  It does not guarantee that your upgrade will complete successfully.

This article will refer to specific collections and fields within the Mongo database. A full schema of MongoDB can be found here: MongoDB Schema Reference | Alteryx Help
 

Configure and Run the Application

Review the Function & Scope of this Application:

Review & Agree to the Application Disclaimer:

1. To run the Application, you must consent to the Disclaimer

• Failing to consent to the Disclaimer will result in an error when running this Application.

Configure the Application:

1. Select the current version of Alteryx Server that you are running.
2. Select the Server UI (Gallery) authentication method.
   • If unsure, please check the Alteryx System Settings > Server UI (Gallery) > Authentication section.
3. Enter the Host, Username, and Password values gathered from Step 2 of the Prerequisites section above.
4. Select Finish to run the application.

How to Read the PDF Report Output

The output has the following sections:

• Current Database Schema Version
• Null/Incorrect Database Entries
• Duplicate Users

Current Database Schema Version

Note: This section will always contain data.

This section shows the current Schema version, as reported from the AlteryxGallery.versions collection.

Please check that the MongoDB AlteryxGallery Schema Version shown here corresponds to your current version of Alteryx Server, according to the MongoDB Schema Reference. If it does not, please contact Alteryx Support, reference this article, and include the PDF Output.
 

Null/Incorrect Database Entries

Note: This section will only contain data if there are entries that need to be corrected prior to upgrade.

This section checks various collections in MongoDB that are known to contain values that can prevent the schema migration from completing successfully.

Please reference the below table for the various checks. If any of these fields are returned in your PDF report, please see the corresponding "Next steps" column.
 

Duplicate Users

Note: This section will only contain data if there are entries that need to be corrected prior to upgrade.

This section checks the AlteryxGallery.users collection in MongoDB for users that have duplicate emails, for example:
 

Please refer to this article (How to Fix Users with Duplicate Email Addresses ) for steps on how to correct these values, and reach out to Alteryx Support if you need additional assistance.
 

Known Issues

mongo_migration_pull_data_schema_agnostic (180): Tool #43: Collection dataConnections not found in database AlteryxGallery.

There are no data connections set up on your server. Please ensure to check the box at the top of the Server Details tab within the app. This is a temporary known issue.
 

mongo_migration_pull_data_schema_agnostic (180)    USERS_MongoDB Input: Mongo Error (getCollectionNames) : { msg:"Authentication failed.: generic server error" code: Authentication failed.: generic server error } 

Check your database details are correct, and re-run.
 

AYX MongoDB Input Macro_WA (309): Record #1: WINIDENTITYS_MongoDB Input: Collection windowsIdentitys not found in database AlteryxGallery. AYX MongoDB Input Macro_WA (309): The output connection "WindowsIdentities" was not valid

You selected the wrong Server UI (Gallery) Authentication method. Confirm your Server UI (Gallery) Authentication method in the Alteryx System Settings > Gallery > Authentication section.
 

mongo_migration_pull_data_schema_agnostic (180)    COLLECTIONS_MongoDB Input: Mongo Error (getCollectionNames) : { msg:"No suitable servers found (`serverSelectionTryOnce` set): [connection refused calling ismaster on 'pod-741045.a.ayxcloud.com:27017']: generic server error" code: No suitable servers found (`serverSelectionTryOnce` set): [connection refused calling ismaster on 'pod-741045.a.ayxcloud.com:27017']: generic server error } 

If you are only getting an error on the COLLECTIONS_MongoDB Input tool, this means your Server UI (Gallery) contains no Collections. Please contact Alteryx Support, and reference this article.
 

"ToolId #202: The field "LastLoginDate" is not contained in the record."

This error is caused by an old defect where the "LastLoginDate" field for Gallery users is not being populated in Gallery environments that use SAML authentication. The defect has been fixed in Server 2021.3. As a workaround, please perform the Server Pre-Upgrade checks by manually running the queries found on the linked articles:

• How to Identify and Fix Null/Incorrect values in Users - Alteryx Community
• How to Identify and Fix Null/Incorrect values in Subscriptions - Alteryx Community
• How to Fix Users with Duplicate Email Addresses

• Install or Upgrade Server | Alteryx Help
• How to Identify and Fix Null/Incorrect values in Users - Alteryx Community
• How to Identify and Fix Null/Incorrect values in Subscriptions - Alteryx Community
• How to Fix Users with Duplicate Email Addresses
• MongoDB Schema Reference | Alteryx Help