Adding a Condition to Uncanny Automator Pro

Let’s add a custom Condition to our integration. We already developed an action that can send emails to users, but what if we want to only send emails to people who work at our company? To achieve this we can add a simple condition that will check if a user’s email address contains a string:

The condition file, class and definition

You can view the complete code of this file here, or you can download the whole sample plugin from our GitHub repository.

Let’s create the conditions folder inside our integration. Then create the user-email-contains-text.php file in it.

In that file, define the new User_Email_Contains_Text class that extends the \Uncanny_Automator_Pro\Action_Condition class:

<?php

class User_Email_Contains_Text extends \Uncanny_Automator_Pro\Action_Condition {

	public function define_condition() {

		// Which integration this condition belongs to
		$this->integration = 'SAMPLE_INTEGRATION';

		// The condition name
		$this->name         = __( 'User email contains text', 'automator-sample' );

		// Condition code
		$this->code         = 'USER_EMAIL_CONTAINS_TEXT';

		// Dynamic name
		$this->dynamic_name = sprintf(
			esc_html__( 'User email contains {{text:%s}}', 'automator-sample' ),
			'TEXT'
		);

		// This particular condition requires a user
		$this->requires_user = true;
	}
}

Override the define_condition method and set the following parameters:

$this->integration – stores the integration code, in our case it’s SAMPLE_INTEGRATION

$this->name – the condition name that will output in the conditions dropdown

$this->code – a unique condition code. IT has to be unique for the integration.

$this->dynamic_name – a string with the placeholder, in our case TEXT that refers to the text field that we will add later. The dynamic name will be used to display a proper condition sentence, once it’s active:

$this->requires_user – this can be omitted if the condition doesn’t require a user or set to true if it does, like in our case, because we need to check the user’s email address.

Instantiating the Condition class

Now let’s get back to uncanny-automator-sample.php file, and add the following line at the end of the sample_integration_load_files function:

// Conditions require Automator Pro installed and active
	if ( class_exists( '\Uncanny_Automator_Pro\Action_Condition' ) ) {
		elog( '\Uncanny_Automator_Pro\Action_Condition exists!' );
		require_once 'conditions/user-email-contains-text.php';
		new User_Email_Contains_Text( $helpers );
	}

Note the we must make sure that the parent \Uncanny_Automator_Pro\Action_Condition class is available, meaning that Automator Pro is installed and active.

Adding fields

Now let’s define the text field that will appear when a condition is added or edited:

	public function fields() {

		return array(
			// The text field
			$this->field->text(
				array(
					'option_code'            => 'TEXT',
					'label'                  => esc_html__( 'Text', 'automator-sample' ),
					'show_label_in_sentence' => true,
					'placeholder'            => esc_html__( 'Text', 'automator-sample' ),
					'input_type'             => 'text',
					'required'               => true,
					'description'            => '',
				)
			)
		);
	}

Override the fields method and output an array of field arrays. You can find the full list of supported fields and helper methods to quickly use them in the src\core\lib\helpers\class-automator-recipe-helpers-field.php file. In this case, we want a simple text field.

Evaluating the condition

The last method we want to override is the evaluate_condition. This method will define if the condition is met or failed.

Since the conditions are attached to Actions, if a condition is met, it has to do nothing to let the action run normally. However, if the condition is not met, the $this->condition_failed( $log_error ); method should be called with a proper error string that will be displayed in the logs:

public function evaluate_condition() {

		// Get the text that users entered in the condition option
		$text = mb_strtolower( $this->get_parsed_option( 'TEXT' ) );

		// Get the WP user object
		// Note that $this->user is not always the current user
        $user_data = get_userdata( $this->user_id );
        
		// Get the user email
        $user_email = mb_strtolower( $user_data->user_email );

		// If the email address doesn't contain the text
		if ( false === strpos( $user_email, $text ) ) {

			// Create any error string
			$log_error = sprintf( __( 'User email "%s" doesn\'t contain "%s"', 'automator-sample' ), $user_email, $text );

			// Pass the error to the condition_failed method
			// This will prevent the action from running
			$this->condition_failed( $log_error );

		}

		// If the condition is met, do nothing and let the action run.
	}

Here we get the TEXT that the user has set when adding the condition using the $this->get_parsed_option( $field ) method and we fetch the user email using the get_userdata($this->user_id).

Note that we should not use the current user ID in conditions, because actions may be run on non-logged in users, for example, when an admin adds users to a course or when something happens in a cron job. Always use $this->user_id instead.

Note, that in a case when the user’s email has the TEXT we are searching for, we simply do nothing to let the action run.

This concludes the condition creation guide.

Checkout other articles from this series:

• Uncanny Automator Terminology
• Creating an Uncanny Automator integration
• Adding a Trigger to an integration
• Adding an Action to an integration
• Adding an Automator Pro Condition (you are here)
• Adding an app integration settings page