Filament Workflow

Visual workflow automation engine for Filament 4+ built on filament-diagrammer.

Features

• Visual flow builder with drag-and-drop nodes
• Trigger → Condition → Delay → Action pipeline
• IF/ELSE branching with condition nodes
• Time-based triggers (due date reminders, overdue escalation)
• Extensible trigger and action registry with dynamic config forms
• Workflow templates (predefined flows)
• Subclassable designer for app-specific customization
• Execution logging and audit trail
• Global + project-scoped workflows

Requirements

• PHP 8.3+
• Laravel 12+
• Filament 4+
• codenzia/filament-diagrammer

Installation

Publish and run migrations:

Publish the config file (optional):

Tailwind v4 Custom Theme

If your Filament panel uses a custom theme (Tailwind CSS v4), add source paths for both this package and its dependency filament-diagrammer:

This wildcard pattern covers all Codenzia packages (including the filament-diagrammer dependency) at once.

Then rebuild your assets (npm run build).

Quick Start

1. Add HasWorkflows trait to your model

This automatically dispatches workflow evaluation on model created and updated events.

2. Register triggers and actions

In your AppServiceProvider::boot():

3. Embed the designer in a page

The modelType parameter is required — the designer will abort if not provided.

Diagram & Rules Tabs

The designer includes two tabs above the canvas:

• Diagram — Visual drag-and-drop canvas (default)
• Rules — Structured form-based step list

Both tabs edit the same underlying data. Changes made in one tab are immediately visible when switching to the other.

The Rules tab shows:

• Connected flows as a vertical step list with condition branching (Yes/No columns)
• Inline + buttons between steps to insert new nodes
• An "Add Step" button for creating new trigger/action/condition/delay steps
• An Unconnected Steps section (collapsed by default) for orphaned nodes

Double-click any step card to open its settings editor.

When switching from Rules back to Diagram, nodes created in the rules view are automatically positioned using a layered tree layout algorithm.

Configuration

Published to config/filament-workflow.php:

Concepts

Node Types

Each node type includes a description() method with localizable help text (via filament-workflow::node-types.*). The palette sidebar shows a ? tooltip on hover with this description.

Double-click any node to open its settings editor. Right-click for the context menu with Settings, Delete, Connect to, and more.

Triggers (Built-in)

• ModelCreated — fires when a model is created
• ModelUpdated — fires when a model is updated
• FieldChanged — fires when a specific field changes (optional from/to constraints)

Actions (Built-in)

• ChangeField — updates a field on the model
• SendNotification — sends a Laravel notification to a user
• DispatchEvent — dispatches a Laravel event

Conditions

Operators: equals, not_equals, greater_than, less_than, greater_than_or_equal, less_than_or_equal, contains, not_contains, is_null, is_not_null, in, not_in

Logic: and (all conditions must match) or or (any condition can match)

Extending

Custom Triggers

Implement TriggerInterface. The configSchema() method returns Filament form fields that appear in the node settings dialog when this trigger type is selected:

Custom Actions

Implement ActionHandlerInterface. The configSchema() method defines what the user configures on the action node:

Config field naming: Use the config. prefix (e.g., config.user_id, config.status) so values are stored in the node's config JSON column. The node type forms automatically show/hide config fields based on the selected trigger/action type.

Register in ServiceProvider

Workflow Templates

Provide predefined workflow templates by subclassing WorkflowDesigner and overriding getWorkflowTemplates():

When templates are available, the "New Workflow" dialog shows a Start from template dropdown. Selecting a template pre-fills the name and description, and scaffolds all nodes and connections on creation.

Templates reference node indices (0, 1, 2...) for connections — the source and target values map to the nodes array order.

Customizing the Designer

The WorkflowDesigner is designed for subclassing. Override these methods to customize:

Example — embedding a subclass:

Remember to register the Livewire component in your AppServiceProvider:

Time-Based Triggers

For triggers based on due dates or overdue status, schedule the command:

The command finds active workflows with time-based trigger nodes, queries matching models, and dispatches evaluation jobs. Deduplication prevents the same model+workflow from re-triggering within the configured window (default: 24 hours).

Time Trigger Query Scoping

For time-based triggers to work with the preview and scheduler, implement the optional scopeMatchingModels static method on your trigger class:

Run Now

The WorkflowDesigner includes a Run Now button for workflows with time-based triggers. This manually invokes the workflow:process-time-triggers command, allowing users to test their time trigger configuration without waiting for the scheduler.

Time Trigger Preview

The monitor panel shows a live preview of which models would match the current time trigger configuration. This helps users validate their trigger setup before activating the workflow.

Monitoring & Execution History

The WorkflowDesigner includes a collapsible Monitor panel below the canvas that shows:

Scheduler Status

• Total workflow runs
• Last run timestamp
• Number of node executions in the last 24 hours
• Configured deduplication window

Time Trigger Preview

• Whether the workflow has time-based triggers
• How many models would match right now
• A list of the first 10 matching models (ID + label)

Recent Executions

• Color-coded execution log (green = success, red = failure, blue = delayed, gray = skipped)
• Node label, model ID, and relative timestamp for each execution
• Last 10 executions shown inline, up to 50 available via scroll

Execution Logs

Every node execution is logged to workflow_execution_logs with:

• Workflow and node IDs
• Model type and ID
• Trigger type
• Result (success, failure, skipped, delayed)
• Execution details (what changed, what failed, etc.)
• Timestamp

Infinite Loop Prevention

The engine uses two mechanisms:

1. Static $executing flag — prevents re-entrant execution when model changes trigger new evaluations
2. Max nodes per run — limits the number of nodes executed in a single workflow run (default: 50)

Database Schema

workflows

Stores workflow definitions with name, model type, project scope, status, and priority.

workflow_nodes

Individual nodes in a workflow: type (trigger/condition/delay/action), configuration, and canvas position.

workflow_connections

Edges between nodes: source, target, optional label (e.g., "Yes"/"No"), and sort order.

workflow_execution_logs

Audit trail of every node execution with result and details.

Testing

License

Proprietary — Codenzia