Alteryx Designer Desktop Knowledge Base
Definitive answers from Designer Desktop experts.Getting Started with Batch Macros
How to get started with using Batch 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 Batch Macros. There are examples, recorded training sessions, and other articles to further your knowledge listed in the Common Issues and Additional Resources sections.
Learning how to configure a control parameter is the most important part of working with batch macros, as the control parameter is the defining part of a batch macro. When adding a Control Parameter Tool to the canvas, the workflow automatically becomes a batch macro.
A batch macro runs one time for each record in the control parameter file. An output is generated each time, and a union of the outputs is created.
A Batch Macro can group data into batches if needed and process one batch at a time. For example, you can have a column of values in the control parameter file that dynamically changes the value used in the macro for each batch that runs.
In the example below, the Control Parameter Tool is used to control the number used as a multiplier in the Formula Tool. The Action Tool is set to replace the placeholder value of 4 as the number used for multiplying with the value coming from the Control Parameter tool.
After saving the macro, and adding it to the workflow, there is an input with an upside-down question mark for each Control Parameter Tool used in the macro.
For this example, the Control Parameter file is on the left. It has a batch column that can be used for grouping and a multiplier column. The input is on the right, and it has a corresponding batch column that matches up for grouping with the Control Parameter file and the Number column that will be multiplied.
When selecting the macro icon in a workflow, there is a Group By tab. If grouping fields are used, a batch macro acts in a similar way as an inner join between the control parameter file and the input file, regarding the number of records affected. A batch macro will, of course, do more than joining columns, but the number of records affected will be the same as an inner join. The value in a control parameter field and the macro processes are applied only to input records that match on the columns selected in the Group By tab.
Each of the 5 batches in the Control Parameter file matches with 2 records in the Text Input file for a total of 10 output records.
When no fields are selected in the Group By tab, the Control Parameter acts in a similar way as an append or Cartesian join to the input data. You can think of it in this way as each record in a control parameter field and the macro processes are applied to each record in the input file. The number of affected records is the same as an append. However, a batch macro is used for more than an append to existing data.
Since there are 5 records in the Control Parameter file and 10 records in the Input, there is a total of 50 output records.
When clicking on the macro icon, there is a Questions tab that allows you to map the input fields from your workflow to the fields in the Macro Input Tool and select a field for each Control Parameter Tool added in the macro.
A batch macro also as a workflow global variable called IterationNumber that corresponds to the number of times a macro has run. This variable can be used in functions to ensure a specified sequence is followed by the macro when processing records. From more information on using the IterationNumber variable see: Iterative Macros.
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
Getting Started With Iterative Macros
CS Macro Dev: Iterative Macros
