Skip to main content

Version-to-Version Server Upgrade Guide: Supported Versions

Important

Please see the Server Upgrade Checklist to help plan and execute a successful Server upgrade, including the Pre-Upgrade Checks workflow to identify issues that cause upgrades to fail.

How Does This Document Help?

This document highlights tasks and changes you need to be aware of when upgrading through versions of Alteryx Server. Issues are cumulative, so read through each section as you upgrade through multiple versions. This doesn't replace Release Notes (see links in each section).

Release Schedule

  • Semi-annual releases add features but can also change Server management requiring you or your users to change behavior.

  • Maintenance releases/patches within each quarter address issues found in the initial release. For example, the first maintenance release for 2022.3 would be 2022.3.2.

Legend

PIT-STOP

Significant change that requires upgrading to this version before upgrading to a later version.

MongoDB Upgrade

The Mongo database version is upgraded.

An Alteryx Server upgrade can only include ONE MongoDB version upgrade between your current version and target upgrade version.

CRITICAL

Critical Issue: Admins must address or be aware of when moving to or past this version.

Criteria for Entries in This List

This list condenses each version's Release Notes to highlight where:

  • Admin or Users are required to perform an action.

  • Item is important in choosing an upgrade version (that is, changed behavior or defect).

  • A significant change was made in Server administration.

2022.3

What's New / Release Notes / Server Community Blog / Overview Community Blog

Version

Actions to take when upgrading to—or past—this version.

2022.3

CRITICAL

Upgrade Requirement for 2022.1 Defect TCPE-1100: If Upgrading from 2022.1 to this or later version, a patch is required.

Impact: If currently on 22.1, you must be on 22.1.1.9.42691_Patch_9 or higher before upgrading to or through 22.3 to avoid the defect TCPE-1100.  This defect affects the workflow revision numbers, setting them all to "1".

Task: Apply the latest 22.1 patch before proceeding with the upgrade if you are not already on Patch_9 or later.

2022.3

CRITICAL

MongoDB Re-encryption: Database collections must be re-encrypted with AES256 and SHA256 hashing standard prior to upgrade

Impact: The Crypto Migration Prep Tool should be run prior to upgrade to 2022.3+ to re-encrypt workflows in the background while the Server continues to function. After running the Prep Tool, the first time the Service starts after upgrading a few more collections, as well as the RuntimeSettings.xml, will also be CryptoMigrated.

Task:

Your Server should be on 2021.2 or later before starting this process. If you are on a prior version, upgrade to a version between 2021.2 and 2022.1 prior to attempting to upgrade to 2022.3+.

Run the Crypto Migration Prep Tool prior to upgrading Server and review the Migrator log for error lines containing ;3;. Don't upgrade Server until Migrator issues are resolved. Review log again if Server Upgrade fails as additional collections being migrated could error.

Following upgrade, you can delete the old, unencrypted collections. Contact Support for information on cleaning up the temporary files created and reducing the size of the Mongo database (CSEs see here).

If you need to rollback the upgrade, you will need to restore the backup of the RuntimeSettings.xml made during upgrade, C:\ProgramData\Alteryx\.

2022.3

CRITICAL

Designer Version Requirement: Designer 2022.3 required

Impact: The encryption methods used by 2022.3 Server require Designer 2022.3.

Task: Users must upgrade Designer to save workflows to the Server.

2022.3

CRITICAL

Configuration Change: SAML ACS endpoint must be all lowercase

Impact: The ACS endpoint is now lowercase (/saml2/acs) but was mixed-case (/Saml2/Acs).  This prevents Service start.  [TCPE-940 is asking that both old and new casing be accepted without error].

Task: Change the ACS endpoint in the IDP to all lowercase.

2022.3 Patch 2

Administrative Change: Option to allow users to run workflows using Shared Server Database Connections

Impact: Allow Access to Workflows Without Shared Credentials option added to allow a workflow using a Shared Server Database Connection to be run by anyone the workflow has been shared via a Collection. The other users do not require the Gallery Connection to be explicitly shared with them.

Task: Go to Server UI > Admin > Settings > Assets. Then select the Allow Access to Workflows Without Shared Credentials checkbox.

2022.3

Administration Change: Load Balancer

Impact: Alteryx System Settings > Server UI > Canonical Address options have been added to ensure email messages from the Server will use the URL your users use to access the Server UI.

Task: If you use a Load Balancer, set these values to the URL your users typically use to access the Server UI or API.

2022.3

Server Usage Report has been deprecated

Impact: The Server Usage Report is no longer supported by Alteryx. Previous versions might continue to function.

2022.3

Password Management: HashiCorp and CyberArk password vault support added

2022.3

Download Tool access to less secure handshake renegotiation: Settings file allows site-specific control

Impact: Use the Peer Validation Allow List if receiving "SSL connect error" from Download Tool. Download Tool updated to OpenSSL 3.0.7.

2022.3

Internal Change: Controller Token length

Impact: Server 2021.4 introduced a longer, more secure Controller Token, however, upgrades from 2021.3 retained their shorter Token. If the Token was not Regenerated to the longer length at some point it will be automatically regenerated in the 2022.3 upgrade. This will occur on all nodes in the same manner so they will create the same longer token and be able to communicate with the Controller following upgrade.

Task: Use the new Controller Token to add new nodes to your Server architecture in the future.

2022.3

Defect TGAL-7199: All versions of workflow labeled "1" (corrected 2022.3.1_Patch2)

Impact: When viewing the list of versions of a workflow, all versions display "1" instead of a sequential version number. This is a UI issue and the correct version is being used to run Jobs.

2023.1

What's New / Release Notes

Version

Actions to take when upgrading to—or past—this version.

2023.1

CRITICAL

Minimum Designer Version

Impact: Designer 2022.3 Patch 3 or later is required to connect with Server. See Server 2023.1 Release Notes.

2023.1

Administrative Change: Option to allow users to run workflows using Shared Server Database Connections

Impact: Allow Access to Workflows Without Shared Credentials option added to allow a workflow using a Shared Server Database Connection to be run by anyone the workflow has been shared via a Collection. The other users do not require the Gallery Connection to be explicitly shared with them.

Task: Server UI > Admin > Settings > Assets > select the Allow Access to Workflows Without Shared Credentials checkbox.

2023.1

Password Management: AWS Secrets Manager password vault support added

Impact: AWS Secrets Manager

2023.1

API Additions: For Active Directory (AD) Authentication Servers, an AD Group can be added to a Custom Group

Impact: Endpoints added:

  • POST /v3/usergroups/{id}/activedirectorygroups

  • DELETE /v3/usergroups/{userGroupId}/activedirectorygroups/{adGroupSid}

2023.1

Administrative Change: Azure Active Directory Group Support with SAML Authentication

Impact: Admins can now sync users and group access to Server using Azure Active Directory (Azure AD) and the SCIM protocol.

Task: Configure Alteryx Server SCIM Azure Active Directory

2023.1

DCM Feature: Option to disable DCM synchronization between Designer and Server

Impact: This feature is useful on a Prod Server to ensure users don't inadvertently synchronize and use a Prod credential in their local Designer.

Task: Alteryx System Settings > DCM > select the Block DCM Connections Synchronization between Server and Designer checkbox. For more information, go to DCM - Server.

2023.1

Administrative Change: Workers can connect to User-Managed MongoDB with unique credentials.

Impact: This allows for auditing per Worker.

2023.1

Database Connections: End of life for 32-Bit Database Connections

Impact: End support 32-bit database connections FAQ. 32-bit connections will no longer function.

2023.1

R Installer

CRITICAL

R Upgrade: Embedded R version upgrades from 4.1.3 to 4.2.3 in RInstaller_2023.1.1.200.exe+

Impact: R version will be 4.1.3 or 4.2.3 as follows:

  • R version 4.1.3 = Server 23.1 installation, all versions

  • R version 4.1.3 = RInstaller_2023.1.1.123

  • R version 4.2.3 = RInstaller_2023.1.1.200+

  • Patches do not affect the R version.

Task:

  • Use a specific RInstaller_2023 to force a specific R version.

  • Reinstall external R libraries and direct users to retest R in workflows when upgrading to 4.2.3.

  • Designer's R version should match the R version used on Server

How To Use the R Tool with Packages Compatible with R Version 4.2.3

2023.1

Analytic App Defects (corrected 2023.1_Patch_2)

Impact:

  • TPRI-2043: Drop Down and List Box Tools return NAME from NAME:VALUE rather than VALUE

  • TGAL-8126: Date Tool returns previous date from the date selected

2023.1

CRITICAL

Connect Product: Connect is not compatible with the initial 2023.1 release

Impact: Release notes will indicate which patch is compatible with 2022.3.

2023.2

What's New / Release Notes

Version

Actions to take when upgrading to—or past—this version.

2023.2

MongoDB 6.0.5

MongoDB Upgrade: Embedded MongoDB upgrades from version 4.2.15 to 6.0.5

Impact: Embedded MongoDB upgrades to 6.0.5

Task: If using embedded MongoDB, upgrading to this version or later will upgrade MongoDB to version 6.0.5. Note free drive space requirements of 1x-2x your current MongoDB size.

2023.2

CRITICAL

MongoDB Upgrade Dialog: The dialog to initiate the embedded MongoDB upgrade is minimized

Impact: When upgrading to 2023.2, after selecting Finish on the upgrade the Embedded MongoDB migration dialog opens but is immediately minimized, giving the impression that upgrade is complete [TGAL-9041]. For more information, go to Error in Service logs when upgrading to Server version 23.2: Invalid feature compatibility version value, expected '5.0' or '5.3' or '6.0'.

Task: Ensure that you make this dialog visible and click to initiate the MongoDB upgrade. The Service will not start until the MongoDB is upgraded.

2023.2

MongoDB Change: __ServiceDataBlob field removed from AlteryxGallery Collections

Impact: The __ServiceDataBlob field has been removed from AlteryxGallery collections; fields now appear as standard MongoDB fields.

Task: If you have admin workflows that used the ServiceDataParser macro to unpack data from this blob, they will need to be refactored.

2023.2

DCM Administration Change: DCM Connections can now be shared for collaboration

Impact: When sharing a DCM Connection in Server UI, the option "Share for Collaboration" allows the DCM Connection to be used by other users in their Designer. For more information, go to Data Connection Manager: Server UI > Share in Designer.

Task: This change allows for easier collaboration of shared workflows and creation of new workflows using a colleague's DCM Connection.

2023.2

Python Upgrade: Embedded Python upgrades from 3.8.5 to 3.8.16

Impact: Users should retest Python in workflows. Engine still uses Python Version 3 so there should be little impact on scripts.

Task: For more information, go to Alteryx Embedded Python.

2024.1

What's New / Release Notes

Version

Actions to take when upgrading to—or past—this version.

2024.1

Administrative Feature: Ability to Transfer Asset Ownership via UI and API

Admins can transfer ownership of workflows and schedules between users via Server UI or using Server API V3 endpoints.

Impact:

  • New API endpoints added. Go to Workflow Endpoints and User Endpoints.Points de terminaison du workflow

    • PUT /v3/workflows/{workflowId}/transfer

    • PUT /v3/users/{userId}/assetTransfer

  • New notifications. See Notifications.Notifications

Note

  • Workflow job history is not visible to the new owner.

  • Workflow will move to the new owner's studio, impacting visibility to other users in source or destination studio.

  • Additional elements need to be shared with new owner to run workflow successfully:

    • DCM Connection

    • Shared Gallery Database Connection

    • Shared Gallery Credential

2024.1

New Feature: New Database Option Added (SQL DB)

User-Managed SQL Server database can be used instead of MongoDB. Currently, the only officially supported version of SQL is MSSQL Server 2019 and 2022.

Impact:

2024.1

CRITICAL

Python Upgrade: Embedded Python upgrades from 3.8.16 to 3.10.13

Impact:

The following error message appears if an incompatible version of a Connector is used in Designer: " Version 3.8 was not found in our alteryx distribution. Please select another version. Internal Error - Deadlock detected."

Task:

  • All Connector Tools must be replaced with a new version.

  • Users should retest Python in workflows. Engine still uses Python Version 3, so there should be little impact on scripts.

2024.1

CRITICAL

MongoDB Datetime Field Change (Service Timestamps Moved to UTC Format in Server Databases)

Impact: We moved all datetime fields to UTC to improve handling of time zone and daylight savings time changes. For more information, go to Server 2024.1 Release Notes.Server 2024.1 - Notes de publication

  • All Server APIs with a timestamp element are affected.

  • If you upgrade from an older version to 2024.1, the timestamps of existing assets will be converted to the new UTC standard when AlteryxService starts.

Task: Review how datetime fields are handled in applications that access MongoDB or the API. They might need to be adjusted to expect the datetime in UTC.

2024.1

DCM Dev/Prod Server Management: Prod Server can redirect Dev DCM to Prod Connections

Impact: DCM Connections and DCM Connection Handling added to Admin menu. For more information, visit the following help pages:

Task: Add DCM redirections to Prod Server to allow workflows migrated from Dev to access Prod data sources with no changes in the workflow.

2024.1

DCM Administration: User Permission Granularity

Impact: New DCM permissions added. For more information, go to the User Roles and Permissions help page.

2024.1

DCM Administration: DCM Generic External Vault added

Impact: You can configure a generic vault that can retrieve secrets from any vault with a programmatic interface using basic authentication.

2024.1

Administration Change: DCM Concurrent Sharing

Impact: You can share the same DCM Connection for Collaboration and, separately, for Execution. Previously you could only choose 1 sharing option. For more information, go to Data Connection Manager: Server UI.

2024.1

Insights End of Life

Impact: Insights no longer available in Alteryx Server. Go to our FAQ page for more information.

2024.2

What's New / Release Notes

Version

Actions to take when upgrading to—or past—this version.

2024.2

CRITICAL

Upgrade Embedded MongoDB to Version 7

Impact: Impact: As part of Server 2024.2 installation, embedded MongoDB will upgrade to version 7.0. Minimum Server version for upgrade is 23.2 (MongoDB version 6.0).

Task: Ensure Server version is 2023.2 or 2024.1, then follow the steps described in Server 2024.2 Release Notes.

2024.2

Migrate Data Connections and Workflows to DCM

You can now migrate Shared Server Data Connections to DCM Connections. To do so, check the How to migrate Server Data Connections to DCM and Data Connections.

2024.2

Possibility to Limit Users in a Studio to One User

Curators have the option to turn off shared studios by limiting the users in a studio to one user. As an admin, you can now easily transfer asset ownership by transferring the workflow from one studio to another.

To limit the number of members in a studio to one user, go to Admin > Settings > Configuration > Users. Then select the Limit Studio to 1 User checkbox. For more information, go to Alteryx Server Settings.

2024.2

Restriction to Make Workflows Public: Global Setting

Curators can now control the way workflows are getting published (publicly or non-publicly) by selecting or clearing the Restrict Public Workflow (Global) checkbox. To do so, go to Admin > Settings > Security.

For more information, go to Alteryx Server Settings.

2024.2

Designer Proxy Settings Expanded

In Designer, Options > User Settings > Edit User Settings > Proxy > Enable New Proxy Settings (Preview) has been added to provide better control over proxy settings and to allow PAC scripts.

Note: In this Initial release, the setting applies to several features (for example, Download Tool) but not others (for example, Connectors or ODBC) in Designer. See User Settings for details.

2024.2

System Setting “Cancel jobs running longer than (seconds)“ Now Applies to All Jobs

In previous versions, this setting only applied to scheduled jobs. To allow manual jobs to run longer than scheduled jobs, clear this setting and use the two new Server UI options explained below.

For more information, go to Alteryx Server Settings.

Option Added to Cancel Long-Running Manual Job Runs

In Server UI > Admin > Settings > Assets, there is a new option to cancel manual job runs (including API job runs) running longer than a specified time. This applies to all Workers unless the Worker has set Alteryx System Settings > Worker > General > Cancel jobs running longer than (seconds). The Worker setting overrides the Server UI setting.

Option Added to Cancel Long-Running Scheduled Job Runs

In Server UI > Admin > Settings > Assets, there is a new option to cancel scheduled job runs running longer than a specified time. This applies to all Workers unless the Worker has set Alteryx System Settings > Worker > General > Cancel jobs running longer than (seconds). The Worker setting overrides the Server UI setting.

2024.2

API Updates:

API Filtering Added to GET v3/workflows/{workflowID}/jobs

The GET v3/workflows/{workflowID}/jobs endpoint can now optionally filter by status and resultCode, returning a list of job IDs that match these filters. For more information, go to Server 2024.2 Release Notes and Workflow Endpoints.

  • All Server APIs with a timestamp element are affected.

  • If you upgrade from an older version to 2024.1, the timestamps of existing assets will be converted to the new UTC standard when AlteryxService starts.

Task: Review how datetime fields are handled in applications that access MongoDB or the API. They might need to be adjusted to expect the datetime in UTC.

New API Endpoints for Subscriptions (Studios)

Curators can now manage subscriptions (studios) using Server V3 API endpoints. These endpoints help to edit subscriptions in bulk and provide the ability to move individual users back to individual studios.

For more information about these endpoints, go to Subscription Endpoints.

API Updates for Workflow Endpoints

  • SourceAppId is now returned in the response body of the following API calls:

    • GET/v3/workflows

    • GET/v3/workflow/{workflowID}

    • GET /admin/v1/workflows/migratable

  • The following can now be called by Artisans:GET v3/workflows/{workflowId}

  • Filtering by status and resultCode has been added to GET v3/workflows/{workflowID}/jobs:

For more information, go to Server 2024.2 Release Notes and Workflow Endpoints.

New API Endpoint to Allow Updating Individual Schedule Settings

Use the new API endpoint PATCH /v3/schedules/{scheduleId} to update a schedule without having to populate several required fields to make a single change. For more information, go to Schedules Endpoints.

Updates for Job Endpoints

  • New API endpointGET /v3/jobs/{jobId}/messages

    This endpoint is for Curators only. Use the jobId as an input parameter to retrieve the corresponding messages for that job.

  • Updated API endpointGET /v3/jobs/{jobId}

    The GET /v3/jobs/{jobId} endpoint has been updated so users can see the jobs that have been shared with them via Collections.

For more information, go to Job Endpoints.