Prior to Alteryx Server version 2018.4, migrating workflows was a three-step process:

1. Deny the problem exists
2. Procrastinate
3. Acquiesce

There were two ways you could “migrate” workflows. You could connect Alteryx Designer to your Gallery, open a workflow and save it locally, then publish it to a new Gallery environment. This method is time-consuming if you had a lot of workflows. On top of that, you can’t access workflows that haven’t been shared with you, so administrators looking to migrate all workflows are out of luck.

There is also the New Workflow button in Gallery. You can download a workflow .yxzp from the Gallery in your old environment, and then upload the .yxzp to a new environment. This is still time-consuming if you had a lot of workflows, but at least you could access all workflows and not just those that had been shared directly with you.

A New Way to Migrate Workflows in Alteryx

Workflow migration from development to production is an inescapable part of the software development lifecycle. Even if you are using Alteryx to avoid code, you probably still have a concept of a sandbox and production. So when it came time for migration, if you had a lot of workflows, you cleared your schedule for the entire week. Fortunately, in Alteryx Server version 2018.4, Alteryx introduced four new endpoints that facilitate proper workflow migration.

These endpoints require four preliminaries:

• Alteryx Gallery enabled
• Source and target Gallery environments on version 2018.4 or later
• Curator access
• An API client (the macros I provide)

Once you have the preliminary steps out of the way, migrating workflows is a four-step process. Each step corresponds to an API endpoint.

Step 1: Finding Workflows Marked “Ready for Migration”

api/admin/v1/workflows/migratable/?subscriptionIds={comma separated subscriptionIds}/

Workflows can be marked as ready to migrate. Under workflow settings in the Gallery, there is a check box labeled Ready to Migrate. The API will return a list of all the workflow IDs of workflows that have been marked.

You can also filter which workflows appear in this list. The endpoint takes a comma-separated list of subscription IDs as a query parameter and will return all workflows marked as ready to migrate under the specific studio(s). If no subscription IDs are provided, all workflows that have been marked as ready to migrate will be returned. This is a lightweight endpoint that will return just three properties:

1. The workflow ID
2. The currently published version ID
3. The subscription ID (the user) the workflow belongs to

Step 2: Download the Workflow

api/admin/v1/{appID}/package/

We need to download the actual workflow files to migrate from one location to another. Once we have the workflow IDs from step 1, this endpoint will download the .yxzp file.

Step 3: Publish the Workflows to the New Environment

api/admin/v1/workflows/

Now we have a bunch of workflow files that need to be published to the target environment. This endpoint allows you to make a post request to publish the workflows we’ve downloaded in step 3.

This endpoint requires a multi-part form that contains information such as workflow owner. This means we can change ownership between the source environment and the target environment during migration. If a workflow is connected to your email address in the source environment, we can use the form to assign ownership to someone else in the new environment. You can also set other workflow options to determine the behavior of the workflow in the new environment, i.e. does the workflow belong in the public gallery? Can it be downloaded by other users?

Since we are able to migrate to and from the same server, we can use the migration endpoints to manage workflows on a single-server setup.

Step 4: Toggle “Ready to Migrate” Flag

api/admin/v1/workflows/migratable/{appID}/

The final endpoint allows you to toggle the Ready to Migrate flag for a given workflow back to False in the source environment after the workflow has been successfully published in the target environment. This way, it will no longer appear as Ready to Migrate until a user or an admin turns the flag back on.

Before you jump in, here are a couple of features to keep in mind:

• So far, I’ve been using the term workflow, but the migration API can move applications, macros and workflows. If it can be published to Alteryx Gallery, it can be moved.
• A workflow does not have to be marked as Ready to Migrate in order to be migrated. The first endpoint provides the IDs of workflows marked Ready to Migrate for convenience. You can download and migrate any workflow if you have its ID.

Some Additional Migration Insights

With these features in mind, there are some considerations to be aware of:

• The migration endpoint does not migrate schedules. Schedules will need to be set up in the new environment.
• Be mindful of data connections and credentials. If you are moving to a new machine and using aliases or data connections in your Alteryx workflows, those need to be set up in the target environment for workflows to function properly.
• Make sure you set paid subscription with expiration for users who need to access the migration API. If this isn’t set, the API may give you strange error responses.

________

If you’re ready to start migration, here are two macros that will help you out. Before you install my macros, please install the R package “alterryx” per the instructions here: https://community.alteryx.com/t5/Alteryx-Knowledge-Base/Install-R-Packages/ta-p/41265

To find your keys required for migration, check in the setting page of the Alteryx Gallery under Admin API.