Creating and Working with Triggers

This document explains how to create and work with trigger nodes, which are responsible for initiating the execution of flows in FlowBuilder.

What are Triggers?

Triggers are a special type of node used to initiate the execution of a flow. They differ from regular nodes in the following aspects:

• They have no input connections (inputCount = 0)
• They are always the first node in a flow
• They respond to specific events to start execution

BaseTrigger Class

All triggers must extend the BaseTrigger class, which itself extends the BaseNode class. The BaseTrigger class already configures some important properties:

• Category: The category is automatically set to 'Triggers'.
• Input Count: The input count is automatically set to 0.
• Output Count: The output count is automatically set to 1.

namespace Modules\FlowBuilder\Support;

abstract class BaseTrigger extends BaseNode
{
    protected ?string $category = 'Triggers';
    protected int $inputCount = 0;
    protected int $outputCount = 1;

    // Trigger-specific methods...
}

Creating a Basic Trigger

To create a custom trigger, extend the BaseTrigger class and define the necessary properties:

namespace App\FlowBuilder\Nodes;

use Modules\FlowBuilder\Support\BaseTrigger;

class CustomTrigger extends BaseTrigger
{
    protected string $id = 'custom-trigger';
    protected string $label = 'Custom Trigger';
    protected string $icon = 'heroicon-o-bolt';

    // You can add custom fields, just like regular nodes
    public function fields() : array
}

The Trigger Method

Triggers have a trigger() method that must be called when the flow needs to be activated from that trigger.

$flow = Modules\FlowBuilder\Models\Flow::query()
        ->first();

$flow->findNode(ManualTrigger::class) // Get the drawflow node
    ->toBaseNode() // Transform to the base node
    ->trigger(); // Call the trigger method

This method dispatches the FlowTriggered event, which is automatically listened to by the ProcessFlowJob class. This listener then takes care of starting the flow execution from the trigger node.

Trigger Lifecycle

The lifecycle of a trigger follows these steps:

1. Initialization
   The trigger node is configured like any other node.

2. Activation
   The trigger is externally activated by calling its trigger() method — for example:

   • A manual trigger is activated via the Flow Builder UI.
   • A scheduled trigger is activated by a scheduled task or cron job.
   • A webhook trigger is activated when an HTTP request arrives.

3. Dispatch
   The trigger dispatches the FlowTriggered event.

4. Processing
   The ProcessFlowJob listens to this event and initiates the flow execution from the trigger node.

Registering Custom Triggers

Like regular nodes, custom triggers need to be registered with the FlowBuilder service:

// In a service provider
use Modules\FlowBuilder\Facades\Node;
use App\FlowBuilder\Nodes\Triggers\CustomTrigger;

public function boot()
{
    Node::register(CustomTrigger::class);
}

Example Trigger: Manual Trigger

Below is an example of a basic manual trigger, which starts the flow when manually triggered:

<?php

class ManualTrigger extends BaseTrigger
{
    protected string $id = 'manual-trigger';
    protected string $label = 'Manual Trigger';
    protected string $icon = 'heroicon-o-play';

    public function fields(): array
    {
        return [
            Placeholder::make('label')
                ->content(__('This trigger will be executed when the flow is manually triggered.')),
                
            TextInput::make(...)
        ];
    }
}

Example Trigger: Webhook Trigger

class WebhookTrigger extends BaseTrigger
{
    protected string $icon = 'phosphor-webhooks-logo-duotone';

    protected string $id = 'webhook_trigger';

    protected string $label = 'Webhook';

    public function fields(): array
    {
        return [
            ViewField::make('webhook') // Use a custom view
                ->view('flowbuilder::nodes.triggers.webhook'),
        ];
    }

    public function getDescription(): ?string
    {
        return __('This trigger allows you to start the flow via an external HTTP request.');
    }
}

Example Trigger: Scheduled Trigger

class ScheduleTrigger extends BaseTrigger
{
    protected string $icon = 'phosphor-clock-countdown-duotone';

    protected string $id = 'schedule_trigger';

    protected string $label = 'Schedule';

    public ?array $validationRules = [
        CronIsValidValidationRule::class, // Custom validation rule to check cron expression validity
    ];

    public ?string $flowObserver = FlowScheduleTriggerObserver::class; // Set the observer in a Flow model

    public function fields(): array
    {
        return [
            TextInput::make('cron')
                ->required()
                ->label(__('Cron Expression'))
                ->placeholder(__('* * * * *'))
                ->helperText(__('Define the schedule using a cron expression. Example: "0 9 * * 1-5" for 9AM on weekdays.')),
        ];
    }

    public function getDescription(): ?string
    {
        return __('This trigger allows you to start the flow based on a defined schedule using a cron expression. It is useful for automating tasks at specific times or intervals.');
    }
}