Community Spring Cleaning week is here! Join your fellow Maveryx in digging through your old posts and marking comments on them as solved. Learn more here!

Engine Works

Under the hood of Alteryx: tips, tricks and how-tos.
patrick_digan
17 - Castor
17 - Castor

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:

 

patrick_digan_0-1648678695284.png

 

Let’s first start with our dropdown tool, specifically the annotation tab:

 

patrick_digan_1-1648678695286.png

 

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:

 

patrick_digan_2-1648678695290.png

 

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:

 

patrick_digan_3-1648678695292.png

 

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:

 

patrick_digan_4-1648678695295.png

 

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:

 

patrick_digan_5-1648678695299.png

 

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.

 

patrick_digan_6-1648678695308.png

 

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:

 

patrick_digan_7-1648678695312.png

 

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:

 

patrick_digan_8-1648678695316.png

 

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:

 

patrick_digan_9-1648678695319.png

 

We can run the workflow like normal and check our browse to see that all of our records have state=IN:

 

patrick_digan_10-1648678695344.png

 

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.

 

patrick_digan_11-1648678695347.png

 

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:

 

patrick_digan_12-1648678695349.png

 

Let’s setup our test values:

 

patrick_digan_13-1648678695353.png

 

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):

 

patrick_digan_14-1648678695355.png

 

Then click Open Debug and open the debug log at the top:

 

patrick_digan_15-1648678695362.png

 

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:

 

patrick_digan_16-1648678695363.png

 

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:

 

patrick_digan_17-1648678695364.png

 

And then replace it entirely with our reference shortcut:

 

patrick_digan_18-1648678695365.png

 

Now let’s have a look at our formula tool:

 

patrick_digan_19-1648678695375.png

 

And the best part about reference shortcuts, we can run the workflow like normal and see that everything is working as expected:

 

patrick_digan_20-1648678695381.png

 

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.

 

patrick_digan_21-1648678695391.png

 

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.

 

patrick_digan_22-1648678695396.png

 

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:

 

patrick_digan_23-1648678695398.png

 

Challenge 252. I used a couple reference shortcuts in the generate rows:

 

patrick_digan_24-1648678695400.png

 

Challenge 215

Challenge 238

 

Comments
mceleavey
17 - Castor
17 - Castor

Oh nice.

 

@TheOC 

@IraWatt 

TheOC
15 - Aurora
15 - Aurora

oOOOoo this is really cool! I did not know about this. Thanks for sharing @patrick_digan @mceleavey 


jacob_kahn
12 - Quasar

80% of my time in Alteryx is Macros and Apps. This is life changing @patrick_digan ! No words. 

Question - now could we use these to interact with detours and containers? Hmmm….

SPetrie
12 - Quasar

This is awesome! Time to go back and see if I can make some of my nastier macros a bit more streamlined. Thanks!

Kenda
16 - Nebula
16 - Nebula

Reference shortcuts make my Alteryx life so much better 💙

Luke_C
17 - Castor

I saw you mention these in a weekly challenge comment a few months back. Haven't used unnecessary action tools since!

rickey0830
8 - Asteroid

This is super helpful. Thank you!

binuacs
20 - Arcturus

very helpful @patrick_digan 

IraWatt
17 - Castor
17 - Castor

That is very cool thanks for the Article

DataNath
17 - Castor

Finally got round to reading this! Awesome article and super instructive. Can't wait to give them a try and reduce Action tool usage. Thanks a bunch!

leonhekkert
8 - Asteroid

@patrick_digan thanks for this nice article. It has helped me already a bunch of times.

 

I have a question though. Do you know whether it is possible to use the reference of, lets say, a check box in the 'update value with formula' part of an action tool that is getting input from a different interface tool?

So the check box determines whether or not the action tool actually acts? :)

patrick_digan
17 - Castor
17 - Castor

@leonhekkert Great question! From my experience, I haven't been able to get it to work in an action tool. I've used condition tools in the past.

leonhekkert
8 - Asteroid

@patrick_digan Can you elaborate a bit on this? What would your setup look like in this situation (checkbox determining whether an action tool that receives input from another interface tool actually acts)?

patrick_digan
17 - Castor
17 - Castor

@leonhekkert Check out the 1 tool example for the condition tool, I think it does a good job of explaining it:

patrick_digan_1-1685705618240.png

 

patrick_digan_0-1685705557995.png

 

Apart from the condition tool, The action tool can have multiple connections on the Q input. So no reference shortcuts in the action tool, but you can connect multiple interface tools and use them in the update value with formula expression editor.

patrick_digan_2-1685705725958.png

 

 

shawnmacnova21
7 - Meteor

I have a macro we use to upload files/data to our internal Data Fabric and would love to use reference shortcuts to make an App that lets a Gallery user update the macro values. Has anyone done something like this? I have having trouble getting the shortcuts to pass to the macro - I can get the input needed from the interface tools and shortcuts. What is the next step?

patrick_digan
17 - Castor
17 - Castor

Hi @shawnmacnova21 ! It depends on what info you're trying to pass to the macro and how flexible the macro setup is. The easiest path is to have your macro just use textboxes to pass the data through to the macro. I've done this for one of my processes. I'm not able to share the workflow/macro, but I can share pictures.

 

The user selects Table1/Table2 in a dropdown in the main workflow. I've called the interface tool Table.

 

image.png

 

Then my macro has a text box where I pass the value:

 

image.png

 

I've named that textbox Table in my macro as well (just to be consistent), and then pass it to an output tool in my macro:

image.png

That's the easiest route. If you have an already made macro that can't be changed, then you'll unfortunately have to use action tools to pass data from the interface tools to your macro. 

 

shawnmacnova21
7 - Meteor

@patrick_digan My macro has a bit of everything, so it might work!

 

How do you pass the user selected value to the macro - is the %Questions.Text2% the default in the macro text box?

patrick_digan
17 - Castor
17 - Castor

@shawnmacnova21 I've found that text boxes in the macro work the easiest. My workflow has its normal interface tools (drop downs, checkboxes etc), and then I pass info to the macro by setting up a textbox interface tool in the macro for each item I need to pass. In my example, My dropdown was called Table in my main workflow, and then I created a textbox interface tool in my macro that I also called Table. Then when I inserted the macro into my workflow, I fed the value %Question.Table% into the macro's question tab. The default value never comes into play. When the workflow is run, it passes the value the user selected from the dropdown to the macro (which uses the value however it wants).