User Loops

Warning!

User Loops are a very powerful automation tool, enabling administrators to create recipes that run actions on multiple users. If you’re not sure about how a loop may affect users on your site, we highly recommend creating and running the recipe on a staging site first. (If your recipe includes an action that sends emails, be sure to disable emails on your staging site prior to running it.) Once run, there’s no way to undo the actions of a user loop.

Introduction

User Loops give your recipes the power of bulk actions. Instead of a recipe’s actions affecting only one user, a loop enables an action (or multiple actions) to run on multiple users that meet some criteria.

This opens up some very powerful automations for site administrators. Here are a few examples:

• Send an email to all users with a specific MemberPress membership
• Enroll all users that purchased a specific Easy Digital Downloads product in a Zoom webinar
• Export a list of all users that completed a LearnDash course to Google Sheets
• Send a coupon code to all users that purchased a specific WooCommerce product
• Add all users with a specific email domain (e.g. @uncannyowl.com) to a BuddyBoss group

With User Loops, Uncanny Automator becomes an even more indispensable tool for WordPress site administrators.

Adding a user loop

To add a user loop to your recipe:

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

This adds an empty loop to your recipe.  It’s time to specify the users to loop over and the actions to run on them.

Targeting the right users

Loop filters

Actions will be run on every user that meets your loop criteria, so it’s critical that you target the correct users inside your loop. The first step is to set up a loop filter.

The default filter is ensures users with the role Administrator are not affected by the actions in the loop. You may set up additional filters to target things like:

• WordPress users with specific email domains (e.g. @gmail.com)
• WordPress users whose usernames or user IDs match a criteria
• WordPress users with specific user meta keys/values
• WordPress users with specific roles

Loop filters reduce the total number of users that loop actions will be run on. You want to add as many filters as you can at this level to improve the performance of the loop.

Action filters

Once you’ve set loop filters, you can then set specific action filters. In this example, we’re targeting users that have completed a specific LearnDash course:

The difference between loop filters and action filters is that loop filters reduce the set of of users that the loop runs against, while action filters check each user in the loop to ensure they meet the filter criteria.

When you’re satisfied that the loop and action filters have targeted the desired set of users, we can add actions to the loop. In this example, we’ll simply be sending the target users an email.

Adding actions and tokens inside loops

Actions inside a user loop will be run on each user that meets the loop’s filter criteria.

To customize the actions for each user, use the tokens available inside the loop. A First name token used outside of a user loop returns the first name of the user who triggered the recipe (or the user selected by the user selector in an Everyone recipe). A First name token inside a user loop returns the first name of each user that is iterated as the loop runs. This is a critical distinction, and is what makes user loops so powerful. A simple example of this is the ability to customize the email being sent to each user in a loop with the user’s first name.

In the screenshot below, we’re ensuring the email action sends an email to each user that meets the loop criteria:

Triggering the loop

To run the bulk actions inside a loop, you need to trigger the recipe. You can use any supported trigger to run the loop, just like a regular recipe. Use Run now trigger to run actions on users in bulk right from inside the recipe page.

Monitoring the progress of a loop

Once the recipe containing the user loop has been triggered, you can monitor the progress of the loop and view results in the easy-to-read, detailed logs.  A recipe with a running loop will show as in progress:

Clicking the Details button will show you the recipe details, including the progress of any running loops:

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 user in the loop. This gives you very detailed information about users that experienced an error or did meet the loop criteria, 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. While user loops are extremely powerful and have the potential to save a lot of time, when used incorrectly they also have the power to make a mess. 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. Consider dividing very large batches 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 significant performance impact to your site. However, as they do use server resources, there is an impact which will vary from server to server.
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 users 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