Sometimes in your recipes you will want to include data about a user or post, and that data may be different for each recipe run. Perhaps there’s a recipe where you want to run it for multiple users, and in the recipe there’s an action to send an email to the user and you want to address the user by their first name. These dynamic pieces of data inside recipes are called “tokens” and can be included in any recipe action.
Types of tokens
Uncanny Automator offers 3 types of tokens for use in recipes:
- Universal tokens: These tokens are always available in every recipe, and might be used to pass in information about a user, a post, a date, etc.
- Trigger tokens: When a trigger is added to a recipe, available tokens specific to that trigger are added to the list of available tokens. When you submit a form, retrieving the value in the second field would be a “trigger” token type.
- Action tokens: When an action is added to a recipe, tokens associated with its output become available to actions that run after it. An example would be having an action that creates a post pass the new post ID to another action.
Using tokens in recipes
Any time there’s an opportunity to use a token in a field, you will see an asterisk (*) icon to the right of that field. By clicking that icon, a menu will expand showing you available tokens. The token system looks like this:
At the top of the list are the Universal tokens that appear in every recipe. The Triggers and Actions sections below will be displayed if there are tokens available for the triggers and/or actions in the recipe. Use the icons on the right side of the token type to expand that section and show all available tokens.
To add a token to an action field, simply select it. Doing so will add then token to your action, in plain English, with special styling to indicate that it’s a token. Support that the recipe is associated with a user and we want to include First and Last names in a field (both “Common” tokens); the field in the recipe would show the following:
The icons inside the grey pill area show the integration icon, if applicable. The title shown is a descriptive label for the token. In this example, if it were sending an email to the associated user during a recipe run and this were the subject, the user would receive an email with their first and last name as the subject.
In some cases, certain tokens will require additional information. If you want to return data for a specific post meta key, for example, you need to tell Automator which post to target (by ID) and which meta key to return data for. When a token requires additional information, it will show an additional modal, like this:
You will even see on the right that passing in a post ID and meta key can be done using tokens (as shown by the * on the right), so it really is possible to use dynamic data anywhere. In this example, maybe I want to return the “organization” meta key value for a certain page linked to a trigger. The token would end up looking like this:
This new token example shows that the post ID is passed in automatically from the trigger (it’s a WordPress trigger, hence the icon) and the meta key of “organization” is hard coded, since that key will apply to all recipe runs.
Universal tokens
Universal tokens include any tokens that are available for use in any action that can accept tokens. Within this category are several important token types:
- Common: These are simply token types that can be used to retrieve and use data about the user, site or recipe. Examples of tokens in this type a user’s first name, a password reset link, the site URL, etc.
- Date: To use the WordPress date, time, or even Unix timestamp, use the tokens in this section.
- Advanced: These are typically more complex tokens, like working with user and post meta records directly.
- Modifiers: Tokens in this section let you manipulate data, like running a calculation on a meta value to increment it by 1.
Trigger tokens
It’s very typical to use values that are captured in a trigger later in the actions. Suppose you submit a form that needs to create a user, and the form entry includes information about the user that will be used to create the account. You would use trigger tokens to populate the user information inside actions and the user selector.
Trigger tokens are unique to each trigger. If you’re having trouble finding what you need in a specific trigger, perhaps a similar trigger has more appropriate tokens.
Tip: Did you know that you can see a list of every single available token on our website? Simply visit any integration page on our website (e.g. https://automatorplugin.com/integration/woocommerce/) and look for the + icon next to the trigger. Click that to expand the list of available tokens, like this:
Action tokens
Sometimes you may need to pass data from one action to another action that runs later in the recipe. An example that uses this token type would be a recipe that creates a new post and then tweets about the new post after a form is submitted. In other to send the tweet, the action needs the URL for the new post so that it can include a link to it. That’s the power of action tokens.
Not all actions support passing data via tokens, and these token types are most application when things are created, like orders, pages, users and form entries. To see a list of available action tokens, make sure you add the action that will pass data to another action first. In many cases, it will make sense to add a small delay to the action that needs data to make sure that the action creating the object is complete.
Once the required actions have been added, open up the token list for the action receiving data and look for the new Actions token section. Choose the appropriate token(s) from the list to include them in your recipe.
