Token Loops

Introduction

Token Loops allow you to iterate over multiple items in loopable tokens, a new type of token that contains information about one or more items. If you’re familiar with User Loops or Post Loops, Token Loops work in an almost identical way, except they loop through items in the supplied token.  You can use Token Loops with any paid Automator license.

Here are a few examples of recipes you could run with token loops and a few plugins like WooCommerce, LearnDash and BuddyBoss:

• Export all orders in the past 24 hours, week, 30 days or year to a Google Sheet or Airtable.
• When a user purchases a product, loop through all of their previously purchased products and email them a special coupon code if they’ve qualified for a multi-product promotion.
• When a user purchases a product, loop through all of their previously purchased products and send out supplementary information on how to use complementary products together.
• When a user purchases a product, loop through the categories assigned to those products and award an achievement for purchases in specific categories.
• When a user purchases a product, loop through their enrolled courses and complete them or reset their progress.
• When a user submits a form, add a post to the activity stream of each of their enrolled groups.
• When a user completes a course, loop through their previously completed courses and award a certificate if they’ve completed the required courses.
• When a user subscribes to a product, loop through their active subscriptions and award store credit for specific combinations of active subscriptions.

Adding a token loop

To add a token loop to your recipe:

1. Scroll to the Actions section of the recipe.
2. Click Add.
3. Click Token loop.

This adds an empty loop to your recipe. Next, select the loopable token that contains the desired data. Only special loopable tokens will appear in the token selector of a token loop.

Loop filters

Actions will be run on every item in the loopable token that meets your loop filter. Adding loop filters makes loops run more efficiently, so if you can narrow your post targets with filters, you should. The default loop filter is that the current item is not empty. Additional filters will be added over time.

Adding actions inside a token loop

Actions inside a token loop will be run for each item that meets the loop’s filter criteria.

The type of action you want to run will depend on the items in the token.  Are they products? Courses? Groups? If you are iterating over courses, you may want to run a Reset course progress action. If they’re products, maybe you want to check if the user purchased a specific product in the past and if so, send an email.

In most cases, you’ll need some information about the items in the loop. To get that information, you’ll use loop tokens.

In the Loop token category you will find key tokens related to the items you’re iterating. If you’re iterating over products, you’ll find things like the Product ID, Product Name, etc. For courses, the Course ID, Course Name, etc.  Here’s what that might look like:

Suppose you have a recipe that fires when a user purchases an online Introduction to Marketing course. You could loop over the user’s previously purchased products, and if they previously purchased a complementary course, like Introduction to Sales, send them an email letting them know about a Sales and Marketing group they might want to join.  Or add them to the group directly. Or, perhaps you’re running a promotion if a user purchases both of those courses, but you want to offer it even if they’re not purchased in the same transaction. Here’s what that recipe might look like:

Triggering the loop

To run the bulk actions inside a loop, you need to trigger the recipe. Most of the time, you’ll want to use a regular trigger to run the recipe containing the loop. For some semi-automated workflows, you may want to use the Run now trigger to run token loops right from inside the recipe page.

Monitoring the progress of a loop

Once the recipe containing the token loop has been triggered, you can monitor the progress of the loop from Automator > Logs and view results in the easy-to-read, detailed logs.

Cancelling a loop

A cancel button lets you cancel a loop in progress.  Loops are processed in batches (see Things to know, below) that are automatically sized to adapt to your specific server’s hardware. Cancelling a loop in progress will cancel batches that have not started yet; however the in-progress batch will continue to execute until it is completed.

Viewing loop results

Once the loop has completed, you can expand the log to see the result of each action on each item in the loop. This gives you very detailed information about actions that experienced an error so you can easily trace any issues.

Important Notes

1. There is no way to undo the actions that were executed in a loop, so be 100% sure your loop is correct before running. Consider testing on a staging site prior to running an extensive loop on your live site.
2. When running loops with app actions (such as Google Sheets), you may run into rate limitations on the receiving side, which will cause actions to fail. While very rare, extremely large batches should in some cases be divided up.

Under the Hood

1. Loops run as background processes. Loops are designed to be as efficient as possible and should not result in a performance hit to the front end of your site.
2. Since loops run in the background, actions not in a loop will typically complete before the loop. If you want an action in a recipe to run after a loop completes, the only way to do that is to manually specify a delay for the action.
3. Loops are executed in batches. The size and frequencies of these batches automatically adapt to your server’s capabilities and cannot be adjusted manually.
4. You can stop a loop that’s in progress from the logs. However, an in-progress batch cannot by halted and will run to completion. Any batches not yet started will be cancelled.
5. How long a loop takes to complete will depend on many factors, including:
   • The number of items the loop iterates over
   • The number of filters inside the loop
   • The number of actions inside the loop
   • The type of actions inside the loop (some actions are slower than others)
   • The capabilities of the server hosting the site