App Building Guidelines

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.

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.

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.

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.

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.

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

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.

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.

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

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.

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 used in a parent workflow should be present with the parent macro or in a supporting directory and named like this: NameOfParent.NameOfSupporting.yxmc.