Cloud Execution for Desktop Learning Guide

[AndrewL]

This guide is designed to help new users get started with Cloud Execution for Desktop. It covers the ins and outs, the dos and don’ts, and the gotchas, from sign-in to scheduling. Follow along with the provided sample workflow.

Requirements

Before you get started with Cloud Execution for Desktop, you need:

• Alteryx Analytics Cloud (AAC) Enterprise Version
  • Cloud Execution for Desktop must be enabled on the workspace by an admin.
  • Private Data Handling is required.
• Alteryx Designer Desktop Version 2023.1 Patch 1 or Newer
• Data Connection Manager (DCM) is required to authenticate an AAC workspace in Designer Desktop.
• Users must have the Cloud Execution for Desktop Creator role assigned.

Link Designer Desktop and Alteryx Analytics Cloud

Before you can take advantage of Cloud Execution for Desktop, you need to create a link between Designer Desktop and your Alteryx Analytics Cloud (AAC) workspace. To do so…

1. In Designer Desktop, go to File > Manage Connections to open DCM.
2. Select Alteryx Links in the left-hand menu and select the + New button.

3. Analytics Cloud is preselected as the default Technology. Provide the required information:
   • Data Source Name: This is the display name (label) for this link. The name is displayed in the Save As and Open menus. Using a descriptive label makes identifying the connection easier in the future.
   • Cloud Instance URL: This is the URL that you use to access the Alteryx Analytics Cloud platform. Contact your AAC admin for this information.
   • Workspace Name: This is the name of your AAC Workspace, as it appears in the URL. For example, you might access AAC via https://company.alteryxcloud.com/?workspace=my-workspace. In this case, you would enter my-workspace in the Workspace Name field. Contact your AAC admin for this information.

4. Select Save.
5. Now you need to link credentials. Select + Connect Credential to get started.
6. Cloud Execution for Desktop supports the OpenID Connect (OIDC) authentication method. This option is preselected in the Authentication Method dropdown.

7. In the OIDC TOKENS section, use the Credential dropdown to choose an existing credential or select Create New Credential.
8. If you need to create a new credential, enter a Credential Name. This label should help you identify it in the future.

9. The Vault is DCM by default.
10. Select Test Connection. This step is optional but helps verify that your connection details are correct.
11. Select Create and Link to finish. If you’re not already signed in to your AAC workspace, your browser asks you to authenticate to AAC.

⚠️ If your connection fails, ensure that the Cloud Instance URL and Workspace Name for your AAC connection are correct.

Once you successfully connect Designer Desktop to the Alteryx Analytics Cloud platform, the connection details are available via File > Manage Connections > Alteryx Links. Select the Data Source Name in the Name column to view the connection details, edit the connection, or delete the connection.

View, Edit, and Synchronize Alteryx Links

Once you’ve created a link between Designer Desktop and AAC, you can seamlessly connect and synchronize your Designer Desktop DCM connections with AAC for Cloud Execution for Desktop. This allows you to keep your connection information consistent across both platforms.

Your credentials are available to sync via the Connections section of each link created via Alteryx Links.

1. Go to File > Manage Connections > Alteryx Links.
2. Select the Name of the existing link to open and view the details
3. To update the link, select the Edit button. Make the necessary edits and select Save or select Cancel to return to the previous screen.
4. In the Connections section, you select Synchronize to sync your credentials between Designer Desktop and AAC.

Once the sync is complete, a confirmation appears. If there is an issue with the sync, an error message appears.

ℹ️ It's a best practice to synchronize your connections and credentials anytime a change is made or a new connection or credential is configured. This ensures that your DCM connections are available in Cloud Execution for Desktop.

Save to a Workspace

Now that we can authenticate to AAC, have Cloud Execution for Desktop enabled in our environment, and have successfully linked Designer Desktop to AAC, let’s get a workflow or app saved.

For this guide, we use the attached sample workflow, PharmacySpatialProcess.yxmd. Download the sample workflow to follow along, or feel free to open any workflow or app you already have completed.

ℹ️ Note that any screenshots that show the PharmacySpatialProcess.yxmd sample workflow show the inputs as Amazon S3 Download connectors, but the attached version uses Text Input tools.

Once your workflow or app is ready, you can save it directly to AAC using the link established earlier. To save your workflow or app to AAC…

1. Select File > Save As > Alteryx Analytics Cloud and select the workspace you want to use from the list of available connections. If the workspace you’re looking for is not in the list, select Add New Link and follow the steps above to create a link.

2. The name of your workflow or app is entered into the Workflow Name field by default. You can change this if needed. Any assets included in your workflow or app are listed below the workflow name. This includes any inputs, outputs, macros, etc., that might need to be packaged with your workflow.

3. Check the Group Assets by tool checkbox to see which tools use the assets in the list. Uncheck any asset that is not needed.

Note: Using this checkbox does not change any associations of the assets or alter the way they are packaged; it just makes it easier to scan through the list and make sure everything looks correct.

4. In this example, the HeaderMacro.yxmc is not required because it is used by the Report Header tool, which is installed by default, so it is unchecked.
5. Select Save. If you are not already signed in to your AAC workspace, a web browser opens and prompts you to sign in. Once authenticated, Alteryx validates your workflow or app to make sure that it does not use prohibited (non-DCM) data connections. Review Tool, Engine, Driver, and Connector Compatibility for a complete list of supported tools, connectors, and ODBC drivers. When the save completes successfully, a green notification bar appears at the bottom of the canvas.

ℹ️ The validation process takes place during the Save and is not a separate action. You will not see anything related to validation unless it fails, in which case an error is shown.

Once saved, you can find your workflow or app in AAC. You can get there by either opening a web browser and going to your AAC workspace or by selecting View in the green notification bar after saving.

Select Library at the top and then Designer Desktop from the list on the left. Here, you’ll be able to see all assets available to you in Cloud Execution for Desktop. You can narrow the view by selecting Owned by me or Shared with me.

You will be able to see the workflow or app's name, who it is shared with, who owns it, and when it was last updated. You are listed as the owner for anything you save directly to AAC.

Using Cloud Execution for Desktop

Your workflow is saved to AAC—now what? Once your workflows and apps are saved to AAC, there are a couple of ways to use them.

Workflows

Designer Desktop workflows saved to AAC can be run in several different ways using Cloud Execution for Desktop. You can run workflows can be run on demand, schedule them to run at a specified time, and add them to Plans.

Run Manually

To run a workflow manually…

1. Navigate to Library and select Designer Desktop from the panel on the left.
2. Find the workflow you want to run and select the three-dot menu next to it. Select Run.

3. A notification appears at the bottom left, showing that the job has started.

To find your results…

1. Navigate to Jobs and select Designer Desktop.
2. Jobs are listed in order from newest to oldest.
3. Find the job you want the results from and select the output button.

4. The Job Outputs window opens and lists all outputs returned by the job. Select the download button for the outputs you want to download.

The Jobs tab includes other helpful information. You can see the Job ID, Asset name, type of run, who ran it, and when it ran (including how long it ran).

You can filter this list of jobs to only show jobs run by you or by using the Filter option. The Filter option allows you to filter the view based on Asset Name, Run Type, Run By, and Status.

Each of the filtering options reveals a checkbox list of values that can be used to narrow down the results. For example, if filtering by Status, you have the option to only view jobs that have a status of Queued, Running, Success, Cancelled, or Failure. Select the checkbox next to the statuses for which you want to filter. Multiple selections are allowed.

Schedules

To schedule a workflow…

1. Navigate to Library and select Designer Desktop from the panel on the left.
2. Find the workflow you want to schedule and select the three-dot menu next to it. Select Schedule.

3. Select +Add New Schedule.

4. Add a name for your schedule.

5. Set up the Occurrence. See below for more details on each option.

6. Select Schedule. Congratulations! You’ve just set up your first schedule.

Which occurrence should you use? Let’s examine the options to see how they work so you can determine which best suits your needs.

• The Recurring option allows you to set a frequency for how often you want the schedule to run. This is helpful when you need to run a workflow at the same interval on a repeating basis. The options include hourly, daily, weekly, and monthly. Each option has a different set of configuration choices. For example, hourly allows you to set the number of minutes past the hour that you want your schedule to run, the time zone to use, and the start and end date and time. Monthly allows you to select either the day of the month (1-31) or the week of the month (1-5) and the day of that week. You can then specify the time you want the schedule to run, the time zone to use, and start and end dates.
• The Once option prompts you to specify the date and time you want the scheduled run to take place and the time zone to use.
• The Custom option allows you to use cron syntax to specify the schedule. You can use cron syntax to schedule a run from hourly to annually and anything in between. As a quick overview, a cron schedule is defined as a space-separated string of values. The values are listed in order of minute, hour, day of month, month, day of week. For example, if you want your schedule to run at 10:15 PM on March 23rd, you enter 15 10 23 3 *. In this example, the * (asterisk) is used as a wildcard for the value for the day of the week. This allows the schedule to run at 10:15 PM on March 23rd, regardless of what day of the week that date falls on. You can learn more about cron syntax here.
• The Event Trigger option allows you to set the schedule to run once a triggering event occurs. This can include updating a database or file or creating a new file. Select Event Trigger as the frequency to get started.

• Select the desired connection, or if you don’t see the connection you want, select Create Connection to open the connections page.
• Select Create Connection in the top right.
• Select the connection you want to create and follow the configuration steps to complete. The information required varies depending on the connection being created.

Another way to schedule your workflow is to navigate to Schedules at the top of the page and select New.

This brings up the schedule configuration window. The configuration menu looks a little different when entered this way. You are required to specify what type of asset you’re scheduling and then select the asset itself.

For Asset Type, you have a choice between Workflow, Desktop Workflow, Plan, and Reporting Project. To schedule the workflow you just saved to AAC, you’ll want to select Desktop Workflow. Once selected as the asset type, the Asset dropdown shows you only the desktop workflows available to be scheduled.

Once you have the asset type and asset selected, the remaining configuration for the new schedule is the same as above. Select the frequency you want to use, enter the required options, and select Schedule.

Once finished, the newly configured schedule appears on the Schedules page.

Update Existing Schedules

Just like creating schedules, you can update existing schedules from either the Library page or the Schedules page.

1. If you’re on the Library page, select the three dots next to the workflow and select schedule. When the dialog box appears, you will see a list of all of your existing schedules, along with the option to add a new schedule as before.

2. To edit the existing schedule, select the three dots to the right of the schedule name. You can choose to edit, disable, or delete the schedule.

3. Select Edit to open the schedule configuration window. Update the configuration to what is needed and select Save.

The process to update a schedule from the Schedules page is the same. Select the three dots next to the schedule you want to update, select Edit, and update the configuration options.

 

Plans

Designer Desktop workflows saved to AAC can also be added to plans. Plans allow for the execution of a sequence of discrete tasks in the Alteryx Analytics Cloud. For more details on Plans in general, go to the Help Page.

To add a Cloud Execution task to a plan…

1. Navigate to Plans in the panel on the left.

2. Select +New in the top right corner.
3. Once the plan opens, drag Designer Desktop from the panel on the left onto the plan canvas.

4. After adding the task to the plan canvas, use the menu on the right to select the Designer Desktop workflow you want to use, and choose Select.

5. The task updates with the workflow name.

You can add multiple tasks to a plan from any of the items listed in the panel on the left. Tasks can be linked together to run in sequence using the connection lines, similar to the connection lines between Designer Desktop tools. Each of the output anchors triggers any task connected to it based on its condition. The check mark output anchor triggers downstream tasks when the current task is completed successfully. The “>” anchor triggers downstream tasks regardless of the success or failure of the current task, and the “x” anchor only triggers downstream tasks if the current task fails.

Analytic Apps

You can save Analytic Apps from Designer Desktop to AAC the same way workflows are saved, but these can't be scheduled. To run an Analytic App using Cloud Execution for Desktop…

1. Navigate to the Library page.
2. Find the analytic app you want to run and select the three dots to the right.
3. Select Run Analytic App.

After selecting run, a new browser tab opens, and Alteryx App Builder launches. This loads the user interface for the selected app. Fill in the necessary values and select Run. While the job is running, the browser changes to show it is processing.

Once completed, it returns to the app configuration screen, which has a notification bar at the bottom.

To view the run's results, select Download in the notification bar. This downloads a ZIP file containing the app's output.

Wrap up

Hopefully you now have a solid understanding of how to utilize Cloud Execution for Desktop to run and schedule your Designer Desktop workflows and apps. All of the resources linked throughout this article can be found in the Help documentation. If you haven’t yet, download the attached sample workflow and try it out yourself!

PharmacySpatialProcess.yxmd

[AlteryxMarco]

Great summary and level of detail @AndrewL thanks for taking the time to pull this together!