Loops
Perform actions on each item in a list
Loops are great if you want to run a number of building blocks for each item in a list.
This can be useful if you are loading all rows from worksheet and want to generate a document per row.
You could also load all contacts from a contact group in your Google address book and send out a personalized email to each contact.
You can loop over any list, no matter if you have loaded records from an Airtable base or if you have received data from a webhook or pass a list of items to your flow from your own application when running Ultradox.
Once you get a hang on how you can perform actions for each item in a list it will be a powerful tool when creating automations.
Example
As an example we want to generate a personalized PDF voucher for each of our customers and send it to them as an attachment by email.
This is how the resulting automation looks like:
|
|||||
|
|
|
||||
|
|
|
||||
|
|||||
|
|
|
||||
|
|
|
||||
|
|||||
|
|
||||
|
|||||
|
|
||||
|
|
|
||||
|
|
||||
|
|||
Explanation
To understand how loops work in Ultradox, let us go through each of these blocks to see what each of them is doing.
|
|||||
|
|
|
||||
|
|
|
||||
The first block will load all rows from the Customers worksheet. In this example the Customers worksheet should just have two columns: name and email.
In the output section of the building block you will find two variables rows[].name and rows[].email.
What does this mean?
It means that we have loaded a list of rows, each containing the name and the email of a single customer.
We could now go ahead and generate a single document with a list of all our customers. But this is not what we want. In our example we want to generate a dedicated document for each customer.
This can be achieved by adding a Repeat block to the flow.
The easiest way to add repeat block is to click on the repeat icon in the output section of the block that loads the rows. You will find such an output action in each block that loads a list of items.
When clicking on the icon the rows[] list will be preselected and the repeat block and the matching continue block will be added to your flow.
|
|||||
|
|
|
||||
|
|
|
||||
|
|||
As you can see the repeat block provides the simple variables name and email.
You can now go ahead and put whatever actions you want to perform on each item in the list between the repeat and the continue blocks.
As we want to generate a PDF document for each item, we drag the Google Docs to PDF block from the sidebar and drop it right after the repeat block.
Pick an existing template or create a new one and open the Ultradox Template Editor add-on that greatly helps you to insert variables into the template.
When working on the template you can simply use the ${name} variable in the template to merge the name of the customer into the document.
|
|||||
|
|
||||
All variables that you have used in your template will show up after in the input section of the building block. In our example the name variable will show up as input of the building block generating the PDF document. The icon on the right of the variable indicates that the value will be taken from the repeat block.
Let's now add the missing step that sends the generated document as an attachment to the customer.
You'll find a suggested output action for generating an email block in the output section.
Use the suggested output actions whenever possible as building blocks added using the suggested actions will come with the correct configuration. When adding them from the sidebar you'll have to take care of the configuration by yourself.
Click on any of the bold parts in the title of the email building block to enter the subject and rename the attachment by clicking on the name of the attachment.
Enter ${email} into the to field of the email dialog. As the variable email will be replaced with the email of the current customer an email will then be sent to each customer.
|
|||||
|
|
||||
|
|
|
||||
|
|
||||
Congratulations! You should have a basic understanding how to create loops with Ultradox.
Pagination
If you are dealing with large lists that contain a huge amount of items, you should avoid to load the full list at once by any means.
Most of the building blocks that provide lists like loading all rows in a worksheet or loading contacts are smart enough to load just a limited number of items at once.
If you are working with additional building blocks that you have added using the Add more menu, you will have to take care of pagination by yourself.
You can do so by populating the nextPage variable before the end of the loop.
Once the last item of the list has been reached the nextPage variable will be used to populate additional variables that will be passed to the building block that loads the data.
If you are for example working with the stripe API you can pass a variable called starting_after when loading lists.
You can encode multiple parameters in the nextPage in the same way as a query string of an URL is constructed.
To pass the id of the current item of the list to the starting_after variable, we can populate the nextPage variable with this template:
starting_after=${id} When reaching the last item in the list, the nextPage variable will be parsed and the startig_after variable will get extracted and provided to the building block loading items from stripe.
Advanced configuration
After reaching the last item in a loaded sublist Ultradox will invoke the first building block before the repeat start by default.
If you have added some more building blocks after the block loading the data and before the start of the repeat, you'll have to pass the ID of the building block to the nextPage variable to tell Ultradox which building block to run to load more items.
You can do that by putting the ID of the building block at the beginning of the nextPage variable and separate it from the parameters with a colon:
[buildingBlockId]:starting_after=${id}&another_variable=${myvar}
Questions and Feedback
If you have any comments on this page, feel free to add suggestions right to the Google document that we are using to create this site.
If you are not yet member of the Ultradox community on Google+, please join now to get updates from our end or to provide feedback, bug reports or discuss with other users.
Last Updated: 5/5/19