Plugin Registration

Filament Flow provides a complete admin interface for managing workflows directly from your Filament panel. This allows you to:

• Create and edit workflows through a visual interface
• Manage states with drag-and-drop reordering
• Configure transitions between states
• Set up notifications for workflow events

Registering the Plugin

Register the plugin in your Filament panel provider:

use RoBYCoNTe\FilamentFlow\FilamentFlowPlugin;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ->plugins([
                FilamentFlowPlugin::make(),
            ]);
    }
}

Once registered, a new "Workflow" navigation group will appear in your panel with access to the Workflows resource.

Access URL: /your-panel-path/workflows (or /your-panel-path/{tenant}/workflows for multi-tenant panels)

Access Authorization

By default, the Workflow admin resource is accessible to all authenticated Filament users. In production, restrict access using authorizeUsing():

FilamentFlowPlugin::make()
    ->authorizeUsing(fn (User $user): bool => $user->hasRole('super_admin')),

The callback receives the authenticated user and must return a boolean.

To access the plugin instance from anywhere in your application:

use RoBYCoNTe\FilamentFlow\FilamentFlowPlugin;

$plugin = FilamentFlowPlugin::get();  // from registered Filament panel

Navigation Customization

Customize how the Workflow section appears in your panel's navigation:

FilamentFlowPlugin::make()
    ->navigationLabel('Workflows')
    ->navigationGroup('Configuration')
    ->navigationIcon('heroicon-o-cog-6-tooth')
    ->navigationSort(10)
    ->navigationParentItem('Settings'), // nest under a parent nav item

To hide the resource entirely (use Filament Flow programmatically only):

FilamentFlowPlugin::make()
    ->withoutWorkflowResource(),

What the resources are

Four resources make a workflow browsable from the panel, and each one carries its relation managers:

Resource	What it holds
WorkflowResource	States (StatesRelationManager), transitions (TransitionsRelationManager), scheduled checks (ScheduledChecksRelationManager), notifications (NotificationsRelationManager), the history of a record (TransitionHistoryRelationManager) and the notifications that were sent (NotificationLogsRelationManager)
WorkflowStateResource	The access rules of a state (AccessRulesRelationManager) and what it allows on each field (FieldPermissionsRelationManager)
WorkflowTransitionResource	The values it asks for (TransitionFieldsRelationManager), who may take it (TransitionPermissionsRelationManager), what it writes (SideEffectsRelationManager) and the rules it applies (ValidationRulesRelationManager)
WorkflowNotificationResource	The channels it goes through (ChannelsRelationManager) and who it reaches (RecipientsRelationManager)

Each resource comes with its pages: ListWorkflows, CreateWorkflow and EditWorkflow for the first, CreateWorkflowState and EditWorkflowState for the second, EditWorkflowTransition for the third, EditWorkflowNotification for the fourth.

None of them is needed when the workflows are declared in code: see below.

Disabling the Workflow Resource

If you only want to use Filament Flow programmatically without the admin interface:

FilamentFlowPlugin::make()
    ->withoutWorkflowResource()

To re-enable it:

FilamentFlowPlugin::make()
    ->withWorkflowResource()

Enabling Workflow Resources

Register the plugin in your Filament Panel provider and enable workflow resources:

<?php
// app/Providers/Filament/AdminPanelProvider.php

use Filament\Panel;
use RoBYCoNTe\FilamentFlow\FilamentFlowPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        // ... other configuration
        ->plugins([
            FilamentFlowPlugin::make()
                ->workflowResources(), // Enable workflow management UI
        ]);
}

This adds three resources to your admin panel:

1. Workflows — Create and manage workflow definitions
2. Workflow States — Define states for each workflow
3. Workflow Transitions — Configure allowed transitions between states

Creation Order

Follow this order when creating a new database-driven workflow:

1. Create a Workflow (required first)

   • Navigate to "Workflows" in your admin panel
   • Click "Create"
   • Fill in:
     • Workflow Name: Descriptive name (e.g., "Order Processing")
     • Model Class: Full class name (e.g., App\Models\Order)
     • State Column: Database column name (default: state)
     • Active: Whether this workflow is currently active

2. Add States (required second)

   • Navigate to "Workflow States"
   • Click "Create"
   • Fill in:
     • Workflow: Select the workflow you just created
     • State Name (Key): Unique identifier (e.g., pending, processing)
     • Display Label: Human-readable name (e.g., "Pending", "Processing")
     • PHP State Class: Optional — leave empty for database-only states
     • Color: Badge color for the UI
     • Icon: Optional Heroicon name
     • Sort Order: Display order (lower = first)
     • Initial State: Check for the default state of new records
     • Final State: Check if this is a terminal state
   • Repeat for all states in your workflow

3. Configure Transitions (required third)

   • Navigate to "Workflow Transitions"
   • Click "Create"
   • Fill in:
     • Workflow: Select your workflow
     • From State: Source state
     • To State: Target state
     • Transition Name (Key): Unique identifier (e.g., process, cancel)
     • Display Label: Button label (e.g., "Mark as Processing")
     • PHP Transition Class: Optional — leave empty for database-only
     • Requires Confirmation: Show confirmation dialog
     • Requires Reason: Require user to provide a reason
   • Repeat for all allowed transitions

Example: Creating an Order Workflow

Step 1: Create Workflow
- Name: "Order Processing"
- Model: "App\Models\Order"
- State Column: "state"

Step 2: Create States
- pending (gray, is_initial=true, sort_order=1)
- processing (blue, sort_order=2)
- shipped (info, sort_order=3)
- delivered (success, sort_order=4, is_final=true)
- cancelled (danger, sort_order=100, is_final=true)

Step 3: Create Transitions
- pending → processing (name: "process", label: "Mark as Processing")
- processing → shipped (name: "ship", label: "Ship Order")
- shipped → delivered (name: "deliver", label: "Mark as Delivered")
- pending → cancelled (name: "cancel", label: "Cancel Order", requires_reason=true)
- processing → cancelled (name: "cancel", label: "Cancel Order", requires_reason=true)

Customizing Navigation

The workflow resource is grouped under "Workflow" by default. You can customize the navigation through the plugin's fluent API:

use Filament\Support\Icons\Heroicon;

FilamentFlowPlugin::make()
    ->navigationGroup('System Configuration')
    ->navigationLabel('Workflows')
    ->navigationIcon(Heroicon::OutlinedCog6Tooth)
    ->navigationSort(10)
    ->navigationParentItem('Settings')

All navigation methods are optional — only set the ones you need to customize.

Conditional Display

You can conditionally show/hide workflow resources:

FilamentFlowPlugin::make()
    ->workflowResources(
        auth()->user()->hasRole('admin') // Only show to admins
    )