Alteryx Server Knowledge Base

Alteryx_KB · ‎08-02-2021

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-2022.x. Upgrading to 2020.x+
Embedded MongoDB
- The application can also connect to a User-Managed MongoDB replica set if 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.

Pre-Work

Download and run the appropriate Alteryx application for the version of Alteryx Server you are currently using attached to this article (.yxzp file).
- Our current version of this Application is:
  - Server Pre-Upgrade Check (2018.3 - 2022.3) [2.2.1 - 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 Checks to 2020X PUBLIC v1.3.yxzp
  - Server Pre-Upgrade Check (2018.3 - 2022.3) [2.2.0 - Public].yxzp
- It is highly recommended 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
Gather Host, Username, Admin Password, and Password from Alteryx System Settings > Controller > Persistence section.
image.png

Configure and Run the Application

Review the Function & Scope of this Application:

image.png

Review & Agree to the Application Disclaimer:

image.png

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 :

image.png

Select the current version of Alteryx Server that you are running.
Select which method of Authentication you are using on the Gallery.
- If you are unsure, please check the Alteryx System Settings > Gallery > Authentication section.
Enter the Host value gathered from Step 2 of the Pre-Work above.
Enter the Password value gathered from Step 2 above.
Select Finish to run the application.

How to Read the PDF Report Output

The output has the following sections:

Current Database Schema Version
Current Database Configuration (This section will only appear if you've enabled Mongo Shell Queries)
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.png

Current Database Configuration

This section will always contain data.

This section checks the current version of your MongoDB by directly querying your MongoDB and will only appear if Mongo Shell Queries are enabled and configured properly.

If you are using an embedded MongoDB, please check that your current MongoDB version matches the supported Embedded MongoDB Version. If the versions don't match, please contact Alteryx Support.

Example Output

image.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.

Section	Issue	Next Steps
User values to update	Users with null FirstName, LastName, Email, SubscriptionId, or Curator fields	See this article
Subscriptions to update	Subscriptions with null ExpDate (Type 2)	See this article
Collections to update	(Windows Authentication only) Collections that contain users with incorrect SIDs	Contact Alteryx Support
Users with mismatched SIDs	(Windows Authentication only) Mismatched SIDs between AlteryxGallery.users and AlteryxGallery.windowsIdentitys	Contact Alteryx Support

Example Output

image.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:

FirstName	LastName	Email
Sally	Jensen	sjensen@company.com
Sandra	Jensen	sjensen@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.

Malformed Data Connections

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

This section checks the AlteryxGallery.dataConnections collection in MongoDB for users that are missing Password values, for example:

Id	Connection Name	Reason	Mongo Query
{ "$oid" : "638fac8ce52f995bd405b177" }	ProdServ_1	Password is Empty.	db.dataConnections.find({ _id : ObjectId("638fac8ce52f995bd405b177")})
{ "$oid" : "638facb3e52f995bd405b1a9" }	ProdServ_5	Password is Null.	db.dataConnections.find({ _id : ObjectId("638facb3e52f995bd405b1a9")})

This issue will only impact upgrades to the following versions of Alteryx Server:

2021.4.2.47792
2021.4.2 (Patch 5)
2022.1.1.42590
2022.1.1.3 (Patch 3)
2022.3 LA

If you are updating to a later version of Alteryx Server, this section of the report can be ignored. If you are upgrading to this version, please see the following article: TGAL-6990 Upgrade to 2021.4.2.47792 or 2022.1.1.3.42590 results in failed schema migration if a gall...

If you have any questions or concerns about performing these steps, please reach out to Alteryx Support.

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 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

mse139 · ‎11-08-2021

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 · ‎11-08-2021

@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 · ‎03-03-2022

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

karthikeyanboobalan · ‎05-19-2022

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

Matt_Davis · ‎05-27-2022

@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 · ‎10-07-2022

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

Ariharan · ‎10-17-2022

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 · ‎11-28-2022

@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.