Automation Configurator
Automatically execute a GraphQL Persisted Query when some event happens on the site.
The Automation Configurator module provides an "automator" user interface, to create automations via the WordPress editor.
The automation trigger is any WordPress action hook, and the action is the execution of a GraphQL persisted query.
A Custom Post Type "Automation Rules" is provided to create automations. When creating a new entry, we must provide the configuration for:
- Automation trigger(s)
- Automation action
Automation action
The automation action indicates what GraphQL persisted query will be executed.
Configure this item with the following elements:
Persisted Query: Select which GraphQL persisted query to execute (among all the ones with status publish or private)
Static GraphQL Variables: Provide a JSON string with values for the GraphQL variables in the persisted query. These are static values.
For instance:
{
"emailSubject": "New post on the site"
}These values are overridden by the "dynamic" GraphQL variables (see Automation trigger(s) below).
Operation name (optional): If the persisted query contains more than one operation, you can indicate which one to execute (by default, it is the last one).
Execute as user (optional): Execute the GraphQL persisted query being logged-in as a specific user, providing the user slug.
Automation trigger(s)
An automation trigger indicates what WordPress action hook will trigger the execution of the Persisted Query. We can provide more than one (eg: to react to editing a post or page only, we can provide hooks edit_post_post and edit_post_page).
Configure this item with the following elements:
Hook name: The WordPress action hook name.
Dynamic GraphQL Variables: Provide a JSON string mapping GraphQL variables to the arguments provided to the hook function. These dynamic values will then be provided to the query on runtime.
The JSON dictionary must contain the GraphQL variable name as key, and the position of the argument in the action hook as value.
For instance, hook draft_post (from the post status transitions) provides the $post_id as the first argument. Then, the following JSON indicates that GraphQL variable $postID will receive the value of $post_id passed to the hook:
{
"postID": 1
}(In this example, 1 means "value of the 1st argument by draft_post".)
If the same key is used for the "dynamic" and "static" GraphQL variables (see Automation action above), then the dynamic values take priority.
WordPress hook mapping
There are WordPress hooks which cannot be directly used in the Automation Configurator, because they provide a PHP object via the hook, which can't be input as a GraphQL variable.
Several of these hooks have been mapped by Gato GraphQL, by triggering a new hook prepended with gatographql: and the same hook name, and passing the corresponding object ID as a variable, which can be input as a GraphQL variable.
For instance, WordPress hook draft_to_publish passes the $post as variable (of type WP_Post). Gato GraphQL maps this hook as gatographql:draft_to_publish, and passes the $postId (of type int) as variable.
The following table lists down the mapped WordPress hooks:
| WordPress hook | Mapped hook by Gato GraphQL |
|---|---|
{$old_status}_to_{$new_status} (passing WP_Post $post) | gatographql:{$old_status}_to_{$new_status} (passing int $postId, string $postType) |
In addition, Gato GraphQL re-triggers several WordPress hooks with some extra information on the hook name, to make it easier to capture and automate specific events.
For instance, hooks that create, update and delete meta values are triggered containing the meta key as part of the hook name. Then, an automation can be triggered when a featured image is assigned to a post, on hook gatographql:added_post_meta:_thumbnail_id.
These are the additional Gato GraphQL hooks:
| Source WordPress hook | Triggered Gato GraphQL hook |
|---|---|
{$old_status}_to_{$new_status}(Passing WP_Post $post) | gatographql:any_to_{$new_status}gatographql:{$old_status}_to_anygatographql:{$old_status}_to_{$new_status}:{$post_type}gatographql:any_to_{$new_status}:{$post_type}gatographql:{$old_status}_to_any:{$post_type}(All passing int $postId, string $postType) |
created_term | gatographql:created_term:{$taxonomy} |
set_object_terms | gatographql:set_object_terms:{$taxonomy}gatographql:updated_object_terms:{$taxonomy} (When there is a delta between old and new terms) |
added_post_meta | gatographql:added_post_meta:{$meta_key}gatographql:added_post_meta:{$post_type}:{$meta_key} (Also passing string $post_type as 5th param) |
updated_post_meta | gatographql:updated_post_meta:{$meta_key}gatographql:updated_post_meta:{$post_type}:{$meta_key} (Also passing string $post_type as 5th param) |
deleted_post_meta | gatographql:deleted_post_meta:{$meta_key}gatographql:deleted_post_meta:{$post_type}:{$meta_key} (Also passing string $post_type as 5th param) |
added_term_meta | gatographql:added_term_meta:{$meta_key}gatographql:added_term_meta:{$taxonomy}:{$meta_key} (Also passing string $taxonomy as 5th param) |
updated_term_meta | gatographql:updated_term_meta:{$meta_key}gatographql:updated_term_meta:{$taxonomy}:{$meta_key} (Also passing string $taxonomy as 5th param) |
deleted_term_meta | gatographql:deleted_term_meta:{$meta_key}gatographql:deleted_term_meta:{$taxonomy}:{$meta_key} (Also passing string $taxonomy as 5th param) |
Debugging issues
If the automation hasn't been executed, there could be an error with the configuration of the automation, or execution of the persisted query.
Error logs
All configuration problems (such as a malformed JSON string for the GraphQL variables, or pointing to a persisted query that has been deleted) and execution errors (such as thrown exceptions, or errors entries in the GraphQL query) are sent to PHP function's error_log, so these are printed in the WordPress error log.
These error logs are prepended with string [Gato GraphQL].
Info logs
The complete GraphQL response for the automation (whether successful or not) is logged under file wp-content/gatographql/logs/info.log.
To print these logs, option Enable Logs? in Settings > Plugin Configuration > General must be selected:
Examples
These are some examples of how we can use it:
- Create a featured image for new posts using AI
- Add a mandatory block to the post when published
- Replace
httpwithhttpsin all image sources and links when a post is updated - Send an email to the admin when there's a new post
- Send an email to the user whose comment has a new response
- [Multisite] Translate a new post to different languages, and add the translated posts to each site
- Execute an action on an external service (eg: automatically share new posts on Facebook)
For instance, when creating a new post with draft status, the predefined automation rule Add comments block to new post checks if the core/comments block is present and, if not, it adds it at the bottom of the post:
