Engine Works
Under the hood of Alteryx: tips, tricks and how-tos.
Reference Shortcuts are a hidden gem in Alteryx. They are the easiest way to use data from interface tools. And yet, most alteryx users don’t know anything about them. I’ll walk through several examples below to show you just how powerful they can be. But First…
What is a reference shortcut?
A reference shortcut is simply %ConstantType.ConstantName%. Tucked away in an obscure help page, Alteryx defines reference shortcuts as “You can use a reference shortcut to use any constant in the configuration of a tool. To specify a constant variable, add a % (percent sign) at the beginning and end of the name: %ConstantType.ConstantName%”. This KB article goes into more detail on constants, including reference shortcuts. It’s well worth the read to ground yourself if you’re new to the world of constants.
How did I learn about reference shortcuts?
Although I was comfortable with alteryx after several months of working with it in 2015, I was suddenly lost when I started learning apps/macros. I was starting to understand the basics, but certain things just weren’t making sense. Action tools are powerful, but it takes a lot of trial and error to harness that power. One thing I couldn’t get around though was how much more cluttered my workflow was once I added in a lot of action tools. For one particular use case, I had one interface tool but needed to use it in 5+ different streams of data. This meant 5+ action tools to do the same thing. I asked the community for alternatives, and AdamR showed me how Reference Shortcuts were the solution to my problem. You can just delete all your action tools and use the %Question.Name% syntax. Thus began my fascination with reference shortcuts.
What are the benefits of reference shortcuts?
Read through the examples for a deeper understanding, but at a high level:
- Simpler. Once you spend a few minutes to understand them, it’s really simple to see how your data is moving from user input into your workflow. Action tools, with all of their power, are much harder to understand how the data is moving around.
- Better debugging. You can use the standard Run button (Ctrl+R) with test values that you enter! This is much better/easier than the debug workflow mechanism.
- Less clutter. By using reference shortcuts instead of an action tool (or action tools), that can make for an easier to digest workflow.
Example 1
I decided to use Weekly Challenges as good examples. You can go through the many other fine solutions that people have submitted and compare it to the Reference Shortcut method. Let’s start with Challenge 5. The goal is to create a simple app where the user selects a single item, and you filter the data based on that item. Here’s my solution:
Let’s first start with our dropdown tool, specifically the annotation tab:
Note that I changed the Name to “Position”. This was intentional to make it easier to reference. The default is the tool name followed the ID [something like Drop Down (25)]. When using reference shortcuts, you reference the name. So a good name is best practice.
Once I had my dropdown named appropriately, I can now setup test values in the workflow configuration >> workflow tab. Click on a blank area in the canvas, and then change the config on the left to the workflow tab:
Notice the bottom one is our dropdown that we named Position. When it’s first added, the value is blank. I like to call this column “test value” because the Question constants will be replaced with the user values when you run it as an app (either the wand or when run from the gallery); the value I’ve entered (33333) is only used when I run the workflow normally (Run button or Control+R). That’s important to understand.
Now that I have my interface tool and a test value, let’s use it in a formula tool:
It may look really weird at first, but it will become second nature if you practice it. Since I’m creating a string field, I have to put %Question.Position% inside quotes. If you find it confusing, try this: first enter the value you want to use as your test value. Let’s put 33333 in there:
Then you would take just your value (33333 inside quotes) and replace it with the reference shortcut.
When you click the run button, check your browse everywhere data to see that 33333 is coming through correctly:
That was easy! My test value is coming through properly. Now we can feel good that when the user runs it as an app or on the gallery, their value will be put into the formula tool with that reference shortcut.
Example 2
Let’s make it a little more complicated and add radio buttons as well. For Challenge 115 you’re tasked with creating an app and displaying a list of beers based on state of origin or style.
Again, I started by adding my interface tools and naming them. I have 2 dropdowns that I’ve named Style and State on the annotations tab. I added 2 radio buttons and named them QueryStyle and QueryState. I then added my test values on the workflow config tab:
Radio buttons and checkboxes return True/False strings. We’ll test the user checking the state radio button and selecting IN. Let’s look at how our filter is configured now:
If the style radio button is selected, then we need style to be equal to what the user selects; otherwise we want to filter for beers that originated from the user selected state. Our 4 interface tools are boiled to a single if then else statement. Notice again that all of our reference shortcuts are inside quotes since they’re strings. Again, we could start with our test values if that’s easier:
We can run the workflow like normal and check our browse to see that all of our records have state=IN:
Example 3
We’ll look at challenge 225 where I use reference shortcuts in a text input in addition to a formula tool. The challenge is to create an app that outputs the time that has passed between a user specified date and the present. The user can decide the units of time that the results should be displayed in.
Again, our first step is adding our interface tools (Date and Listbox) and renaming them in the annotations tab. Notice in the Listbox that I’m just concatenating all of the units selected since my separator is blank:
Let’s setup our test values:
So we’re testing 2016-03-09 with all the units selected. Notice that our test values need to match the right format of the actual data that will be passed. For example, I wouldn’t want to test 3/9/2016 or Years,Months,Weeks,Days,Hours since that format isn’t correct.
If you’re not sure about the format, use the debug view. To do that, go to view >> interface designer and then select the second option called test view. Then make your selections (March 9, 2016 and all the units):
Then click Open Debug and open the debug log at the top:
Notice the values are 2016-03-09 and YearsMonthsWeeksDaysHours. We can then use these as our test values in our workflow.
Let’s have a look at our text input now:
It’s just taking the Date selected. Since we’re in a text input tool, strings don’t need quotes around them. The easiest way to think about it is to first put your actual test value in:
And then replace it entirely with our reference shortcut:
Now let’s have a look at our formula tool:
And the best part about reference shortcuts, we can run the workflow like normal and see that everything is working as expected:
Example 4
For our last example, let’s look at a silly challenge like 202. The goal is to create a Mad Libs style app.
While it’s a silly task, it highlights the real power of reference shortcuts. After you add your textbox tools and rename them, you just add the %Question.ToolName% right into the textbox wherever you want your data to go. Then it’s really easy to test that everything is working by adding test values and checking your browse.
How can reference shortcuts be better?
While I love reference shortcuts, I think there are a few small tweaks that make them even better. Go like these ideas and add your support!
- In an expression editor (formula/filter etc), you can hit the [ symbol and use the engine and user constants. It would be great if they added question constants as well! Then you wouldn’t need the weird percentile syntax in these cases, and you could use them just like normal data [Question.ToolName] taking advantage of intellisense/autocomplete. This would be huge! https://community.alteryx.com/t5/Alteryx-Designer-Ideas/Let-Question-Constants-be-used-like-Engine-a...
- It doesn’t make sense that the tool name is one spot (the tool’s annotation tab) but the test value is in another (the workflow’s configuration tab). The Name and test value should be together! So the tool’s annotation should let you put a test value (ie just add a box below the name box to capture the test value) and the configuration tab should let you rename tools. The configuration tab is a funny one because it actually lets you type in a new name for question tools, but as soon as you click off and then click back on, your new name reverts back to the original name. https://community.alteryx.com/t5/Alteryx-Designer-Ideas/2-small-changes-to-make-working-with-Interfa...
Do you have any more examples?
If you’re looking for more examples, check out my responses on these challenges:
Challenge 77. I used a reference shortcut in the trade area tool:
Challenge 252. I used a couple reference shortcuts in the generate rows:
