Articles

Creating Integrations

This article will go through the steps of creating a new plugin integration for Uncanny Automator. If you are creating new triggers or actions for an existing integration please see Creating Actions ‎and  Creating Triggers.

If you don’t know what an integration is or aren’t familiar with the concepts of an integration code, name or icons, please read What Is An Integration for high-level definitions.

For an example of a complete working plugin that creates an integration, trigger, and action; please see https://github.com/UncannyOwl/Uncanny-Automator-Sample-Integration.

Summary

Every integration has two mandatory hooks.

  1. add_action( 'uncanny_automator_add_integration', 'my_unique_add_integration_func', 10, 1 );
  2. add_filter( 'uncanny_automator_maybe_add_integration', 'maybe_add_integration', 11, 2 );

These hooks will be used to define:

  • if the integration should be loaded through a validation function
  • the location of the icons and logos for the recipe creation UI
  • the name of the integration
  • the unique code associated with the integration code

Integration Code

The integration code uniquely identifies the integration. It should include uppercase letters only, be unique, and have a logical association with the plugin or service.

An integration code has several uses within an integration:

  • Creates a unique filter to verify if this integration should be loaded. Ex if a certain plugin should be active, if a specific site setting is set, etc.
  • Allows triggers and actions to be categorized under this integration.

If there is another integration with the same code, your integration will be skipped or will override the other integrations with the same code.

Ex:

  • name “WordPress” code “WP”
  • name “WooCommerce” code “WC”

If an integration already exists with the same integration code you are trying to add, then your integration may be skipped. The Uncanny Automator Lite plugin has first priority to add integrations.

To view a list of integrations that have been registered, visit a recipe creation page at http://www.example.com/wp-admin/post-new.php?post_type=uo-recipe, open the browser developer console (press F12), type in “UncannyAutomator.integrations” and press Enter.

Integration Name

The name of the integration is alphanumeric and should have no special characters. It would usually be the name the plugin or service that the integration is built for. The name can have a maximum of 14 characters.

Ex:

  • plugin “Easy Digital Downloads” name “Easy Digital Downloads”
  • service “Zapier” name “Zapier”

Integration Icons

There should be five versions of an icon created for your integration. You will need to know the URL for each. They should be stored inside the plugin or theme you are developing. They may be stored in the media library or externally, however that is not recommended.

The 5 icons are as follow:

  1. 16px by 16 px png icon with a transparent background
  2. 32px by 32 px png icon with a transparent background
  3. 64px by 64 px png icon with a transparent background
  4. 150px(max) by 62px(max) png logo with a transparent background
  5. 300px(max) by 125px(max) png logo with a transparent background

Adding Your Integration

Hook into integration registration

// Register the integration's name, icons, and code
add_action( 'uncanny_automator_add_integration', 'my_unique_add_integration_func', 10 ,1 ); // Function names need to be unique

Register your integration

/**
 * Add integration data to Automator
 */
function my_unique_add_integration_func() {

   global $uncanny_automator;

   $uncanny_automator->register_integration(
      'WCX', // Integration Code
      array(
         'name'        => 'WooCommerce Sample', // Integration Name
         'icon_16'     => plugins_url( 'integration-woocommerce-icon-16.png', __FILE__ ),
         'icon_32'     => plugins_url( 'integration-woocommerce-icon-32.png', __FILE__ ),
         'icon_64'     => plugins_url( 'integration-woocommerce-icon-64.png', __FILE__ ),
         'logo'        => plugins_url( 'integration-woocommerce.png', __FILE__ ),
         'logo_retina' => plugins_url( 'integration-woocommerce@2x.png', __FILE__ ),
      )
   );
}

Let’s break it down!

1. Let’s grab the Automator global object which stores all integrations, triggers, actions, and recipe data.

global $uncanny_automator;

2. Set up your data and use $uncanny_automator->register_integration() to register the integration.

$uncanny_automator->register_integration( 
   ...
);

Verifying when the integration should be loaded

Hook into integration validation

// This filter adds your integration to Automator and its associated triggers and actions, if it passes the validation function
add_filter( 'uncanny_automator_maybe_add_integration', 'maybe_add_integration', 11, 2 );

Set up the validation function

/**
 * Check if the plugin we are adding an integration for is active based on integration code
 *
 * @param bool   $status If the integration is already active or not
 * @param string $code   The integration code
 *
 * @return bool $status
 */
function maybe_add_integration( $status, $code ) {

   if ( 'WCX' === $code ) {
      if ( class_exists( 'WooCommerce' ) ) {
         $status = true;
      } else {
         $status = false;
      }
   }

   return $status;
}

Let’s break it down!

1. Let’s check if the $code being checked is for our integration code.

if ( 'WCX' === $code )

2. Check if the related plugin or service is active. If its a service like an external API that is always available then just return true.

if ( class_exists( 'WooCommerce' ) )

3. Set the status as true if the plugin or service is available and false if it is not.

if ( class_exists( 'WooCommerce' ) ) {
   $status = true;
} else {
   $status = false;
}

Complete Code

// Register the integration's name, icons, and code 
add_action( 'uncanny_automator_add_integration', 'my_unique_add_integration_func', 10 ,1 ); // Function names need to be unique

/**
 * Add integration data to Automator
 */
function my_unique_add_integration_func() {

   global $uncanny_automator;

   $uncanny_automator->register_integration(
      'WCX', // Integration Code
      array(
         'name'        => 'WooCommerce Sample', // Integration Name
         'icon_16'     => plugins_url( 'integration-woocommerce-icon-16.png', __FILE__ ),
         'icon_32'     => plugins_url( 'integration-woocommerce-icon-32.png', __FILE__ ),
         'icon_64'     => plugins_url( 'integration-woocommerce-icon-64.png', __FILE__ ),
         'logo'        => plugins_url( 'integration-woocommerce.png', __FILE__ ),
         'logo_retina' => plugins_url( 'integration-woocommerce@2x.png', __FILE__ ),
      )
   );
}

// This filter adds your integration to Automator and its associated triggers and actions, if it passes the validation function
add_filter( 'uncanny_automator_maybe_add_integration', 'maybe_add_integration', 11, 2 );

/**
 * Check if the plugin we are adding an integration for is active based on integration code
 *
 * @param bool   $status If the integration is already active or not
 * @param string $code   The integration code
 *
 * @return bool $status
 */
function maybe_add_integration( $status, $code ) {

   if ( 'WCX' === $code ) {
      if ( class_exists( 'WooCommerce' ) ) {
         $status = true;
      } else {
         $status = false;
      }
   }

   return $status;
}

What’s next

After creating an integration, you may want to read Creating Triggers or Creating Actions.

Back To Top