The X-Ray Macro

{Icon} About the X-Ray Macro

The X-Ray Macro is a tool designed to help with developing and debugging macros. It enables you to take a macro that you are developing, pick a location within that macro where you want to view the data passing through, pick the columns you’re interested in viewing, and have that data be displayed as warning messages in the Alteryx output window.

The net effect is like attaching a Browse into a macro, and then being able to see the contents of that Browse tool revealed in the output window at runtime, even though the macro is not being run directly but rather it is being called by a secondary workflow. You can "browse" the data flowing inside the macro even though you are not running the macro workflow directly, and thereby gain insight into the actual functioning of your macro. The X-Ray Macro can reveal problems in your macro at runtime that typical Browse tools may not be able to reveal during development time.

You can also choose to have data files be automatically output from the selected location within your macro, for subsequent analysis.

Why you would use this tool

You would use the X-Ray Macro any time you are developing a macro and you want to see what’s happening to the data inside the macro during runtime.

Input

The macro accepts any input data stream.

Configuration Properties

Configuration Tab

1. Location name: Enter a name that describes the location at which you are inserting the macro. This name will appear in the output window, and will also be used as part of the file name of the X-Ray output files if that option is chosen. The name helps differentiate the messaging and files for when you use more than one X-Ray Macro inside your macro. Always choose a unique name whenever you insert more than one X-Ray Macro into your macro. See further detail below.
2. Number of data rows to display in output window: Use dropdown to specify the number of data rows that you want displayed in the Alteryx output window, up to a maximum of 20 rows.
3. Select at least 1 column to display: Check the boxes on the list box to select which columns you want to view on the output window.
4. View unknown columns also: Check this box if you also want to view any "unknown" columns on the output window. You should select this option whenever the macro to be tested has any action tools or other dynamic functioning that renames columns. The X-Ray Macro cannot see any dynamically-generated or dynamically-named columns at configuration time so it’s not possible to select these columns in the macro, so you will want to select this option to be able to see these dynamic columns. Selecting this option may reveal columns that you did not even know were present in the runtime data stream.
5. Limit each column in output window to 50 characters: Check this box to restrict columns in the output window message table to 50 characters per column. Because the output window can display only approximately 500 characters per row, this option is checked by default to ensure there is room for more than 1 column to be displayed in the output window. Deselect this option if you need to display more than the first 50 characters in your targeted columns. (It will then display up to 1000 characters.) As a result of this setting, you may see "Conversion Errors" indicating that columns are being truncated. NOTE: this option applies only to the display in the output window; it does not affect the data in the "X-Ray Files," described below.
6. Output X-Ray file(s): Check this option to output complete data files in addition to the output window messaging. See further detail below.
1. Timestamp X-Ray file(s): When this option is selected, the X-Ray files will have a datetime stamp appended to the end of the file name. Select the timestamp option to prevent the overwriting of previous X-Ray files. This option is particularly helpful with batch and iterative macros, to ensure that one file is preserved for each iteration, to be used for analysis and comparison between iterations.

Note:You must save the "TesterWorkFlow" (explained in Use Case Example section) for the X-Ray macro to work. If you have not yet saved the TesterWorkFlow you’ll see an error like "The external program "cmd.exe" returned an error code 1". Simply save the TesterWorkFlow and the error will disappear.

Output

The X-Ray Macro produces 2 outputs:

1. Warning Messages: First, the macro will output a table of the gold-font warning messages to the Alteryx Output window. For each X-Ray Macro you insert into your existing macro, you will see a table of data with the following information:
1. Location: the first warning message displays the location name that you specified on the macro interface.
2. Data table: the output window will then contain a (somewhat rough, see below) table containing the column names followed by the column values for the columns and number of rows selected for X-Raying.
3. See further details below.
4. Example output window table: Here we have a screenshot of the output window containing the results of the X-Ray macro. The 'location name' entered was "AfterFilter9True", and just 1 column was selected for X-Raying--the "powersOf2" column.

   

2. X-Ray Files: The second output of the macro is the optional set of X-Ray files. If the user selected the option to output X-Ray files, then the macro will generate a subdirectory called "X-RayFiles" into the directory where the testing workflow resides. The macro will generate .yxdb files into that X-RayFiles directory, and those files will contain the full set of data that is passing through the macro at the point where the X-Ray Macro is inserted.

To clarify, the 2 different ‘outputs’ will display different data: the warning messages will contain a targeted subset of data with only the selected columns and the number of data rows that are specified in the interface; the X-Ray output yxdb files will contain the entire data stream--all columns and all rows--that appear at that point in the user macro’s data stream.

Output window display details

You will see that the table produced in the output window is somewhat jagged. Because of the variable-width font utilized in the output window, it’s not possible to have the table columns line up perfectly. If you have difficulty tracking which columns are which due to the jagged nature of the columns, then:

• Select fewer columns to X-Ray, or
• Select the option to output X-Ray files and review those instead of the warning messages.

All columns selected for display in the output window are converted to v-string and truncated to a maximum of 50 characters. This conversion and limit is applied only for output window display purposes; data being output to X-Ray files are output as-is, with no conversion of size or data type.

Column limits: The output window has a display limit of approximately 500 characters. Hence, depending on the width of your columns, you will not be able to see the X-Ray results of more than approximately 8-12 columns at a time. We recommend that you not try to X-Ray more than approximately 8-12 columns at a time unless both the column names and column values are narrow enough, and you should test first before running a long process. If you need to X-Ray more than 8-12 columns and you see the warnings getting cut off at the right, there are a couple of ways to overcome this limitation:

• Select the option to output X-Ray files and review those instead of the warning messages, or
• Use 2 X-Ray Macros, splitting up the desired columns between the 2 macros, or
• Copy/paste the contents of the output window to a text editor and you’ll see the full contents of the warning message there.

We recommend that you select the fewest, most important columns for X-Raying, since it makes it easier to view the data in the output window.

Column data-type specifics:

• Blob-type columns cannot be X-Rayed to the output window. If you attempt to X-Ray blob-type columns, you will simply see a note at the bottom of the X-Ray table in the output window listing the blob column names (without any values) that passed through the X-Ray.
• Spatial-type columns are converted to strings stating simply what type of spatial object (point, line, or polygon) that is contained in that cell.

You can ignore any Field Conversion Errors you might see emanating from the X-Ray Macro; the macro purposely truncates long columns, so these “errors” are expected and should be ignored.

Use Case Example

Usage of the X-Ray Macro involves a couple of workflows and folders. Verbiage:

1. "UserMacro": the macro that the user is in the process of developing.
2. "TesterWorkflow": the standard workflow into which the UserMacro has been inserted. The TesterWorkflow exists simply to test the UserMacro.
3. "TesterWorkflowDirectory": the directory in which the TesterWorkflow is saved.

The example user is developing the UserMacro, and is having a challenge with it. The user inserts the X-Ray Macro into the UserMacro, after a Formula tool with tool ID 208, so they enter "AfterFormula208" in the ‘Location name’ text box. They set the macro to display 5 data rows in the output window, selected the columns they’re interested in viewing, and chose the options to output timestamped X-Ray files.

When they run the TesterWorkflow, they see warning messages appear in the output window listing the column names that they’d selected and the values contained in the first 5 rows of the data stream. On the file system, they see that a directory called "X-RayFiles" has been generated inside the TesterWorkflowDirectory, i.e. TesterWorkflowDirectory\X-RayFiles, and in that folder, the user finds a file called "X-RayMacro_AfterFormula208_20140909154256.yxdb". If they reran the tester workflow, they’d see another X-Ray file with a new timestamp, so the first X-Ray file is preserved rather than overwritten.