Installation

Last updated on
4 November 2026

Installation

  1. Add Maestro to your site with Composer:

    composer require drupal/maestro
  2. Enable the main Maestro modules:

    • Maestro Engine
    • Maestro Task Console
    • A template builder: Maestro ReactFlow Template Builder and/or Maestro Template Builder with Diagram.js. You can enable both and choose per template.
    drush en maestro maestro_taskconsole maestro_reactflow_template_builder
    drush cr

    More information on all of the included modules is below.

  3. Set up user permissions at /admin/people/permissions.

    • Grant view maestro task console to any role whose users will be assigned workflow tasks.
    • Grant administer maestro templates to workflow administrators. This permission is also required for the template builders and the Visual Trace.
  4. Go to the Maestro Engine settings at /admin/config/workflow/maestro.

    • For initial use and getting started with Maestro: enable the checkbox Run the Orchestrator on Task Console Refreshes.
    • For production or more active development of real workflows, you will want the Maestro Engine running automatically in the background. Maestro requires you to enter a token for running the orchestrator. You WILL get errors if you try to run Maestro's engine without an orchestrator token.
    • YOU MUST set the token to a valid, non-empty string. Set it to something that can be called by a URL calling mechanism (wget, cron, PowerShell script, etc.).
    • The resulting URL to run the Maestro Engine is http://site_url/orchestrator/{token}. Without a token, running the orchestrator on Task Console refreshes will also fail. For example, if you set the token to "abcdefg", your orchestrator URL is http://site_url/orchestrator/abcdefg.
    • You can also run the orchestrator with Drush: drush maestro:orchestrate. Add --user=USERNAME_OR_ID to run it as a specific user for that run.
    • Run the orchestrator as. Leave this empty to run the orchestrator as whoever triggers it: the user refreshing the Task Console, anonymous for the /orchestrator URL, or the Drush user. When set, every orchestrator run executes its tasks as this user, and tasks that check permissions, such as the Tool Task, are checked against this account. The Drush --user option still overrides it. Anyone holding the orchestrator token can run tasks as this user, so choose an account with only the permissions your workflows need, not an administrator.
    • Orchestrator lock timeout. The orchestrator locks itself so that only one run happens at a time. The default is 30 seconds. If you have long running tasks, increase this value. The orchestrator cannot run again until the lock period has passed. For example, if you set the timeout to 45 seconds and schedule the orchestrator more often than that, the extra runs are skipped until the 45 seconds have passed. Make sure your PHP execution time limit is long enough for your longest running task.
    • Development Mode. Leave this off unless you are troubleshooting issues you suspect are related to cached entity data. When on, Maestro resets the entity cache before it fetches a queue, process, assignment and so on.
    • Watch this video to understand the orchestrator's output and how to test for proper operation: https://www.youtube.com/watch?v=903PUH15_HU
    • Maestro URL Tokens. When a key is provided in "Provide a site-wide token key for use in the URL as the key in a key-value pair", Maestro generates a unique token value for each task in the queue and uses it in interactive task URLs instead of the queue ID and process ID.
    • Zero-User notification mechanism. Allows developers to notify people outside of Drupal and lets flow builders assign tasks to roles that have no Drupal users. See the Maestro API page.
    • Maestro Trace Archive (only when the Trace Archive module is enabled). Sets how long before and after snapshots are kept. See the Tracing and Debugging Workflows page.
  5. If you use the Diagram.js builder, review its settings at /admin/config/workflow/maestro_template_builder. The pan/zoom save delay controls how long the builder waits after you pan or zoom before saving the view (minimum 500, default 1500 milliseconds). The ReactFlow builder needs no configuration.

  6. After updating Maestro, always run database updates and rebuild caches:

    drush updb
    drush cr

Getting Started

  • If the core Toolbar module is enabled, Maestro adds a Maestro menu with the most common links, including the user's Task Console. You can also place the Tools menu block in a region.
  • View and manage workflow templates at /maestro/templates/list (also available under the Structure menu). Each template row has operations to open it in the React Editor (ReactFlow builder) or the Task Editor (Diagram.js builder), depending on which builders are enabled.
  • Enable the Maestro Form Approval Flow Example module. It is a simple, all-inclusive workflow that provides a template, content type, users, roles and permissions for a simple form approval.
  • Users access their tasks via the Task Console at /taskconsole.

Provided Views

  1. Outstanding Tasks: shows all currently active interactive tasks that require user interaction, plus batch tasks that have not yet completed, including any task the orchestrator is in the process of executing.

    • Exposed filters for task name and process name.
    • Links to trace the workflow process and to reassign the task owner.
  2. All Active Tasks: shows all currently active tasks, including conditional (IF) and batch tasks.

    • Exposed filters for task name and process name.
    • Links to trace the workflow process and to reassign the task owner.
  3. All Flows: lists workflow processes with expandable process details, a "Process Name contains" filter and a Template filter.

  4. Maestro Views-based Task Console: a Views-based task console (Maestro 4.1 and above).

    • Initially disabled, with permissions assigned to administrators.
    • Site builders can use it as a base for custom task consoles.

All of these Views use Views AJAX for sorting, filtering and paging, and can be customized in the Views UI.

Maestro engine, also known as the Orchestrator

The Maestro engine orchestrates the workflow. It schedules the tasks and logic defined by the workflow template, tests the result of each task as it completes, and determines which task(s) to execute next. Routing can depend on user actions such as clicking an Accept or Reject button, a process variable value, custom PHP code in a batch function, the answer from an AI Task, and more.

  • The orchestrator needs to run in the background continuously. If it is not running, tasks cannot complete and new tasks will not start.
  • Every way of running the orchestrator (the URL, Task Console refreshes, process kickoff and Drush) uses the same locking and the same "run as" account rules described above.

Modules included

Core

Maestro Engine (maestro)

  • The core engine responsible for executing workflow templates.
  • Contains all of the Maestro APIs.
  • Installs with a single example template and the Views listed above.

Maestro Task Console (maestro_taskconsole)

  • The main user interface for users to access and complete their assigned tasks.
  • Shows Task, Flow, Assigned, Stage, Actions and Details, with sortable columns, expandable details and a card layout on narrow screens.
  • Requires the Maestro Engine.

Maestro ReactFlow Template Builder (maestro_reactflow_template_builder)

  • A ReactFlow based visual workflow editor with a drag and drop task palette, minimap, zoom controls and alignment tools.
  • Adds the React Editor operation to the templates list.
  • See the Workflow Editor page.

Maestro ReactFlow Trace Viewer (maestro_reactflow_trace_viewer)

  • Sub-module of the ReactFlow builder. Adds a read-only Visual Trace that overlays a process instance's progress on its workflow diagram.

Maestro Template Builder with Diagram.js (maestro_template_builder)

  • The original visual template builder, built on Diagram.js.
  • Adds the Task Editor operation to the templates list.

Maestro Trace Archive (maestro_trace_archive)

  • Captures a snapshot of process variables and entity identifiers immediately before and after each task executes, so the Visual Trace can show what changed. Requires Maestro 4.5.1 or above.

Maestro Utility Functions (maestro_utilities)

  • Extra common use interactive and batch functions.

Additional task types

Maestro Review Task (maestro_review_task)

  • A ready made interactive task with instructions for the assignee, renameable Accept and Reject buttons, and links to the workflow's content.

Maestro Variable to Entity Identifier (maestro_variable_entity_identifier)

  • An engine task that converts an entity ID held in a process variable into a Maestro entity identifier so other tasks can work with that entity. Requires Maestro 4.3 or above.

Maestro Webform Integration (maestro_webform)

  • Provides the Webform task type. Requires the Webform module.

Maestro ECA Integration (maestro_eca_task)

  • Provides a task that fires events ECA can react to, and an ECA action to spawn a Maestro process. Requires ECA.

Maestro Tool Task (maestro_tool_task)

  • An engine task that calls a Tool API tool directly, mapping tokens and process variables to the tool's inputs and its outputs back into process variables. No AI involved. Requires Maestro 4.3 or above and the Tool API module.

AI (experimental)

Maestro AI Task (maestro_ai_task)

  • The AI Task type. Requires the AI and Key modules.

Maestro AI Task Assistant Capability (maestro_ai_task_assistant)

  • Lets an AI Task delegate its prompt to a configured AI Assistant, including the Assistant's tools and agents. Requires the AI Assistant API sub-module of the AI module.

Maestro AI Tools (maestro_ai_tools)

  • Exposes public workflow templates as Tool API tools so AI agents and assistants can discover and start workflows and check their status. Requires Maestro 4.3 or above and Tool API.

Maestro AI Task Vision Example (maestro_ai_task_vision_example)

  • Simple and complex expense receipt checking example workflows. Requires a Chat with Image Vision provider and the Webform module.

Examples

Maestro Form Approval Flow Example

  • A simple, all-inclusive workflow that provides a template, content type, users, roles and permissions for a simple form approval.

Maestro Interactive Plugin Task Example and Maestro Non Interactive Plugin Task Example

  • Stub code showing how to write your own task types for the Maestro engine.

More Information

Visit https://www.nextide.ca/blogs to read more about Maestro.

Help improve this page

Page status: No known problems

You can: