Batch Function

Batch functions are extremely useful for carrying out programmatic events during a Maestro process flow. We often need the ability to execute code at some point in the workflow to improve the automation. This may be to look up information from the local site or a remote site. A batch task can be a single line of code, or a complex function. It can even be a background process that needs to pause the workflow for days until a specific state is reached. Until the batch task returns a TRUE result, the workflow engine will continue to execute the batch function every time the orchestrator runs. You would not want to have a long running piece of code but you could implement the Drupal queue API or some other batch processing API so that all you do is check for completion status in the batch function code.

Provided in this section, is an example of a batch function to publish a node. 

Configuring the Batch Function Task:

In the Template Builder, add a new task of type Batch Function to your workflow. Once it's added, click on the Edit menu icon on the top left corner of the task. You should see the available batch function names in the handler fields as you start to type. Once one is selected, you will see the help or description appear just below the handler field. This help text is defined for the selected function in your modules use of hook_maestro_batch_handlers.

Maestro ships with a few “bare bones” functions, however the addition of new functions are as simple as hooking in to Maestro and creating your own handler. Here’s how:

Defining a new Batch Function:

You will need somewhere to place your code. I would suggest not using any of the Maestro core files for this as any updates to Maestro will most likely overwrite those files and you’ll lose your code. The best approach is to write your own custom Drupal module so that you can easily maintain your own custom codebase.

In your module, first you need to tell the Template Editor about your new Batch Function so the auto-lookup for handlers can show it as an option when your defining the handler for the Batch Function task. You need to implement HOOK_maestro_batch_handlers and return an array of function names and function descriptions. You can return as many as you need - this is an example of just one.

/**
 * Implements hook_maestro_batch_handlers
 */
function my_module_maestro_batch_handlers() {
  return [
    'my_module_publish_node' => t('Publish a content node.'),
  ];
  //return $handlers;
}

Now, add your function - in my case, let's create one to publish a node. The node id will be set in a process variable we added to the template called nid. All batch functions pass in the process_id and the queue_id so you have both the ID of the overall active process and the id of this individual task, known as the queue_id in the maestro engine. We will use the Maestro API to retrieve the tracked entity and then load the node, set it's status to published and save the updated node.

function my_module_publish_node($processID, $queueID) {
  if($nid = MaestroEngine::getEntityIdentiferByUniqueID($processID, 'nid')) {
    $node = \Drupal\node\Entity\Node::load($nid);
    $node->setPublished(TRUE);
    $node->save();
  }
  return TRUE;
}

Maestro tracks content created with the Content Type task or the Webform Task in the maestro_entity_identifiers table and you can retrieve the linked content (node in this case), using the maestro API, knowing the processID.

Final step is to return TRUE to tell the maestro engine that this task is now complete. If you don't return TRUE, then task (batch function) will be executed every time the engine runs. This can be what you want or not, there are cases where you may have a long running operation or you need to pause a workflow until a specific state or action is completed.