Inspire EMEA 2022 On-Demand is live! Watch now, and be sure to save the date for Inspire 2023 in Las Vegas next May.

Alteryx Server Knowledge Base

Definitive answers from Server experts.

Alteryx Server: Pre-Upgrade Checks

Alteryx_KB
Alteryx
Alteryx
Created

Alteryx Server: Pre-Upgrade Checks


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
 

Environment

 

  • Alteryx Server
    • Current Version 2018.3-2020.x. Upgrading to 2020.x+
  • Embedded MongoDB
    • The application will also connect to a User-Managed MongoDB replica set if you can identify the Master node.

 

Pre-Work

 
  1. Download and run the Alteryx application attached to this article (.yxzp file).
    • Ideally, you will run this from the Controller machine that holds the database. If you are running it from a different machine, you must replace localhost (see Step 3) with the machine name of the Controller machine that holds the database. The machine you are running from must be able to communicate to the Controller.
      • I.e.: localhost:27018 would be replaced with myservermachine:27018
  2. Gather Host and Password from Alteryx System Settings > Controller > Persistence section.
image.png

 

Configure and Run the Application

 

image.png

  1. Enter the Host value gathered from Step 3 above.
  2. Enter the Password value gathered from Step 3 above.
  3. Select the current version of Alteryx Server that you are running.
  4. Select which method of Authentication you are using on the Gallery.
    • If you are unsure, please check the Alteryx System Settings > Gallery > Authentication section.
  5. 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

This section will always contain data.

This section checks the current Schema version, as reported from the AlteryxGallery.versions collection. It will show:
  • The current Schema version in the database
  • The expected Server version that matches this schema version
Please check that this matches the expected "MongoDB Schema Version" for your current version of Alteryx Server found here: MongoDB Schema Reference . If it does not, please contact Alteryx Support , reference this article, and include the PDF Output.
 
Example Output
 
image.pngimage.png

 


Null/Incorrect Database Entries

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.

SectionIssueNext Steps
User values to updateUsers with null FirstName, LastName, Email, SubscriptionId or Curator fieldsSee this article
Subscriptions to updateSubscriptions with null ExpDate (Type 2)See this article
Collections to update(Windows Authentication only) Collections that contain users with incorrect SIDsContact Alteryx Support
Users with mismatched SIDs(Windows Authentication only) Mismatched SIDs between AlteryxGallery.users and AlteryxGallery.windowsIdentitysContact Alteryx Support

 

Example Output
 

 

image.pngimage.png


 

Duplicate Users

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:
 

FirstNameLastNameEmail
SallyJensensjensen@company.com
SandraJensensjensen@company.com



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)    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 Gallery Authentication method. Confirm your 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 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:

 
 
 


Additional Resources
 

Attachments
No ratings
Comments
mse139
8 - Asteroid

Hi, I've tried to run this on our user-managed mongo replica set and I get the below error:

 

ToolId #202: The field "LastLoginDate" is missing. Compare the tool configuration with the input stream.

I'm running this from Designer Version: 2021.2.2.45235.  The server version is 2021.2.  

I am supplying just the primary mongo node's address/port.  We also use SAML authentication.

SophiaF
Alteryx
Alteryx

@mse139 I'm sorry to see you are running into this issue. We are investigating. In the meantime, you can manually run the queries found on the linked articles:

 

Please use the link at the end of the article to contact Support if you need further assistance!

Matt_Davis
5 - Atom

 

I also got the "LastLoginDate" error on ToolId #202 with server version 2021.1.3.22649 and SAML Authentication, but those links were helpful for checking those potential issues using Robo 3T

 

Matt_Davis_0-1646319672016.png

 

Matt_Davis were you able to resolve your error? i'v also got the same error

Matt_Davis
5 - Atom

@karthikeyanboobalan No I did not figure out how to resolve the error.  We do have Robo 3T installed on the server though from troubleshooting a different support case so I was able to run the checks using Robo 3T and the links Sophia provided.

afitchit
5 - Atom

that's pretty cool that you're able to add those features. thanks, Alteryx

Ariharan
9 - Comet

Hi @Alteryx_KB ,

 

We're using the Alteryx server version 2022.1.1, at the moment. When we upgraded the server from 2021.3 to 2022.1.1, we executed the workflow and we were able to see the output PDF with the MongoDB schema version details. Unfortunately, when we try to execute the same pre-upgrade workflow in the 2022.1.1 version, we didn't see the MongoDB schema version in the output PDF.

 

Regards, 

Ariharan R

 

KPOLU
5 - Atom

@Alteryx_KB , We are seeing similar behavior as specified by @Ariharan .  We ran this WF on our server (version is 2021.4.2). The report does not contain MongoDB schema information.