Installation

Installation:

1) Copy/upload the maestro module to the modules directory of your Drupal installation.

2) Enable the three (3) main maestro modules:

• Maestro Engine
• Maestro Task Console
• Maestro Template Builder

   More info below on the included modules

3) Set up user permissions. (/admin/people/permissions)

• ​Grant access to the task console for any users that will be assigned workflow tasks.

4) Go to the Maestro Engine settings here: /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, your going to want to have 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 are trying to run Maestro's engine without an orchestrator token. 
• YOU MUST set the value to valid string, it needs to not be empty. Set the token to something that can be called via some sort of URL calling mechanism (wget, CRON, PowerShell Script etc.).
• The resulting URL to crank the Maestro Engine that will be called when you set a token is: http://site_url/orchestrator/{token} - without setting the token, your setting for running the orchestrator on Task Console refreshes will also fail.  For example, if you set your token to "abcdefg" in the Maestro configuration screen, your Orchestrator url would be http://site_url/orchestrator/abcdefg.
• You are able to set an orchestrator lock timeout value.  The orchestrator performs a lock on itself to restrict its execution to one-at-a-time.   By default this is set to 30 seconds.  However, if you have long-running orchestration tasks, you may find that the orchestrator needs to lock itself for longer periods of time.  Increase this value in seconds to your desired lock timeout.  The orchestrator is unable to run until the lock timeout period has passed.  For example, if you set the timeout to 45 seconds, and you've scheduled the orchestrator to run more frequently than 45 seconds, the orchestrator will be locked out from running again until the 45 seconds have passed.  Please note: you should also ensure your PHP execution time limit matches that of your longest running task to ensure that you're not hitting a PHP timeout.  Your site administrator may have disabled the ability to set a maximum PHP execution time limit. 
• Enable Development Mode.  Please leave this option off unless you are troubleshooting issues which you suspect may be related to cached Drupal entity data.  By default, Maestro uses the Drupal entity system to read/write data to/from.  If you've manually adjusted data, those changes may not be picked up without resetting the Drupal cache.  Enabling Development Mode simply does an entity cache reset prior to fetching of a queue, process, assignment etc.
• Please 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 configuration.  This section allows you to configure the Maestro site-wide token.  When a token key is provided in the "Provide a site-wide token key for use in the URL as the key in a key-value pair" config option, Maestro will generate a unique token value as a representation of the task in the Maestro Queue.  The token created will be used in interactive URLs rather than the task's Queue ID and Process ID identifiers.
• Enable Zero-User notification mechanism. The zero-user notification mechanism allows Maestro Developers to write code to notify external-to-Drupal actors of a flow and allows flow builders to create workflows which are assigned to roles which have no Drupal users.  This may sound unusual, however, if your workflow relies upon people interacting with interactive tasks who are not Drupal users, this option being checked will enable Maestro developers to create custom notification routines.  Please see more on this option in the Maestro API section.

5) Go to the Maestro Template Builder settings: admin/config/workflow/maestro_template_builder

• Review the location of the library used for the visual workflow editor.
• Maestro uses the Raphael JS library to create the SVG graphics and the object handling libraries for the drag and drop functionality.
• By default on installation, the module loads the library from: //cdnjs.cloudflare.com/ajax/libs/raphael/2.2.7/raphael.js

Getting Started:

• The core "Toolbar" module if enabled will add a new Maestro menu with the most common links to the main maestro tools including the users Task Console. Optionally you can add the Tools menu block to a region.
  
• Use the Maestro Template builder /maestro/templates/list to view the workflow templates and to add/edit the templates can also be accessed under the Structure menu.
• Enable the 'Maestro Form Approval Flow Example' module. It's a simple, all-inclusive workflow that provides a template, content type, users, roles, permissions for a simple form approval.
• Users access their tasks via the Task Console /taskconsole

Provided Views:

1) Outstanding Tasks: View: Shows all the currently active interactive tasks that require user interaction. This shows tasks that are assigned to users and batch tasks that have not yet completed. It will show any task the orchestrator is in the process of executing.

• Provides two exposed filters that allows you to filter by process name or task name
• Provides links to Trace this instance of the workflow process and re-assign the task owner

2) All In Production Tasks: Shows all the currently active tasks including conditional (IF) and Batch tasks.

• Provides two exposed filters that allows you to filter by process name or task name
• Provides links to Trace this instance of the workflow process and re-assign the task owner

3) Maestro Views-based Task Console: A views-based task console available in Maestro version 4.1 and above.

• Uses views to create a task console.
• View is initially disabled and permissions assigned to administrators.
• Site builders can use this view as a base to build out custom task consoles via views.

Maestro engine, also know as the Orchestrator:

The Maestro engine orchestrates the workflow which is responsible for scheduling the tasks and logic defined by the workflow template. It does far more then just assigning the next workflow task. It will test the result of each task as they complete and determine what the next task is to execute. Workflow templates include conditions so there can be different tasks to setup as the next task depending if a user approved a form for example. The workflow routing can depend on different user actions such as clicking an Accept or Reject button, a template variable value, custom php code in a batch function etc. Maestro is very flexible.

• The orchestrator needs to run in the background continuously and if it's not running then a task can not complete and new tasks will not start.
• Maestro and the Orchestrator have been refactored for Drupal 8 and as of the Beta release, has no upgrade option (yet) from Drupal 7.

Modules included:

Maestro Engine (maestro)

• This is the core engine to Maestro responsible for execution of the engine templates. 
• Contains all of the Maestro APIs.
• Installs with a single example template.
• Installs with two Views for outstanding tasks and all in-production tasks.

Maestro Task Console (maestro_taskconsole)

• The main user interface for users to access their assigned tasks.
• Users can view their assigned tasks and their provided actions
• Requires the Maestro Engine to be installed.

Maestro Template Builder (maestro_template_builder)

• Main administration interface to view and edit the workflow templates
• Provides a SVG-based visual template builder.
• Requires the Maestro Engine to be installed.
• Only required to edit workflow templates.

Maestro Utility Functions

• Extra common use interactive and batch type functions

Maestro Form Approval Flow Example

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

Maestro Custom Task Type Examples:

• Maestro Non-Interactive Task Example
• Maestro Interactive Task Example
• Both these modules provide stub/base code for how you would write your own task type for the maestro workflow engine.

Maestro AI Task:

• Available in Maestro 4.1 and above
• Includes the Maestro AI Task type and two example workflows.

More Information:

Please go to http://nextide.ca/blogs to read more on Maestro for D8.