skip to Main Content

How to create a simple Automator action

Custom Triggers & Actions
1. How to create your own integration with Automator
2. How to create your own trigger with Automator
3. Comparison between 2.x and 3.x Automator code
4. How to create a simple trigger with Automator
5. How to create a simple Automator action

Difficulty: Easy

Creating an action with Automator 3.0 is a lot easier than you might think. To get started, you can download working sample from our Github repository.

A step by step guide to create a simple Show a message on a page action with Automator 3.0+:

Start by creating a new plugin in your dev environment and define your plugin file:

<?php // phpcs:ignore WordPress.Files.FileName.InvalidClassFileName

/**
 * @wordpress-plugin
 * Plugin Name:       Your plugin name
 * Plugin URI:        Your plugin URI
 * Description:       Your plugin description
 * Version:           1.0.0
 * Author:            Author
 * Author URI:        Author URI
 * License:           GPL-3.0+
 * License URI:       http://www.gnu.org/licenses/gpl-3.0.txt
 */

After defining your plugin, use automator_add_action() to add your action in Automator’s active actions as:

function load_my_custom_action() {
	// Let's find integration by name so that action can be added to it's list.
	$add_to_integration = automator_get_integration_by_name( 'Uncanny Automator' );
	if ( empty( $add_to_integration ) ) {
		return null;
	}
    // Add a php action file in the same folder and name it uoa-shownotice.php
	$action = __DIR__ . '/uoa-shownotice.php';
	automator_add_action( $action, $add_to_integration );
}

add_action( 'automator_configuration_complete', 'load_my_custom_action' );

Once the action is defined, you will now create a file in plugin folder (if not created yet) and name it uoa-shownotice.php.

Automator usually uses integration’s shortcode as the prefix of the file and class name, i.e., uoa is the shortcode of Uncanny Automator integration and shownotice is somewhat meaningful name of the action’s functionality. The classname from filename uoa-shownotice.php will become UOA_SHOWNOTICE.

Now in your action file, start by adding use Uncanny_Automator\Recipe namespace. Declare your class.

<?php

use Uncanny_Automator\Recipe;

class UOA_SHOWNOTICE {
}

Automator 3.0 uses PHP’s Traits to implement consistent code across all integration files. Add use Recipe\Actions inside your class as:

<?php

use Uncanny_Automator\Recipe;

/**
 * Class UOA_SHOWNOTICE
 */
class UOA_SHOWNOTICE {
	use Recipe\Actions;

}

As soon as use Recipe\Actions is added, your IDE should throw a notice that there are few abstract functions that are required to be added in to the file. These function are mandatory to run your action and has to be added in the file. Your site will also throw a Fatal error if not added. These functions are:

protected function setup_action(){}     // Is used to declare action
protected function process_action(){}   // Is used to process the action 

You will now add placeholder functions like:

<?php

use Uncanny_Automator\Recipe;

/**
 * Class UOA_SHOWNOTICE
 */
class UOA_SHOWNOTICE {
	use Recipe\Actions;

	protected function setup_action() {
	}

    protected function process_action() {
    }
}

Once you are done adding placeholder functions, next step is to actually setup_action() so that it’s added in Automator’s Recipe UI. To do that, add __construct() and call setup_action().

<?php

use Uncanny_Automator\Recipe;

/**
 * Class UOA_SHOWNOTICE
 */
class UOA_SHOWNOTICE {
	use Recipe\Actions;

    public function __construct() {
		$this->setup_action();
	}

	protected function setup_action() {
	}

	protected function process_action() {
    }

}

You will use following functions in order to define an action:

$this->set_integration(); // Display this action under specific integration 

$this->set_action_code(); // Unique action code

$this->set_action_meta(); // Re-useable meta, selectable value in blue boxes

$this->set_sentence(); // Sentence to appear when action is added.

$this->set_readable_sentence(); // Non-active state sentence to show

$this->set_options(); // Adding options so that Automator could display it in Recipe UI 

$this->register_action(); // Registering this action

To get the list of all available functions for setup_action(), please refer to Action_Setup developer’s guide here.

Now let’s start to fill values in this action by adding above functions in setup_action():

<?php

use Uncanny_Automator\Recipe;

/**
 * Class UOA_SHOWNOTICE
 */
class UOA_SHOWNOTICE {
	use Recipe\Actions;

    public function __construct() {
		$this->setup_action();
	}

	protected function setup_action() {

		$this->set_integration( 'UOA' ); // Display this action under UOA integration 

		$this-> set_action_code( 'UOASHOWNOTICE' ); // Unique action code

		$this-> set_action_meta( 'SHOWNOTICE' ); // Re-useable meta, selectable value in blue boxes

		$this->set_sentence( sprintf( 'Show a {{message:%1$s}} on a page', $this->get_action_meta() ) ); // Sentence to appear when action is added. {{message:%1$s}} will be presented in blue box as selectable value

		$this->set_readable_sentence( Show a {{message}} on a page ); // Non-active state sentence to show

        // Add a text field and call it "Message". This is then used to show a message to the user. 
		$option = array(
			Automator()->helpers->recipe->field->text(
				array(
					'option_code' => $this->get_action_meta(),
					'label'       => esc_attr__( 'Message', 'uncanny-automator' ),
					'input_type'  => 'text',
				)
			),
		);

		$this->set_options( $options ); // Adding options so that {{a page:%1$s}} could display it in Recipe UI 

		$this->register_action(); // Registering this action
	}

	protected function process_action() {
	}

}

At this point, if all goes well, your action should start to show up in Recipe UI as:

Action in the Recipe UI

Action displaying option

Action once option is selected

The action is technically ready for use on your Automator installation site.

But wait, what happens when this action is called?

This is handled in the following functions that you added before as placeholders:

protected function process_action( int $user_id, array $action_data, int $recipe_id, array $args, $parsed ) {}

By default, all actions are going to call process_action function in your action. Automator passes 5 arguments to this function.

  • $user_id
    • int User ID the fired the recipe
  • $action_data
    • array Action’s available data, for example, action ID, action’s log ID etc
  • $recipe_id
    • int Current recipe ID
  • $args
    • array of all the arguments collected so far by the recipe, including recipe and trigger Ids
  • $parsed
    • array Automator will attempt to parse tokens used in the action automatically but it will still allow you to override it with filters

Next step, as the name suggests, process_action(), you are going to add some code to actually process and complete the action. For this example, assume that the recipe is simplest, a user visits a page -> show an alert on the page with the message. So the process_action will have a basic validation if user is currently on a page using is_page() and based on the outcome of it, either marks complete the action with an error message that “User was not on a page” or go ahead and display an alert on the page.

protected function process_action( int $user_id, array $action_data, int $recipe_id, array $args, $parsed ) {
		$message = isset( $parsed[ $this->get_action_meta() ] ) ? $parsed[ $this->get_action_meta() ] : '';
        // Check if the is currently on a page, instead of post or archive
		if ( ! is_page() ) {
            // User is not on page, mark complete this action with error message as:
			Automator()->complete->action( $user_id, $action_data, $recipe_id, 'User was not on a page' );
		}

        // sanitize the output
		$message = trim( wp_strip_all_tags( $message ) );
		ob_start();
		?>
        <script>
            // show an alert when page loads with the message saved in action
            var t = setTimeout(function () {
                alert('<?php echo esc_html( $message ); ?>');
            }, 1000);
        </script>
		<?php
        // display the message
		echo ob_get_clean();

        // complete this action successfully
		Automator()->complete->action( $user_id, $action_data, $recipe_id );
	}

So the final code of an action file after adding process_action is:

<?php

use Uncanny_Automator\Recipe;

/**
 * Class UOA_SHOWNOTICE
 */
class UOA_SHOWNOTICE {
	use Recipe\Actions;

    public function __construct() {
		$this->setup_action();
	}

	protected function setup_action() {

		$this->set_integration( 'UOA' ); // Display this action under UOA integration 

		$this-> set_action_code( 'UOASHOWNOTICE' ); // Unique action code

		$this-> set_action_meta( 'SHOWNOTICE' ); // Re-useable meta, selectable value in blue boxes

		$this->set_sentence( sprintf( 'Show a {{message:%1$s}} on a page', $this->get_action_meta() ) ); // Sentence to appear when action is added. {{message:%1$s}} will be presented in blue box as selectable value

		$this->set_readable_sentence( Show a {{message}} on a page ); // Non-active state sentence to show

        // Add a text field and call it "Message". This is then used to show a message to the user. 
		$option = array(
			Automator()->helpers->recipe->field->text(
				array(
					'option_code' => $this->get_action_meta(),
					'label'       => esc_attr__( 'Message', 'uncanny-automator' ),
					'input_type'  => 'text',
				)
			),
		);

		$this->set_options( $options ); // Adding options so that {{a page:%1$s}} could display it in Recipe UI 

		$this->register_action(); // Registering this action
	}

	protected function process_action( int $user_id, array $action_data, int $recipe_id, array $args, $parsed ) {
		$message = isset( $parsed[ $this->get_action_meta() ] ) ? $parsed[ $this->get_action_meta() ] : '';
        // Check if the is currently on a page, instead of post or archive
		if ( ! is_page() ) {
            // User is not on page, mark complete this action with error message as:
			Automator()->complete->action( $user_id, $action_data, $recipe_id, 'User was not on a page' );
		}

        // sanitize the output
		$message = trim( wp_strip_all_tags( $message ) );
		ob_start();
		?>
        <script>
            // show an alert when page loads with the message saved in action
            var t = setTimeout(function () {
                alert('<?php echo esc_html( $message ); ?>');
            }, 1000);
        </script>
		<?php
        // display the message
		echo ob_get_clean();

        // complete this action successfully
		Automator()->complete->action( $user_id, $action_data, $recipe_id );
	}

}

Once the recipe is fired and action is called successfully, you are going to see an alert on the page:

Your action is now ready to be used in a recipe.

Back To Top