Workflow Editor

The Template Builder, also called the Workflow Editor, is where workflow administrators spend most of their time. It is the Maestro UI for adding and editing workflow templates.

Maestro ships with two visual builders. Both edit the same workflow templates, so you can enable either one or both:

• Maestro ReactFlow Template Builder (maestro_reactflow_template_builder): the newer editor, built on ReactFlow. It has a drag and drop task palette, a minimap, zoom controls and tools to align and distribute tasks. Open it with the React Editor operation on the templates list.
• Maestro Template Builder with Diagram.js (maestro_template_builder): the original editor. Open it with the Task Editor operation on the templates list.

In both builders, the task edit screens are native Drupal forms, and templates must be validated before they can be put into production. The validation routine makes sure each task has the fields and task pointers it needs so the template runs as error free as possible.

Add a new Template

Click the Add Template button on the template listing page, /maestro/templates/list. All that is needed at this point is a label (name) for your workflow template.

When you save the form, default process variables are created. One is called initiator and is set to the user ID (uid) of the user that launches the workflow. Assigning interactive tasks to initiator is common during initial development so you don't have to keep switching users to test; all the tasks will be assigned to you. In practice, you will still use this variable frequently for assigning interactive tasks. The other default process variables control the visual status bar that shows which stage a workflow instance is at within the overall process. The number of stages, the current stage and the message for the current stage can be controlled in code, and each task's stage settings are configured in the template builder.

The ReactFlow Template Builder

From /maestro/templates/list, choose React Editor from a template's operations. The editor fills the browser window below the page header, and the canvas pans and zooms on its own without scrolling the page.

Toolbar links

Above the canvas you will find links to go back to the templates list, run a validity check and edit the template settings. If the template has not been validated, a reminder is shown. If the template has open processes, a warning is shown, because changing a template while processes are running against it can cause execution problems.

Adding a task

Every available task type is listed in the task palette on the left side of the canvas, each with its own shape and colour. Drag a task type from the palette and drop it where you want it on the canvas. The task is created at that spot and saved to the template immediately. Then open its menu and choose Edit Task to configure it.

You don't need to configure tasks right away. You can add and arrange tasks to sketch out the process using task names, then come back and configure each one.

The task menu

Each task has a small menu button at its top left corner. Click it to open the actions available for that task type:

• Edit Task: opens the task's configuration form.
• Draw Line To: click this, then click the target task to connect the two. Click an empty spot on the canvas to cancel.
• Draw False Line To (IF tasks): the same as Draw Line To, but draws the red FALSE branch.
• Remove Lines: removes the lines connected to this task so you can reconnect it.
• Remove Task: deletes the task after you confirm. The Start task cannot be removed.

Only the actions that make sense for a task are shown. For example, you cannot draw a line from an End task.

Task details on hover

Task labels longer than 13 characters are shortened on the canvas. Hover over a task to see its full name, its task ID, its type and its workflow stage and status message, if set.

Moving, aligning and distributing tasks

• Drag a task to move it. Tasks snap to a 5 pixel grid, and the new position is saved as soon as you let go.
• Hold Ctrl (Cmd on macOS) and click to select more than one task.
• When two or more tasks are selected, an alignment toolbar appears at the top of the canvas. Align lines up the selected tasks by their left edges, horizontal centres, right edges, top edges, vertical centres or bottom edges. Distribute spaces three or more selected tasks evenly, horizontally or vertically.

Navigating the canvas

• Drag an empty part of the canvas to pan, and use the mouse wheel or a pinch gesture to zoom.
• The controls in the bottom left corner offer Zoom In, Zoom Out, Fit View and a lock button that toggles whether tasks can be moved and selected.
• The minimap in the bottom right corner shows the whole workflow and where you are in it.
• Your pan and zoom position is saved with the template, so the editor opens where you left off.

Lines

Normal lines are drawn in black and FALSE branch lines from IF tasks are drawn in red. Lines connect to the nearest edge of each task and follow the tasks as you move them.

The Diagram.js Template Builder

From /maestro/templates/list, choose Task Editor from a template's operations. Use the task menu on each task to edit it, draw lines and remove lines, in the same way as described above. Its settings page at /admin/config/workflow/maestro_template_builder has a pan/zoom save delay: after you pan or zoom, the builder waits this many milliseconds before saving the view (minimum 500, default 1500).

Next Steps

• Get an idea of the different Task Types
• Learn the common settings for Interactive Tasks
• Trace a running workflow on its diagram
• Review the doc page for each task type to understand its configuration options.