Maestro API

Please refer to the maestro.hooks.api.php file in the root of the Maestro module's code for a listing of all hooks available.  Maestro and the bundle of modules it's shipped with makes use of a great deal of the available hooks.

All interactive and batch functions will be passed the process and the engine queue identifier or a site-wide token so you can interact with the Maestro Engine via the APIs.  Please refer to the site-wide token explanation later in this document. 

Retrieve the workflow instance content tracking identifier:
Example of retrieving the entity_id for the content being tracked by the Unique Identifier in your workflow called 'submission'. If a valid entity_id is returned then you can load the entity using the Drupal function or the contrib module's function. Refer to https://www.drupal.org/docs/8/modules/maestro/content-type-task for more information on the Unique Identifier and configuring content type tasks.

$sid = MaestroEngine::getEntityIdentiferByUniqueID($processID, 'submission');

if this was a webform submission, then you could use:

if ($sid) {
  $webform_submission = \Drupal\webform\Entity\WebformSubmission::load($sid);
  // Retrieving a field value from the webform submission.
  if ($webform_submission) {
    $email = $webform_submission->getElementData('email_address');
  }
}

Retrieve a process variable:

$quote_type = MaestroEngine::getProcessVariable('type_of_quote', $processID);

Set a process variable:

MaestroEngine::setProcessVariable('quote_submission_username', $email, $processID);

Complete a task and set it's status:
Example use is in a custom interactive function where you have a cancel or reject button that you want to test for successful completion or not with an IF task to route the workflow refer to https://www.drupal.org/docs/8/modules/maestro/if-task for more information.

MaestroEngine::completeTask($queueID, \Drupal::currentUser()->id());
MaestroEngine::setTaskStatus($queueID, TASK_STATUS_CANCEL);

Set the name of the displayed workflow instance name:
Use this to have a custom workflow name appear in the task console.

MaestroEngine::setProcessLabel($processID, $quote_type . ' Insurance Quote For ' . $email);

Launching a new workflow with the template name:
This API will return the process id for the newly launched workflow.

$maestro = new MaestroEngine();
$processID = $maestro->newProcess('my_template_name');

Or 
$processID = MaestroEngine::newProcess('my_template_name');

Maestro Site-Wide Token

The Maestro site-wide token value configured in the Maestro Admin settings will automatically generate a token value representation used in URLs.  The site-wide token eliminates passing process and queue IDs in the URL and allows URLs to obfuscate the internals of Maestro.

Maestro Site-wide token configuration found in the main Maestro Engine Module Settings page.

For example, if you entered in the value above in the Maestro URL Tokens section, the URL used for things like the editing feature of a content type task will look like:

http://yoursite/node/add/approval_form?maestro=1&maestro-sitewide-token=TDd5maoWsQNA9U19AyvKErd-6sCHrykyjK97wHZus3Q

As you can see, the URL will contain a key called "maestro-sitewide-token" with an obfuscated value that represents the queue ID of the task in question.

Without setting a site-wide token, the URL would look like this:

http://yoursite/node/add/approval_form?maestro=1&queueid=145

As you can see, the site-wide token does not appear, but rather the internal queue ID for the task does.

If you wish to fetch and use the site-wide token in your code to transpose the token into a queue ID, you can use the following code:

$config = \Drupal::config('maestro.settings');
$sitewideToken = $config->get('maestro_sitewide_token');
if($sitewideToken != '') {
  $tokenValue = \Drupal::request()->query->get($sitewideToken, '');
  $tokenValue = \Drupal\Component\Utility\Html::escape($tokenValue);
  if($tokenValue != '') {
    $tokenQueueID = MaestroEngine::getQueueIdFromToken($tokenValue);
  }
}

Once executed, $tokenQueueID will hold the queue ID for the task in question.

Zero-User Notification and Hook

The Zero-User Notification Hook can be enabled and used for workflows that require external-to-your-site involvement by users.  Admittedly, this is not a beginners workflow concept.  The notion of zero-user notifications can be nebulous and is only meant to support very specific enterprise-level workflow scenarios.

Consider the use case where you have a workflow that needs to assign a task to and notify a workflow actor that is not a user in your Drupal database. For example, a workflow that needs to interact with a 3rd party individual who does not have a Drupal login and does not have any need to be given access to your site.  This individual can be completely random and there would be no way to pre-create this user in your Drupal database.  All you need from this 3rd party is some information filled in a Webform or Interactive Form task.  It would be impossible to create discrete users in your Drupal site and maintain those users for the off-chance that they may interact with your workflow. 

In this use case, your task's notification would be configured to notify a Drupal role that has no users assigned to it.  Maestro detects this scenario during the Maestro Orchestrator's task generation engine routine.  If you enable the zero-user notification mechanism in the Maestro settings, you can then write your own code to send a notification to a 3rd party and even provide them with a link to the task for execution (provided you configure your Drupal permissions properly!).

Referring to the Site-wide Token configuration picture above, the zero-user hook is configured in conjunction with the token.  You can only enable the Zero-User hook when there is a token for security reasons as we do not want to reveal queue IDs to non-Drupal or non-Maestro users.  In future releases, Maestro will only use a token to identify a task in URLs and these options will be enabled by default.

The Maestro Engine runs the following piece of code when detecting a zero-user notification scenario:

if($config->get('maestro_token_zero_user') == 1) { //This can only be set if the token key has been set.
  //Developers can fetch the Queue Token via the Maestro API in their hook.
  Drupal::moduleHandler()->invokeAll('maestro_zero_user_notification', [$templateMachineName, $taskMachineName, $queueID, $notificationType]);
}

This produces a hook that looks like:

function hook_maestro_zero_user_notification($templateMachineName, $taskMachineName, $queueID, $notificationType) {
  //Do things like look up the token from the queue and create a customized URL for the outgoing notification.
}

Here is an example of how you would use this hook to notify someone outside of your Drupal environment by detecting the task type and notification type of "assignment".  The sky's the limit as far as what you can do with this hook for task assignment notification.  This is a simple example of detecting that this was a webform task type and that we are doing an "assignment" notification.  In this fictitious example, somewhere during the flow execution, a process variable was set with a CRM contact.  We then look up the email of that contact and we can then use the Drupal Mail API to send the task to the non-Drupal user.

/**
 * Implements hook_maestro_zero_user_notification().
 */
function example_maestro_webform_maestro_zero_user_notification($templateMachineName, $taskMachineName, $queueID, $notificationType) {
  // This only fires with a ZERO user-count on notifications.  Use this as you see fit.
  if($notificationType == 'assignment') {
    $templateTask = MaestroEngine::getTemplateTaskByID($templateMachineName, $taskMachineName);
    if($templateTask && $templateTask['tasktype'] == 'MaestroWebform') {
      //This is very rigid in only detecting the Maestro Webform task.
      $processID = MaestroEngine::getProcessIdFromQueueId($queueID);
      //example of Fetching a non-Drupal user's information from a CRM
      //This process variable was set somewhere else in the workflow and is completely dynamic
      $crm_person = MaestroEngine::getProcessVariable('crm_contact', $processID);
      $person_email_to_notify = CRM::look_up_customer_email($crm_person);

      //Use Drupal APIs to notify $person_email_to_notify as you see fit.
      //Use the Maestro APIs to generate the task URL for the $templateTask and send that to the 3rd party.
...
...
...
    }
  }

}