Maestro ECA Task Module and ECA Actions

** The Maestro ECA Task and Actions module is available only in the 4.x and above version of Maestro

Overview

The Maestro ECA Task module provides the ability in Maestro to easily create an ECA entity-aware Custom Event which you can use in ECA to perform ECA-related actions upon.  The Maestro ECA Task module also contains an ECA Action which allows you to spawn a Maestro Template, passing an entity from ECA directly into Maestro's Entity Identifiers.

For example, you have a Maestro gated workflow process using a node where

• The node is unpublished at creation time
• Once the gated review process is complete, the node needs to be published
• You wish to manage the content process with low to no code

In the example above, you can use the Maestro ECA Task to fire the ECA Custom Event, passing the node into ECA for you to publish it via ECA Actions.  No code required.

Dependencies

In order to use the Maestro ECA Task, you'll need to have the ECA module installed (https://www.drupal.org/project/eca). During the installation process, the Maestro ECA Task will install a Maestro Template demonstrating how to fire an ECA Event and will also install a BPMN.IO model to show how to intercept that event and action upon the node created in Maestro.

Task Configuration

The Maestro ECA task is simple to configure with only a few options.

• Label of the task - The label that appears in the Template Builder.
• Participate in Setting the Workflow Stage and Status Message - Core Maestro functionality.  See task documentation.
• Entity Identifier Source - Manual Entry or Process Variable are the options.  In order to pass an entity FROM Maestro TO ECA, Maestro needs to know about it.
• Entity Identifier (Manual Entry) or Select Process Variable - Depending on the Entity Identifier Source, you will have to either type in the entity identifier you wish to use or select a process variable.  If the identifier is stored in a Process Variable, the variable you choose will hold the identifier.  In the example above, we've used the manual entry option and filled it in with the entity identifier of "submission".  That means our workflow template should have an entity identifier called "submission" created in a task, programmatically created, or via a Webform Submission Handler.  The Entity Identifier can be anything so long as it references an actual entity in your process.
• Event ID - This is the custom ECA Event ID we use when firing the Custom ECA Event.  This allows you to customize your ECA models to listen for ONLY those events which come from Maestro.  This is shown in the BPMN.iO model example.

When the Maestro ECA Task executes, the Custom ECA entity-aware event fires, identified by the Event ID and sending along the entity referenced by the Maestro Entity Identifier for use in an ECA Model.

ECA Start Event Configuration

Trapping the ECA event is simple.  Shown below is the BPMN.iO model editor configuration for how to listen for a Maestro event.

What we have shown above is how to configure your start event to listen for Maestro events.

• Use the ECA Custom Event (entity-aware) template.
• The Custom properties has an Event ID option. That option's value must directly match the Event ID field in your Maestro ECA Task configuration as shown above.

With that simple setup, you can now use ECA to run any applicable action on the entity that was originally managed by Maestro.

Please note:  

YOU are responsible for knowing what type of entity it is that you are managing.  For example, if you have a Webform Submission in your Maestro Entity Identifiers, you can't use an ECA-Drupal core node Publish Action on it.  You will get an error.  This is not a Maestro error, this is a fundamental mixing of entity types and trying to perform an action upon an entity that doesn't support that mechanism.

ECA Spawn Maestro Workflow Configuration

Maestro ECA Task module provides a Spawn Maestro Workflow ECA Action.  You can find it in the Action list once you've installed the module.  Shown below is an example configuration:

• The Template is Maestro: Spawn Maestro Template found in the Actions listing in ECA
• Spawn with Maestro Template - Choose the Maestro Template you wish to spawn.
• Maestro Entity Identifier - Optional.  When you fill this field in, you will send the entity (configured later in the form) into the Maestro Process referenced via a Maestro Entity Identifier using the configured ID here.
• Maestro Process ID ECA Token Name - Optional.  Need to use the process ID of the process spawned by this Action later in your model?  The token name you enter here will hold the process ID of the spawned process.  You use the token in your ECA model like this: [your_token_name]
• Entity - This is the token name for the entity you wish to send INTO Maestro.

Examples Provided

When you install the Maestro ECA Task module, you'll get the Maestro-ECA Example Template installed.  Looking at that template, you will see the following:

This is a simple flow to highlight how to use the Maestro ECA Task.  It is not meant to be the only way to use Maestro and ECA, rather it's showing you how you can easily configure Maestro to integrate with ECA (and vice versa as will be shown in the ECA model).

If you have the BPMN.iO ECA modeller module installed, you will see a new model created.

The model is disabled by default to keep it from executing.  You will have to enable the model to have the full example run.

What this example ECA model does is it detects the Maestro ECA Event configured in the Maestro Template and will

• Publish the content entity
• Spawn a Maestro workflow and insert a Maestro Entity Identifier into the process with a unique ID of "node_submission"
• Once the flow is spawned, a Drupal log entry will trap the process ID created

Run the Example

Depending on how you've configured Maestro to run the orchestrator, you'll have to have the orchestrator running to use the example template.  Refer to our orchestrator documentation.  You must enable the "Maestro Example: Publish Content" ECA Model.

• Spawn the flow from the Maestro Template Builder interface
• Once started, go to the task console and you should have a task waiting for you to execute. It is a content type task that gets you to create an "article".
• Note:  If your site does not have an article content type, you can edit the Maestro ECA Example template's "Add Content" task and change the content type to any one of the types you have in your system.
• When you execute the content type task, you will see a regular node-add page.  Create the content type.  However, you can set the Published flag to Unpublished, as the ECA model we installed will publish it for us.
• Save the content and you should be returned to your task console.
• If you've configured Maestro to run the orchestrator on Task Console refreshes, then refresh the task console a few times. This will run the ECA Task and finally the END task. Otherwise, let the orchestrator run on its own or use the Maestro Admin Menu to run the orchestrator manually.

What you should notice is the following:

• The node you created that was originally unpublished should now be published.
• Your task console should now have 2 new tasks created from the Simple Parallel to Serial workflow in it.
• If you look further into the Simple Parallel to Serial process via the Outstanding Tasks view and Trace the process, you will see an entity identifier called "node_submission" that has the node you created attached to the Entity Identifiers.

While the Simple Parallel to Serial workflow does not use entity identifiers, it was used as a base flow to simply demonstrate how we can use ECA to spawn a flow and pass entities into Maestro.