Engine Works
Under the hood of Alteryx: tips, tricks and how-tos.
If you’re one of those people who develops all your macros flawlessly the first time, congratulations: you don’t need the X-Ray Browse Macro. (And we’d love to get your resume.) This macro is designed for the rest of us: humans.
The X-Ray Browse Macro is an Alteryx macro debugging tool, and if you develop a lot of macros, it will undoubtedly save you time, and perhaps even your sanity: after we circulated a beta version of the X-Ray, one of our Content Engineers--deep into development of an extremely complex macro--reported: “I was at my wit’s end with this thing and then remembered the X-ray macro, dropped a few in, and immediately had my answer. So glad this thing exists 🙂 ”
What does it do?
The X-Ray Browse’s main function is the same as that of the regular Browse tool: display the data you want to see, when you want to see it. To illustrate, here’s a side-by-side view of the Browse tool and the X-Ray Browse macro, each displaying just 2 rows and columns of data. The Browse tool presents the data in the Properties window; the X-Ray Browse Macro presents the data in the Output window.
The Browse tool is arguably Alteryx’s most powerful workflow debugging tool, so of course we use Browses when we develop macros: a macro is first and foremost a workflow. However, the power and purpose of a macro is that you can call a macro from within another workflow, and that power comes at a cost: when you call a macro from another workflow, you cannot see the Browses inside said macro. The X-Ray Browse overcomes that limitation: it will display the data flowing inside your called-upon macro—your selected columns and rows—printed to the Alteryx output window as the gold-text warning—and frequently meaningless--messages you may have grown accustomed to ignoring. But this time you’ll want to read these warnings—you asked for them!
How do you use it?
In a nutshell, easily:
You take a macro you’re working on, slap an X-Ray onto the macro’s internal workflow canvas wherever you’d like to “browse”, make a couple simple settings and presto!
Out of the nutshell:
Here’s an example of using the X-Ray macro to solve a bug in the “Exponentiator macro”. The simple Expo macro just asks for a number, and returns a listing of all the powers of 2 up to that number entered. It functions just fine when run as a workflow, so it’s ready for real-world macro testing: calling it from within another workflow.
To follow along with the demo—and to get your copy of the X-Ray macro itself—download and save the “DemoTheXRayMacro_XRayTheExponentiator.yxzp” somewhere on your computer. Then import the .yxzp, and run “DemoTheXRayMacro_XRayTheExponentiator.yxmd.” (You may get an error if you try to import the yxzp without first saving it to your machine.)
In the demo workflow, you see we entered 20 into the Expo macro, so we’d expect it to generate 1-2-4-8-16, but what do we see in the Browse attached to the Expo output? Just 1-2-4. Where are 8 & 16?
Let’s watch the X-Ray get us out of this jam.
To resolve the bug, I went back into the internals of the Expo macro and inserted X-Rays into it. As you can see in the screenshot, I inserted them—not coincidentally--into the same 3 places that I had previously put regular Browse tools when I was originally creating the Expo as a workflow.
Then I did the simple configuration on each X-Ray. Here’s the first one:
Basically all I did was name the location where I inserted the X-Ray, and set which columns I want to view and how many rows thereof. (The helpdoc details all the configuration options—as well as some important caveats—so make sure you check that out.)
Thanks to the Alteryx “Message” tool used inside the X-Ray macro, here’s what we see in the output window for the first X-Ray:
The “Location” name tells me where within the macro I’m X-Raying, so I can see that the 8 & 16 were present in the data stream after the GenerateRows1 tool. So far so good.
Looking further down the output window, I see the output from the 3rd X-Ray:
As labeled, this X-Ray is showing the data from the false side of the Filter9 tool, and there we see it in gold-and-white: it’s the Filter tool that’s throwing out the 8 & 16 values. Knowing that they’re not filtered out when run as a workflow leads me to suspect an issue with the interface tools. Interface tools in macros—and apps for that matter--are not triggered when they are run directly as workflows, so I investigate the interface tools attached to that Filter tool, and find an Action tool reconfiguring the Filter to remove any values greater than 5 at macro runtime. Seeing no worldly reason for that Action tool, I delete it, achieving macro bliss: the Expo macro now works perfectly. Thanks X-Ray.
Rarely will your macros be as simple as the 4-tool Expo macro. Sometimes you’ll have a hundred+ tools. Sometimes you’ll be doing batch or iterative macros. These situations can be challenging to say the least. That’s when the X-Ray will really shine, and that’s also when you may benefit from the final, optional feature of the X-Ray Browse: the X-Ray Files option.
With just a tick in the optional “Output X-Ray files” checkbox, the X-Ray will generate yxdb files containing the entire data stream at that point in the macro (into an “X-RayFiles” subfolder the macro automatically generates). With the X-Ray files, you can analyze complete data streams—all columns and all rows—not just the ones selected in the row and column configuration. Furthermore, selecting the “Timestamp X-Ray files” option ensures previous X-Ray files are not overwritten. Timestamping is very handy for comparing data streams before and after making a change to your macro, and is particularly handy for batch and iterative macros so you get a file for every iteration. (Again, the helpdoc gives all the details.)
So next time you hit a hiccup with a macro, and you wish you could Browse inside of it at runtime, you can: X-Ray Browse it.
PLEASE use comment section below and TELL US WHAT YOU THINK!
