Maestro

Overview

Maestro is an enterprise-grade workflow automation system for Drupal that provides a complete solution for business process management (BPM) and workflow orchestration. The module allows site administrators and developers to design, deploy, and execute complex workflows through a visual drag-and-drop template builder.

At its core, Maestro features an orchestration engine that continuously processes workflow instances, executing tasks, evaluating conditions, and routing workflows based on user actions or automated logic. The system supports multiple task types including interactive tasks requiring user input, batch functions for automated processing, content type tasks for node creation/editing, and conditional logic gates (IF, AND, OR) for workflow branching.

Workflows can be assigned to users or roles, with support for dynamic assignment through variables. The module includes comprehensive notification capabilities, task reassignment features, process variable management, and detailed workflow tracing for audit purposes. A dedicated Task Console provides end-users with a centralized interface to view and execute their assigned tasks.

Install

Drupal 11, 10 v4.3.0

composer require 'drupal/maestro:^4.3'

Features

Visual SVG-based workflow template builder using Raphael.js library for drag-and-drop workflow design
11 built-in task types: Start, End, Interactive, Batch Function, Content Type, If (conditional), And (synchronization gate), Or (first-come gate), Manual Web, Set Process Variable, and Spawn Sub Flow
Background orchestrator engine that processes workflow instances, evaluates conditions, and routes tasks automatically
Task Console for end-users to view assigned tasks and execute interactive workflows
Role-based and user-based task assignment with support for dynamic assignment via process variables
Process variables system for storing and manipulating workflow data during execution
Workflow tracing and timeline status bar for monitoring process progress
Comprehensive notification system with assignment, reminder, and escalation notifications
Token-based secure task execution for external access to workflow tasks
Webform integration submodule for incorporating webform submissions into workflows
Content Type task integration for creating and editing Drupal nodes within workflows
Spawn Sub Flow capability for creating child workflow instances with variable inheritance
Pre-built Views for outstanding tasks, all in-production tasks, completed tasks, and all workflow instances
Extensive hook system for customizing workflow behavior, notifications, task execution, and console display
Template validation system to verify workflow configuration before deployment

Use Cases

Document Approval Workflow

Create a multi-stage document approval process where content is submitted, reviewed by one or more approvers, potentially revised, and finally published. Use Content Type tasks for document editing, Interactive tasks for approval decisions, and IF tasks to route based on approval status.

Employee Onboarding

Automate new employee onboarding with tasks assigned to HR, IT, and management. Parallel task paths can handle equipment provisioning, account creation, and documentation simultaneously, with AND gates to synchronize before completion.

Purchase Request Processing

Route purchase requests through appropriate approval chains based on amount. Use process variables to store request amounts, IF tasks to route to different approvers based on thresholds, and notifications to keep requesters informed of status.

Content Publishing Pipeline

Implement a multi-stage content publishing workflow with draft creation, editorial review, legal compliance check, and final publication. Use the Spawn Sub Flow task to trigger related workflows like social media promotion.

Customer Support Escalation

Create tiered support workflows where issues can be escalated through support levels. Use OR gates to handle resolution at any level, and Set Process Variable tasks to track escalation history.

Webform-Driven Processes

Use the Webform integration to create workflows triggered by form submissions. Ideal for application processing, feedback collection, or service requests where form data drives the workflow.

Tips

Start with the 'Maestro Form Approval Flow Example' module to understand workflow concepts before building custom templates.
Use process variables extensively to pass data between tasks and make routing decisions.
The template validation feature helps catch configuration errors before deploying workflows to production.
Consider using the Spawn Sub Flow task to break complex workflows into manageable, reusable sub-workflows.
Use Views to create custom task displays filtered by process type, user role, or other criteria.
Implement custom batch handlers for automated tasks that integrate with external systems or perform complex logic.
Take advantage of hooks to customize task console display, notifications, and workflow behavior without modifying core Maestro code.
For high-volume workflows, configure the orchestrator to run frequently via cron and tune the lock execution time appropriately.

Related Projects

webform

The maestro_webform submodule provides deep integration with Webform, allowing webform submissions to trigger and be part of workflow processes.

rules

Maestro provides a Rules action to spawn workflow instances, allowing workflows to be triggered by Rules events.

views Core

Comprehensive Views integration with custom fields, filters, and argument defaults for displaying workflow processes, queue items, and entity identifiers.

Admin Pages

Title	Path	Description
Maestro Engine Module Settings	`/admin/config/workflow/maestro`	Configure the core Maestro workflow engine settings including orchestrator token, notification settings, and development mode options.
Maestro Template Editor Module Settings	`/admin/config/workflow/maestro_template_builder`	Configure the visual workflow template builder settings, particularly the Raphael JS library location used for SVG-based workflow editing.
Maestro Templates	`/maestro/templates/list`	List all workflow templates defined in the system. From here administrators can view, edit, start, validate, and delete workflow templates.
Template Builder	`/template-builder/{templateMachineName}`	Visual drag-and-drop workflow editor using SVG graphics. Add, edit, and connect workflow tasks to design the workflow flow. Configure task properties, assignments, notifications, and workflow routing.
Task Console	`/taskconsole`	End-user interface for viewing and executing assigned workflow tasks. Users can see all tasks assigned to them, expand task details, view workflow status, and execute or reject tasks.
Trace	`/maestro/trace/{processID}`	Workflow tracing interface that shows the complete execution history of a workflow process. View all tasks that have been executed, their completion status, who completed them, and when.

Permissions

Permission	Description
	Allows access to the Maestro Template Task editor and administrative operations including creating, editing, and deleting templates.
	Allows users to initiate new workflow instances from templates.
	Grants users access to view the task console and see their assigned tasks.
	Allows access to administration forms for configuring and managing Maestro Queue entities including task reassignment.
	Allows creation of new queue entries.
	Allows deletion of queue entries.
	Allows editing of queue entry properties.
	Allows viewing of queue entries in Views and other displays.
	Allows creation of new process instances.
	Allows deletion of workflow process instances.
	Allows editing of process properties.
	Allows viewing of process information.
	Allows access to task reassignment functionality.
	Allows management of entity-to-workflow mappings.

Hooks

Hook	Description
`hook_maestro_post_variable_save`	Fired after a process variable is saved, allowing modules to react to variable changes.
`hook_maestro_post_fetch_assigned_queue_tasks`	Allows modules to add additional queue task IDs to the list of tasks assigned to a user.
`hook_maestro_can_user_execute_task_alter`	Alter hook to modify whether a user can execute a specific task.
`hook_maestro_template_validation_check`	Allows modules to add custom validation checks during template validation.
`hook_maestro_post_production_assignments`	Fired after a production task assignment is made, allowing post-assignment customization.
`hook_maestro_pre_task_save`	Fired before a task is saved, allowing modification of task configuration.
`hook_maestro_production_NOTIFICATIONTYPE_notification`	Create or alter notifications of specific types (assignment, reminder, escalation).
`hook_maestro_zero_user_notification`	Handle notifications when a role has no assigned users. Allows custom notification mechanisms.
`hook_maestro_task_console_interactive_link_alter`	Alter the text of task execution links in the task console.
`hook_maestro_task_console_interactive_url_alter`	Alter the execution URL for tasks in the task console.
`hook_maestro_task_console_custominformation_alter`	Add custom information to task rows in the task console.
`hook_maestro_task_console_taskdetails_alter`	Alter the task details expansion content in the task console.
`hook_maestro_interactive_handlers`	Register interactive task form handlers that appear in the autocomplete list.
`hook_maestro_batch_handlers`	Register batch function handlers that appear in the autocomplete list.
`hook_maestro_process_status_alter`	Alter the process status display in the status block.
`hook_maestro_task_console_status_bar_alter`	Alter the workflow status bar display.
`hook_maestro_get_entity_token_value`	Provide custom token value resolution for entity tokens.

Troubleshooting

Orchestrator not running - tasks stay in queue

Ensure the orchestrator token is configured in Maestro settings. For testing, enable 'Run Orchestrator on Task Console Refreshes'. For production, verify cron or external HTTP calls to /orchestrator/{token} are working.

Tasks not appearing in Task Console

Check that the user has the 'view maestro task console' permission and that tasks are properly assigned to the user or their roles. Verify the orchestrator has run to create queue entries.

Template validation fails

Use the Validity Check feature in the template builder to identify configuration issues. Common problems include missing handlers, unconnected tasks, or missing assignments on interactive tasks.

Workflow stuck at AND gate

The AND gate waits for ALL incoming branches to complete. Verify all parallel paths are executing and completing. Check for any tasks that may be holding indefinitely.

Notifications not sending

Ensure 'Send out notifications' is enabled in Maestro settings. Check that users assigned to tasks have valid email addresses. For role assignments, verify the role has members.

Template builder canvas not displaying

Verify the Raphael.js library is accessible. Check Template Builder settings for correct library URL or local library path. Clear Drupal cache after changing library settings.

Security Notes

The orchestrator token should be a strong, unique value to prevent unauthorized workflow execution.
Users with 'administer maestro templates' permission can create workflows that execute PHP code via batch handlers - restrict this permission carefully.
Token-based task execution URLs can be used for external task completion - ensure proper validation in custom handlers.
The 'administer maestro queue entities' permission allows task reassignment which could be used to redirect workflow tasks.

Maestro `maestro`