Automating tasks [PRO]
Automatically execute a GraphQL Persisted Query when some event happens on the site.
Create automations directly via the WordPress editor. The automation trigger is any WordPress action hook, and the action is the execution of a GraphQL persisted query.
Accessing all automation rules
Clicking on "Automation Rules" on the plugin's menu, it displays the list of all the created automation rules:
Creating a new automation rule
Click on the "Add New Automation Rule" to add a new entry.
In the editor screen, 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:
