How to create a custom automation trigger in fluent crm

FluentCRM is the awesome and automation is the magic of FluentCRM. It has so many buildin triggers to perform the magic for you. But anyone can create their own trigger without touching existing triggers. Isn't cool? 

Following some steps, anyone can be part of this magic. In this article, we will show you, how you are able to add a custom trigger in automation

What is trigger in Automation?

Trigger is the entry point of a automation. Every automation starts using a trigger. There are a lot of triggers that can start or initiate automation in FluentCRM such as Primary Automation Triggers, Ecommerce Triggers, Membership Triggers, LMS Triggers, and many more. Using those trigger you can track various activities in your WordPress ecosystem.

Let's dive deep to learn how to create a custom trigger for Fluent CRM automation. To make an custom trigger, we need to use two filters and one action hook.

• fluentcrm_funnel_triggers: This is a filter hook and this hook will regisiter your custom hook to trigger list.
• fluentcrm_funnel_editor_details_{trigger_name}: This is also a filter hook and this will build your custom trigger setting block. For the following trigger source code, the {trigger_name} is ct_file_uploaded
• fluentcrm_funnel_start_{trigger_name}: This is an action hook and this will be called automatically depending on the trigger_name. You can do further using this action hook.

Sometimes example is the easy way to learn. Let's see an example. To add a custom trigger in automation, I am going to tell you to step by step. This example will be using composer, you can do without composer too.

Step 1

Here is the full source code of custom trigger.

<?php

class CustomTrigger
{
    public function __construct()
    {
        $this->triggerName = 'ct_file_uploader';
        $this->priority = 20;
        $this->actionArgNum = 2;
        add_filter('fluentcrm_funnel_triggers', array($this, 'addTrigger'), $this->priority, 1);
        add_filter('fluentcrm_funnel_editor_details_'.$this->triggerName, array($this, 'prepareEditorDetails'), 10, 1);
        add_action('fluentcrm_funnel_start_' . $this->triggerName, array($this, 'handle'), 10, 2);
    }

    public function getTrigger()
    {
        return [
            'category'    => __('File Uploader'),
            'label'       => __('A file uploaded'),
            'description' => __('This Funnel will be initiated when a File Uploader\'s file uploaded successfully'),
            'icon'        => 'fc-icon-wp_new_user_signup',
        ];
    }

    public function addTrigger($triggers)
    {
        $triggers[$this->triggerName] = $this->getTrigger();
        return $triggers;
    }

    public function getSettingsFields($funnel)
    {
        return [
            'title'     => __('A file uploaded'),
            'sub_title' => __('This Funnel will be initiated when a File Uploader\'s file uploaded successfully.'),
            'fields'    => [
                'message' => [
                    'type'        => 'input-text',
                    'label'       => __('Message Title'),
                    'placeholder' => __('Type Message Title')
                ],
            ]
        ];
    }

    public function prepareEditorDetails($funnel)
    {
        $funnel->settings = wp_parse_args($funnel->settings, $this->getFunnelSettingsDefaults());
        $funnel->settingsFields = $this->getSettingsFields($funnel);
        $funnel->conditions = wp_parse_args($funnel->conditions, $this->getFunnelConditionDefaults($funnel));
        $funnel->conditionFields = $this->getConditionFields($funnel);
        return $funnel;
    }

    public function getFunnelSettingsDefaults()
    {
        return [
            'subscription_status' => 'subscribed'
        ];
    }

    public function getConditionFields($funnel)
    {
        return [
            'file_types'   => [
                'type'        => 'multi-select',
                'is_multiple' => true,
                'label'       => __('Targeted File Type', 'fluent-crm'),
                'help'        => __('Select which file upload will run this automation Funnel', 'fluent-crm'),
                'placeholder' => __('Select file types', 'fluent-crm'),
                'options'     => $this->getFileTypes(),
                'inline_help' => __('Leave blank to run for all file upload', 'fluent-crm')
            ],
            'run_multiple'       => [
                'type'        => 'yes_no_check',
                'label'       => '',
                'check_label' => __('Restart the Automation Multiple times for a contact for this event. (Only enable if you want to restart automation for the same contact)'),
                'inline_help' => __('If you enable, then it will restart the automation for a contact if the contact already in the automation. Otherwise, It will just skip if already exist')
            ]
        ];
    }

    private function getFileTypes()
    {
        return [
            ['id' => 'csv', 'title' => 'CSV'],
            ['id' => 'image', 'title' => 'Image'],
            ['id' => 'video', 'title' => 'Video'],
        ];
    }

    public function getFunnelConditionDefaults($funnel)
    {
        return [
            'file_types'   => $this->getFileTypes(),
            'run_multiple'       => 'yes'
        ];
    }

    public function handle($funnel, $originalArgs)
    {
        error_log(print_r([$funnel, $originalArgs], 1));
    }
}

Here we created a class called CustomTrigger which contains all the code for trigger. Let's split the code and describe each part in details.

public function __construct()
{
    $this->triggerName = 'ct_file_uploader';
    $this->priority = 20;
    $this->actionArgNum = 2;
    add_filter('fluentcrm_funnel_triggers', array($this, 'addTrigger'), $this->priority, 1);
    add_filter('fluentcrm_funnel_editor_details_'.$this->triggerName, array($this, 'prepareEditorDetails'), 10, 1);
    add_action('fluentcrm_funnel_start_' . $this->triggerName, array($this, 'handle'), 10, 2);
}

In the __construct method, we initializes three properties triggerName, priority, and actionArgNum.  We also registered two filters and one action hooks, which will execute the corresponding class methods (addTrigger, prepareEditorDetails, and handle) when the specific events occur.

 public function addTrigger($triggers)
 {
    $triggers[$this->triggerName] = $this->getTrigger();
    return $triggers;
 }

The addTrigger method will register the CustomTrigger in the automation trigger list under a new category called File Uploader. It receives an array of triggers as a parameter. It adds the current trigger, build from getTrigger, to the array using the triggerName as the key.

public function getTrigger()
{
    return [
        'category'    => __('File Uploader'),
        'label'       => __('A file uploaded'),
        'description' => __('This Funnel will be initiated when a File Uploader\'s file uploaded successfully'),
        'icon'        => 'fc-icon-wp_new_user_signup',
    ];
}

The getTrigger method returns an array representing the trigger details. It includes the category, label, description, and icon for the trigger.

public function prepareEditorDetails($funnel)
{
    $funnel->settings = wp_parse_args($funnel->settings, $this->getFunnelSettingsDefaults());
    $funnel->settingsFields = $this->getSettingsFields($funnel);
    $funnel->conditions = wp_parse_args($funnel->conditions, $this->getFunnelConditionDefaults($funnel));
    $funnel->conditionFields = $this->getConditionFields($funnel);
    return $funnel;
}

The trigger's popup modal will generate according to the code of the prepareEditorDetails method. It takes a $funnel object as a parameter. Within this method, the following tasks are performed:

1. The $funnel->settings property is merged with the default settings obtained from getFunnelSettingsDefaults using the wp_parse_args function. This ensures that any missing settings are populated with their default values.
2. The $funnel->settingsFields property is set by calling the getSettingsFields method, which retrieves an array representing the settings fields for the funnel.
3. The $funnel->conditions property is merged with the default conditions obtained from getFunnelConditionDefaults using wp_parse_args.
4. The $funnel->conditionFields property is set by calling the getConditionFields method, which retrieves an array representing the condition fields for the funnel.

Finally, the modified $funnel object is returned.

public function getSettingsFields($funnel)
{
    return [
        'title'     => __('A file uploaded'),
        'sub_title' => __('This Funnel will be initiated when a File Uploader\'s file uploaded successfully.'),
        'fields'    => [
            'message' => [
                'type'        => 'input-text',
                'label'       => __('Message Title'),
                'placeholder' => __('Type Message Title')
            ],
        ]
    ];
}

The getSettingsFields method returns an array representing the settings fields for the funnel. It includes the title, sub_title, and an array of fields with their respective properties such as type, label, and placeholder.

public function getFunnelSettingsDefaults()
{
    return [
        'subscription_status' => 'subscribed'
    ];
}

The getFunnelSettingsDefaults method returns an array of default settings for the funnel which generate a select form field to define target user's default role . In this case, it includes a single key-value pair with the key 'subscription_status' and the value 'subscribed'. 

public function getConditionFields($funnel)
{
    return [
        'file_types'   => [
            'type'        => 'multi-select',
            'is_multiple' => true,
            'label'       => __('Targeted File Type', 'fluent-crm'),
            'help'        => __('Select which file upload will run this automation Funnel', 'fluent-crm'),
            'placeholder' => __('Select file types', 'fluent-crm'),
            'options'     => $this->getFileTypes(),
            'inline_help' => __('Leave blank to run for all file upload', 'fluent-crm')
        ],
        'run_multiple'       => [
            'type'        => 'yes_no_check',
            'label'       => '',
            'check_label' => __('Restart the Automation Multiple times for a contact for this event. (Only enable if you want to restart automation for the same contact)'),
            'inline_help' => __('If you enable, then it will restart the automation for a contact if the contact already in the automation. Otherwise, It will just skip if already exist')
        ]
    ];
}
private function getFileTypes()
{
    return [
        ['id' => 'csv', 'title' => 'CSV'],
        ['id' => 'image', 'title' => 'Image'],
        ['id' => 'video', 'title' => 'Video'],
    ];
}

The getConditionFields method returns an array representing the condition fields for the funnel. It includes multiple fields with their respective properties such as type, label, help text, placeholder, options, and inline help. 

public function handle($funnel, $originalArgs)
{
    error_log(print_r([$funnel, $originalArgs], 1));
}

The handle method is responsible for handling the trigger action. It takes two parameters: $funnel and $originalArgs. You can customize this method to perform the desired actions when the trigger event occurs.

Step 2

Using the following code, You can able to add this custom trigger code in FluentCRM.

add_action('plugins_loaded', function () {
   if (defined('FLUENTCAMPAIGN_DIR_FILE')) {
      new CustomTrigger();
   }
});

You see, making a custom trigger is so simple. Just need to follow some instruction. That’s it. To learn more about Automation, you can check the Fluent CRM's offical developer doc.