Maestro
A comprehensive workflow orchestration engine for Drupal that enables creation, management, and execution of complex workflow templates with conditional logic, parallel/serial task execution, and role-based task assignments.
maestro
Install
composer require 'drupal/maestro:^4.3'
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.
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.
Technical Details
Admin Pages 6
/admin/config/workflow/maestro
Configure the core Maestro workflow engine settings including orchestrator token, notification settings, and development mode options.
/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/list
List all workflow templates defined in the system. From here administrators can view, edit, start, validate, and delete workflow templates.
/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.
/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.
/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 14
Hooks 17
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 6
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.
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.
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.
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.
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.
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 4
- 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.