Alteryx Designer Desktop Knowledge Base
Definitive answers from Designer Desktop experts.Getting Started with Iterative Macros
How to get started with using Iterative Macros
If you are new to working with macros in Designer, a good place to begin is with this article: Standard Macros. It covers the basics of working with macro inputs, configuring variables that can be updated by the user, adding a macro to a workflow, and saving a macro on a Designer Toolbar.
For some fun and interesting ways to conceptually understand the differences between Standard, Batch, and Iterative Macros, I suggest these articles from the Macro Maynia Blog series:
This article will help you get started with using Iterative Macros. There are examples, recorded training sessions, and other articles to further your knowledge listed in the Common Issues and Additional Resources sections.
An iterative macro is a process that runs a specified number of times or until a defined condition is met. This type of macro adds a global workflow variable called IterationNumber. This variable is useful in workflow functions, it increments by 1 each time the macro runs. An Iterative Macro is similar to an SQL or Python while statement, in that the macro continues to run while a condition remains true.
An iterative macro is useful when processing records in a specific order, such as by priority or spatial distance. You can implement functions so that only records with a priority number matching the iteration number process on any run of the macro (for example, priority 1 records for the first run of the macro, followed by priority 2 records next, and so on). Similarly, you could determine a driving route by selecting the nearest destination to the last starting point on each iteration, creating a specific sequence.
Iterative macros can be helpful after grouping your data into numeric sets. For example, the Multi-Field Binning Tool or Tile Tool could be used to create subsets of your data with the records in each subset having the same number. Afterward, the iterative macro would run only the group of records with the tile or bin number matching the iteration number, and the macro would run one time for each group number until all the groups are completed.
Here is an example of an iterative macro that assigns items from warehouse stock to retail stores based on the store’s priority. If the comments are too small, try holding down the Ctrl key and click on the plus key or scroll up with the mouse wheel to zoom in (minus key or scroll down to reverse the effect).
This macro will loop until all stores are processed, or the maximum number of iterations set on the Interface Designer Properties tab is met. Keep in mind that an iterative macro needs a true/false test. In this case, the macro will keep looping as long as the test of an existing record with a priority matching the iteration number is true. As soon as no more records have a priority matching the iteration number, the macro will stop sending records out of the iteration output, and the macro will stop running.
Tip: It is helpful to use the Output Name field in the Macro Output Configuration screen. Add a name for the output that will iterate back through the macro.
Afterward, you can easily pick the correct output on the Interface Designer screen. You can also set the maximum number of iterations, the action to occur when the maximum reached, and the Output Mode. For best practices, you should keep the maximum number of iterations as low as possible. If there are more iterations than expected, it may be time to check the logic in the macro.
Common Issues
You may need some sample workflows with macros to help you get started. Sample macros for different use cases are available in Designer by going to Help, Sample Workflows, Use scripting and automation tools, and Build a Macro. When viewing the workflow, right-click on the macro tool, and then select the option to Open Macro. This will open the macro workflow packaged for that tool on a separate tab.
Also, there are recorded training sessions for macros available on the Community website here: Recorded live training label: Macros.
Additional Resources
Iterative Macro: Collatz Conjecture Example
CS Macro Dev: Iterative Macros
