Building Automations

Introduction

OptiFlow’s automation builder allows you to create sophisticated, event-driven workflows using a visual drag-and-drop interface. Automations respond to triggers and execute actions automatically, eliminating repetitive manual tasks.

Automation Builder Interface

The automation builder (resources/js/components/automations/automation-builder.tsx) provides a powerful node-based canvas:

Canvas: Drag nodes, create connections, and visualize your automation flow
Node Catalog: Browse available triggers, actions, and conditions
Node Inspector: Configure selected nodes with specific settings
Undo/Redo: Full history management with keyboard shortcuts (Cmd/Ctrl+Z)
Copy/Paste: Duplicate node groups (Cmd/Ctrl+C, Cmd/Ctrl+V)

The builder uses ReactFlow under the hood, providing smooth interactions, minimap navigation, and zoom controls.

Creating an Automation

Access the Automation Builder

Navigate to the automations section and click “Create Automation”.

Configure the Trigger

Every automation starts with a trigger node. Select the event that will start your automation:

Workflow Stage Entered: When a job moves to a specific workflow stage
Invoice Created: When a new invoice is created
Invoice Updated: When an invoice is modified

Add Action Nodes

Click “Add Node” to open the node catalog. Choose from available actions:

WhatsApp Message: Send messages to customers
Telegram Message: Notify staff members
Webhook: Call external APIs
Condition: Add conditional logic

Connect Nodes

Drag from a node’s output handle to another node’s input handle to create connections. These define the execution flow.

Configure Node Settings

Select each node to configure its specific settings in the inspector panel on the right.

Save and Activate

Give your automation a name, toggle the “Active” checkbox, and click “Save”.

Automation Triggers

Triggers define when your automation runs. They are configured in the AutomationTrigger model.

Workflow Stage Entered Trigger

This is the most common trigger for optical stores. It fires when a workflow job enters a specific stage. Configuration:

[
  'workflow_id' => 'uuid-of-workflow',
  'stage_id' => 'uuid-of-stage',
]

Example Use Cases:

Send WhatsApp when order reaches “Ready for Pickup”
Notify optician when job enters “Quality Check”
Create invoice when job reaches “Completed”

Invoice Triggers

Invoice Created: Fires when a new invoice is created Invoice Updated: Fires when an invoice is modified These triggers have access to invoice data including totals, line items, and associated contacts.

Triggers are stored in the automation_triggers table and linked to specific automations via automation_id.

Action Nodes

WhatsApp Message Node

Send automated WhatsApp messages to customers using connected WhatsApp Business accounts. Configuration:

WhatsApp Account: Select from configured accounts
Recipient: Use template variables like {{contact.number}}
Message Template: Craft your message with dynamic variables

Example Message:

Hola {{contact.name}},

Tu orden #{{job.id}} está lista para recoger.
Total: {{invoice.total_amount}}

¡Te esperamos!

Telegram Message Node

Send notifications to Telegram chats for internal staff communication. Configuration:

Telegram Bot: Select from configured bots
Chat ID: Specify the destination chat
Message: Use template variables

Example Message:

🔔 Nuevo trabajo en {{to_stage.name}}

Cliente: {{contact.name}}
Prioridad: {{job.priority}}
Vence: {{job.due_date}}

Asignado por: {{actor.name}}

Webhook Node

Call external APIs to integrate with third-party systems. Configuration:

URL: Endpoint to call
Method: GET, POST, PUT, DELETE
Headers: Custom HTTP headers
Body: JSON payload with template variables

Condition Node

Add conditional logic to create branching automations. Configuration:

Field: Select workflow field or context variable
Operator: Equals, contains, greater than, etc.
Value: Comparison value

Condition nodes enable sophisticated automations like “Send WhatsApp only if invoice total is greater than $500”.

Template Variables

Template variables allow you to insert dynamic data into your messages and webhooks. The AutomationController provides these variables:

Variable	Description	Example
`{{contact.name}}`	Customer name	”Juan Pérez”
`{{contact.number}}`	Customer phone	”+1234567890”
`{{contact.email}}`	Customer email	”[email protected]”
`{{invoice.number}}`	Invoice number	”INV-001”
`{{invoice.total_amount}}`	Invoice total	”$250.00”
`{{job.id}}`	Job UUID	”9a3f…”
`{{job.priority}}`	Job priority	”high”
`{{job.due_date}}`	Due date	”2026-03-15”
`{{to_stage.name}}`	Destination stage	”Ready for Pickup”
`{{from_stage.name}}`	Previous stage	”In Progress”
`{{actor.name}}`	User who triggered	”María García”

Template variables are replaced server-side by the AutomationContext class. Invalid variables will be replaced with empty strings.

Testing Automations

Before activating an automation, test it to ensure it works as expected.

Test Run Controller

The AutomationTestRunController allows you to execute automations with sample data:

// app/Http/Controllers/AutomationTestRunController.php
// Provides test execution with mock context

Testing Process:

Select an automation to test
Provide sample data (contact, invoice, job details)
Execute the test run
Review the results and node outputs

Test Data Controller

The AutomationTestDataController generates realistic test data:

// Generates sample contacts, invoices, and jobs
// Useful for testing automations without affecting real data

Test runs create AutomationRun records with a test flag, so they don’t interfere with production automation metrics.

Automation Runs and History

Every time an automation executes, it creates an AutomationRun record.

AutomationRun Model

// app/Models/AutomationRun.php
final class AutomationRun extends Model
{
    // Properties:
    // - automation_id: Which automation ran
    // - automation_version_id: Version of the automation
    // - trigger_event_key: What triggered it
    // - subject_type: 'workflow_job' or 'invoice'
    // - subject_id: ID of the triggering entity
    // - status: 'running', 'completed', 'failed'
    // - pending_nodes: Number of nodes still executing
    // - started_at: When execution began
    // - finished_at: When execution completed
    // - error: Error message if failed
}

Node Run Tracking

Each node execution is tracked in AutomationNodeRun:

Node ID: Which node executed
Status: pending, running, completed, failed, skipped
Input: Data passed to the node
Output: Result from the node
Error: Error details if failed
Started/Finished: Execution timestamps

Viewing Run History

The AutomationRunController provides views to:

List all runs for an automation
View detailed run results
See individual node execution details
Debug failed automations

Automation runs are retained for audit purposes. You can see exactly when automations fired, what data they processed, and whether they succeeded.

Automation Versioning

Automations support versioning via the AutomationVersion model. How It Works:

When you save an automation, a new version is created
The version stores the complete node and edge definition
Active automations reference a published_version
You can roll back to previous versions if needed

Version Fields:

[
  'automation_id' => 'parent-automation-uuid',
  'version' => 1, // Incremental version number
  'definition' => [ // Complete automation definition
    'nodes' => [...],
    'edges' => [...],
  ],
]

Versioning allows you to safely update automations. If a new version causes issues, you can quickly roll back to a known-good version.

Real-World Example

Here’s a complete automation for an optical store: Scenario: Notify customers when their prescription eyewear is ready for pickup.

Trigger

Workflow Stage Entered

Workflow: “Prescription Eyewear Orders”
Stage: “Ready for Pickup”

Condition

Check if contact has phone number

Field: contact.number
Operator: “is not empty”

WhatsApp Message

Send pickup notificationMessage:

Hola {{contact.name}},

¡Buenas noticias! Tu orden está lista para recoger.

📋 Orden: #{{job.id}}
💰 Total: {{invoice.total_amount}}

Visítanos en nuestro horario de atención.

¡Gracias por tu preferencia!

Telegram Notification

Notify staffMessage:

📦 Orden lista para entrega

Cliente: {{contact.name}}
Orden: #{{job.id}}
Total: {{invoice.total_amount}}

Preparado por: {{actor.name}}

Best Practices

Start Simple

Begin with single-action automations (one trigger → one action). Add complexity gradually as you become comfortable.

Use Descriptive Names

Name automations clearly: “Send WhatsApp - Order Ready” instead of “Automation 1”.

Test Before Activating

Always test automations with sample data before activating them for production use.

Monitor Run History

Regularly check automation runs to ensure they’re executing as expected and troubleshoot any failures.

Use Template Variables Wisely

Always have fallback text for optional variables. Example: {{contact.name}} or “Cliente”.

Handle Errors Gracefully

Design automations to degrade gracefully. If WhatsApp fails, consider having a fallback notification method.

Keyboard Shortcuts

The automation builder supports these keyboard shortcuts:

Shortcut	Action
`Cmd/Ctrl + Z`	Undo
`Cmd/Ctrl + Shift + Z`	Redo
`Cmd/Ctrl + Y`	Redo
`Cmd/Ctrl + C`	Copy selected nodes
`Cmd/Ctrl + V`	Paste nodes
`Delete/Backspace`	Delete selected nodes

Keyboard shortcuts are disabled when focus is inside text inputs to prevent accidental actions while typing.

Advanced Features

Copy and Paste Nodes

Select one or more nodes and press Cmd/Ctrl + C to copy them. Press Cmd/Ctrl + V to paste with a slight offset. This is useful for creating similar action chains.

Undo/Redo History

The builder maintains up to 100 snapshots of your automation state. Use undo/redo to experiment without fear of losing your work.

Node Selection and Multi-Select

Click nodes to select them individually. Hold Shift and click to select multiple nodes. Selected nodes can be moved together or deleted as a group.

Workflows Overview

Learn about workflows and how they integrate with automations

Prescription Management

Link prescriptions to workflow jobs and automations

Get Started

Core Features

Guides

Workflows & Automation

Building Automations

Introduction

Automation Builder Interface

Creating an Automation

Automation Triggers

Workflow Stage Entered Trigger

Invoice Triggers

Action Nodes

WhatsApp Message Node

Telegram Message Node

Webhook Node

Condition Node

Template Variables

Testing Automations

Test Run Controller

Test Data Controller

Automation Runs and History

AutomationRun Model

Node Run Tracking

Viewing Run History

Automation Versioning

Real-World Example

Best Practices

Keyboard Shortcuts

Advanced Features

Copy and Paste Nodes

Undo/Redo History

Node Selection and Multi-Select

Workflows Overview

Prescription Management

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

Workflows & Automation

​Introduction

​Automation Builder Interface

​Creating an Automation

​Automation Triggers

​Workflow Stage Entered Trigger

​Invoice Triggers

​Action Nodes

​WhatsApp Message Node

​Telegram Message Node

​Webhook Node

​Condition Node

​Template Variables

​Testing Automations

​Test Run Controller

​Test Data Controller

​Automation Runs and History

​AutomationRun Model

​Node Run Tracking

​Viewing Run History

​Automation Versioning

​Real-World Example

​Best Practices

​Keyboard Shortcuts

​Advanced Features

​Copy and Paste Nodes

​Undo/Redo History

​Node Selection and Multi-Select

​Related Resources

Workflows Overview

Prescription Management

Build docs developers (and LLMs) love

Introduction

Automation Builder Interface

Creating an Automation

Automation Triggers

Workflow Stage Entered Trigger

Invoice Triggers

Action Nodes

WhatsApp Message Node

Telegram Message Node

Webhook Node

Condition Node

Template Variables

Testing Automations

Test Run Controller

Test Data Controller

Automation Runs and History

AutomationRun Model

Node Run Tracking

Viewing Run History

Automation Versioning

Real-World Example

Best Practices

Keyboard Shortcuts

Advanced Features

Copy and Paste Nodes

Undo/Redo History

Node Selection and Multi-Select

Related Resources