App Building Guidelines
An Alteryx analytic app is a self-contained program that performs a specific function for the user. The interface must be simple and the app designed with a single goal in mind. The app should perform a limited range of tasks focused on an optimal user experience. Considering that users run the apps you build in a web browser, the back-end design needs to be clever, elegant, and efficient.
Most Recent Vintage Dataset
When you author an App that uses a specific dataset, make sure the selected dataset is set to use the Most Recent Vintage version of the dataset. This means that Alteryx Designer automatically uses the latest dataset version installed on the user’s computer. This applies to Demographic Analysis tools (Allocate), Behavior Analysis tools (Solocast), Calgary tools, Drivetime, Geocoder, and the Reference Base Map in the mapping tools. To set the dataset, go to Options > User Settings > Edit User Settings > Dataset Defaults.
Meta Info Tab
Information that you fill in on the Meta Info tab of the Workflow Configuration window displays in the App details on the web.
Use File Name: This option presents the name of the file.
Custom: Select this option to give the App a friendly name. For example, the App file itself might be called Download_Weather_Data then the custom name would be the same but without the underscores, Download Weather Data.
Description: The description entered here is the description that shows on the web for the app, so please make sure the description is accurate and user-friendly.
URL: The URL field provides the ability to include a link to an external website.
Display Text (optional): Use this field to supply the display text for the URL.
(Macros Only) Tool Settings: These settings only apply to macros. For more information on the macro repository, refer to Macros under User Settings. These settings allow you to create multiple versions of a macro. Macros saved to the macro repository display in the tool palette.
Root Tool Name: Enter a name for the tool. You can have multiple tools with the same root name, however, only one tool appears in the tool palette.
Tool Version: Enter the tool version number. The most current version of a tool appears in the tool palette. To see a menu where you can access older versions of a macro tool, drag the tool to the canvas and right-click it.
Tool In-Database?: Select this option if the tool can be used in a workflow with In-Database tools.
(Macros Only) Tool Palette: The settings only apply to macro workflows. For more information on the macro repository, refer to Macros under User Settings. These settings control how macros display in the tool palette. Macros saved to the macro repository display in the tool palette.
Category Name: Enter the name of the category in which the macro should be displayed in the tool palette.
Search Tags: Enter terms that a user might use to search for and locate the macro. By default, File Name, Custom Name, Author Name, and Company Name are included as search tags.
Author: Provide the details of the Analytic App creator.
Name: Enter the author's name.
Company: Enter the company with which the author is affiliated.
Copyright: Enter copyright information.
Set to Default: Select to undo your work and use the default text.
Remember as Default: Save the text that you entered as the default.
Extension .yxwz
When authoring an app, make sure you have saved the file as a YXWZ file even if you changed the workflow type to Analytic App. If the file extension is left as a .yxmd, it opens as a workflow and not as an App.
Apps created in version 9.0 can no longer be saved as YXMD files.
Map Input
The Map Input tool gives the App consumer the ability to select a location or draw a polygon or line using the map input feature. Map questions should be short but descriptive and a base map should always be used. When choosing a base map, make sure you select Most Recent Vintage.
Finally, if Draw mode is selected, ensure the User Can Label Features setting is always checked. This gives the user the option to add a name to each of their custom polygons.
Report Output
When you save an App to Alteryx Server, if the output of the report is rendered as PCXML, the application provides the option for the end-users to not only preview the report on the web but also to download the report in any of our supported report formats. Supported report formats include; PDF, Microsoft Word, Microsoft Excel, and HTML.
When you author an App, the output can be any of our supported report formats. To utilize PCXML set the Output Mode in the Render tool to Choose a Specific Output File, and for the Output File, use APP_NAME.pcxml.
When you preview a report in PCXML you will not see footers, but they will be available when downloaded as a PDF, Word, or Excel document.
Read/Write Files: Macros in an App
For web Apps, you can only read and write to files that are within the same folder as your App or a lower-down folder, in other words, any folder that is within the folder that contains the app (can be more than 1 level down.) This rule also applies to Macros that you wish to use for your App, unless it's a standard macro that is part of the Alteryx product installer or a data installer.
%temp%
Do not use %temp% to write to the temp directory when you build workflows or apps to be saved to Server. Keep all file paths within the workflow. If you develop a chained app, use only the file name rather than any file path, for example, .\fileOutput.yxdb and not %temp%\fileOutput.yxdb or something similar. Select a file by browsing to it and then change the file dependency path to a relative path via the Workflow Dependencies window.
Prohibited Tools and Events
These Alteryx Designer tools and events are prohibited in the Community Gallery, also known as the Analytics Gallery, due to the numerous possible configurations and actions that can be performed:
If your workflow uses one of the prohibited tools or events in a safe manner, you can apply for an exemption to run the workflow in the Gallery. To apply for an exemption...
Email curator@alteryx.com and explain how and why each prohibited tool is used, along with the general purpose of the workflow.
Publish the workflow in your Private Studio and check the option Others may download this workflow.
Add the workflow to a Collection and share it with the Alteryx Curator at curator@alteryx.com.
Allow up to two business days for your workflow to be reviewed and an Alteryx Curator to email you the status of your request.
The Predictive Macros included with Designer that use the R tool are allowed in the Community Gallery.
Unsupported App Features for Web
These are not supported in the Community Gallery web environment.
Folder Browse
File Browse (Save as), upload works fine on the web.
If an App throws any errors in the Desktop environment, you can't save it to Server.
App chains longer than 7 apps don't work on Server.
Best Practices for Building Apps
Update Actions
When you use the Action tool to Update/Change Value, unless actually needed, don’t use the Replace a specific string: option. If you change the tool configuration in your workflow due to continued development, you might end up breaking that action tool, because that specific string might no longer exist. Obviously, there are times when you need to use that option but just bear in mind that if you change that string in the tool then you might need to also update the Action tool.
Update Detours
If you use an Action tool to update a Detour tool, try to be complete and update the detour for both possibilities, in other words, detour left and detour right. Otherwise, if you just update for the one condition and you change the workflow while developing then you haven’t accounted for when you need the workflow to go the other way.
End Detours
All detours must end, especially before joining any data streams from a detour to anywhere else in the workflow. A Detour End tool requires no configuration, so is easy to use. Make sure you use them or end the detour with an Output tool.
Use the Error Message Tool
When you write questions, consider your user by anticipating common mistakes. You should issue error messaging using an Error Message tool. For example, if the user must select an option, then throw an error when they don’t select anything, this can avoid the engine throwing errors that might not be meaningful enough to the user to understand how to fix an error. Ideally, throw an error for every question that the user needs to fill in. You can also do more complex conditions to make sure they have filled things in correctly. For example, if they need to fill in a text box with up to 5 trade areas separated by commas (for example 1, 2, 3, 4, 5), you could use a regex condition to make sure there aren’t more than 4 commas in the text box.
Issue Errors with the Message Tool
Along these same lines, try to anticipate cases where the App might fail even when configured properly. For instance, the user might enter an address that fails to geocode and renders no results. You can easily handle messaging in your App by Filtering bad geocodes and then using the Message tool to return a message to the user: "The address you have provided did not geocode. Please check the address is valid and make appropriate changes to it or enter a different address and re-run."
Update Raw XML, Escape HTML Metacharacters
If you are updating raw XML for a tool or using special characters in your Apps, bear in mind that on the web this might not work as anticipated. For example, a Drop Down tool or List Box tool selection on the engine could contain text like: Age By Sex Summary Report:<Report Type=”summary”>Age By Sex Summary Report</Report>
But when this is used on the web it doesn't actually display the question correctly and therefore when this gets used in an action it probably doesn't have the desired effect. A solution is to change the text to be: Age By Sex Summary Report:<Report Type="summary">Age By Sex Summary Report</Report>
Then if you are using the question response in an action, you need to update it to be: EscapeXMLMetacharacters([AllocateSummaryReport])
The Escape XML Metacharacters function was added to the Formula library in version 8.0. You can access it from the Specialized category. This function replaces all XML metacharacters with their escaped versions.
Allocate Variable Trees
The web and the engine return different values when an Allocate variable tree is left empty. If the App has an Allocate variable tree as a question type then you might want to write a condition that checks if the user selected anything or left this empty. For the engine, you could write something like:
[AllocateVariables] == "<Variables />"
When the variable tree has nothing selected, <Variables /> is returned. However, on the web, the value returned is actually nothing, so you would need the condition to be:
isempty([AllocateVariables])
Obviously, we want the Apps to work on both the web and the desktop so the condition actually needs to be:
[AllocateVariables] == "<Variables />" or isempty([AllocateVariables])
If we are also worried about using the <, >, and / characters on the web then we could change the condition to be:
REGEX_CountMatches([AllocateVariables], "Variables") == 1 or isempty([AllocateVariables])
Union Tool
It is best to keep a manually configured Union tool out of any App because in most cases, the workflow changes at runtime. Instead of configuring the Union tool in manual mode, insert Select tools into each connection feeding into the Union tool. When configuring the Select tool, rename and reorder fields as necessary taking proper care to not include Dynamic/Unknown fields. Configure the Union tool using either Auto Config by Name or Auto Config by Position.
Tool Containers and App Organization
App organization is done in part by using different tool containers for different sections of the app. For example, all the reporting tools are typically the last section of an App, and could be placed in a tool container labeled "Reporting".
A Tool Container tool can be color-coded based on the function it is highlighting. Color-coding tool containers make it easier to understand what an app is doing, especially when viewed at a small zoom. This is helpful when troubleshooting or debugging an app that someone else has authored.
Interface tools should be placed in their own containers and color-coded as such. For multi-tabbed apps, it is helpful to place the tools that make up each tab in their own container.
Annotations for Workflows and Apps
Annotations are text boxes that are attached to a specific tool and can be very helpful in describing the role of individual tools. One major benefit is if you move the tool, the annotation moves with it. Under the Workflow Configuration, set Annotations to show.
If needed, you can also set individual annotations to be placed on either the top or bottom of a tool. To change the Annotation, click on the tool, select the Annotation tab, and select or deselect Place Annotation on the Top.
Macro Specific Guidelines
All previous guidelines apply to Macros as well as Apps, with the following exceptions that apply only to Macros.
Macro Inputs
A Macro Input tool should include data. The inclusion of data makes it so much easier to troubleshoot or debug if something goes wrong. There is a text input embedded inside the Macro Input tool. This is the preferred method for macro inputs. If you need a bigger file to serve as the data input, it should be included with the macro where possible. Data file dependencies for a macro should be named following this pattern:
NameOfMacro.NameOfDataFile.yxdb
Input and Output Names should not have a tool number associated with them. From the Macro Input Properties tab, ensure the name is descriptive enough. The Name you specify here is visible to users when they configure the Macro tool.
When there are multiple inputs and outputs, adding a Connector Abbreviation helps the user configure the tool by providing a label on the tool anchor when the tool is placed on the canvas. Go to Macro Input Tool or Macro Output Tool for more information.
Naming Tabs
Tab names should be descriptive for ease of use while the user is configuring the macro tool. Tabs are visible to the user at configuration time. The default Tab name is 'Questions' – not a very descriptive name and this is usually an oversight when developing a macro (or app) with a single tab. See Interface Designer window.
Supporting Macros
Supporting Macros used in a parent workflow should be present with the parent macro or in a supporting directory and named like this: NameOfParent.NameOfSupporting.yxmc.