We have extended our Early Bird Tickets for Inspire 2023! Discounted pricing goes until February 24th. Save your spot!

Alteryx Designer Knowledge Base

Definitive answers from Designer 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:


Macro Maynia: Knitting

Macro Maynia: Loads of Fun

Macro Maynia: A Piece of Cake


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.


EricWe_3-1574774616337.png EricWe_4-1574774616340.png


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


Tool Mastery Apps and Macros

Batch Macro Help Page

CS Macro Dev: Batch Macros

Getting Started With Iterative Macros

CS Macro Dev: Iterative Macros


5 - Atom


5 - Atom


5 - Atom

Good one


8 - Asteroid

i don't know Macro and batch,should i start learning here or should i learn batch file and macros from other location.
Can i get any suggestion!


Hi @subhajits11


The Macro Maynia posts linked near the top of this article are a fun and easy way to conceptually understand the differences between standard, batch, and iterative macros without the technical details. If you are new to macros, that is a good place to start. 


Afterward, I suggest reviewing the article on standard macros for a solid foundation on using macros in Designer. Click the link here: Getting Started with Standard Macros.


8 - Asteroid

Hi @EricWe ,


Perfect.  thanks for your suggestion.I hope this is the right link(https://community.alteryx.com/t5/Engine-Works-Blog/Macro-Maynia-Macros-a-piece-of-cake/ba-p/416835)  you mentioned,If not this please correct me.



Hi @subhajits11


Yes, that's the right link. There are two more articles in that series as well: Loads of Fun and Knitting.

8 - Asteroid

Thanks @EricWe , One more query ,If you could help!"
Do i need macros as a must-for passing Alteryx first(CORE) certification ?


Hi @subhajits11


I somehow missed your last post back in 2020, my apologies. It's been a while since I took that exam and the content may have changed a bit.


The best way to prepare for the Certification Exam is with the Exam Prep Guide available here and with the Certification Prep videos on the Community Learn tab here

6 - Meteoroid

In the macro configuration there must 3 input , 2 for data streams and 1 for control parameter ? I am getting 3 in my case why





Hi @krishcode0 , 


Could you clarify the issue? You should have one input anchor for each of the Macro Input and Control Parameter tools. 




Eric West