Templates and tasks make up the basic building blocks of a Maestro workflow. Maestro requires a workflow template to be created by an administrator. When called upon to do so, Maestro will put the template into "production" and will follow the logic in the template until completion. The definitions of in-production and template are important as they are the defining points for important jargon in Maestro. Simply put, templates are the workflow patterns that define logic, flow and variables. Processes are templates that are being executed which then have process variables and assigned tasks in a queue.
Once created, a workflow template allows the Maestro engine to follow a predefined set of steps in order to automate your business process. When put into production, the template's tasks are executed by the Maestro engine or end users in your system. This blog post defines what templates and tasks are, and some of the terms associated with them.
Templates:
Templates define the logical progression of a workflow pattern from a single start point to one or more end points. Templates are stored in Drupal 8 as config entities provided by the maestro module and are managed through the maestro_template_builder module. A Maestro template defines a few static and non-deletable elements:
Template machine name: The machine name of the template is initially derived from the template human-readable label, however, you can edit the machine name to suit your requirements.
Template Canvas height and width: The height and width, in pixels, of the template as shown in the template editor.
"initiator" template variable: The initiator variable appears once a new template has been saved. You are unable to remove the initiator variable. The initiator variable is set by the workflow engine when a template is put into production and is set to the user ID of the person starting the workflow. The initiator variable is helpful in using to assign tasks back to the individual who kicked off a process. You are able to edit/alter the initiator's value via the Maestro API.
"entity_identifiers" variable: The entity_identifiers variable also appears once a new template has been saved. You are also unable to remove the entity_identifiers variable. entity_identifiers is used to store any entities used by the workflow in a specific format. As an example, the Content Type Task uses the entity_identifiers variable as a means to store the unique IDs of content created and also to fetch that content for later use. The format of the variable is as follows: type:unique_identifier:ID,type:unique_identifier:ID,... Where 'type' is the type of entity. For content type tasks, this is set as the actual content type machine name (e.g. article). 'unique_identifier' is used to give each piece of content a unique ID used in the engine and task console to pick off which of the entities it should be actioning upon. 'ID' is the actual unique ID of the entity where in the Content Type Task's case, is the node ID. While this may sound confusing, it's simply a list of entities which are used in the workflow. As a workflow designer, you do not have to use the entity_identifiers to store unique IDs -- you can create and use variables as you see fit.
Start Task: When a template is created, a Start task is automatically generated. This task is a non-deletable task and always has the machine name of "start". The workflow engine will always begin execution of a process using the 'start' task (unless you specify via an API spawned process otherwise).
End Task: Although deletable, the end task is generated automatically when a template is created. A template can have multiple end tasks and as such, the end task is deletable and can be added back in to a template.
Template Variables:
Already noted in the Template section above, the initiator and entity_identifiers variables are created by default for each template. These variables are used primarily by the engine and tasks to store important information about what is going on in the execution of the process. As a workflow administrator, you can create template variables that can be used by your workflow application to assign tasks to users or roles or to make logical branching determinations based on values.
You can create any number of template variables and assign them a default value. It is advisable to set default values to avoid logic issues in your workflow when testing for specific values. Each time your template is put into production, the variables you've created on the template are created in the process. Process variables and their values are used by the workflow engine for assignment or logic branching. It is up to you to determine how best to use the variables.
Tasks:
Tasks are used on Templates and are either assigned to actors in the workflow (called Interactive Tasks) or are executed by the Maestro engine (called Engine Tasks). The following list of tasks are shipped with Maestro D8:
Start Task: Automatically created by the engine for each template and is non-deletable. This task must be present for a workflow to function.
End Task: You can have any number of End tasks on your template, however, you must at least have one end task in order for your template to be validated for production usage. The end task is responsible for ending a workflow and properly signalling the engine to close off the process and set the appropriate flags. If you terminate a non-end-task-terminated workflow branch by having no other tasks after it, the process will never be flagged as complete and archivable. In such a scenario, the process will appear to never complete.
And Task: Logical AND. This task takes multiple branches of a workflow and ANDs them together, meaning that the flow of the process will HOLD at the AND task until all tasks that point to the AND are complete before continuing execution.
Or Task: Logical OR. This task takes multiple branches of a workflow and ORs them together, meaning that the flow of the process will NOT hold at the OR task. The OR is used to combine multiple branches of a workflow together into a single serial point of execution.
Batch Function: The Batch Function task allows you to create a function that will be executed by the engine. This is a non-interactive task and requires that the batch function return a TRUE in order to signal the engine that the task has completed.
Content Type Task: The Content Type task provides an interactive task to the user to fill in a content type and have the content attach itself to the workflow via the "entity_identifiers" variable. The Content Type task requires the administrator to attach a unique identifier to the content so that the content can be referenced in the workflow across multiple content type tasks.
If Task: The If task provides logical branching based on the status of the last executed task preceding the IF, or based on the value of a variable. The IF task provides a TRUE and a FALSE branch and is the mechanism used to generally cause a logical loop-back condition.
Interactive Task: The Interactive task is a user-executed task that is generally run as a modal dialog in the Maestro Task Console. Interactive tasks are completely customizable by the workflow developers to present whatever type of information is required to the end user. Interactive tasks will only complete when an end user assigned to the task completes it. The workflow will not continue until such time.
Manual Web Task: The Manual Web task is used to redirect the user to a different Drupal page, or even an external page from the workflow application. The redirection to a page is done in the Maestro Task Console and provides the Maestro Queue ID (queueid=xxxx) as a parameter in the URL when redirecting to the page. It is 100% up to the manual web task's ultimate endpoint to complete the task via the Maestro API. The workflow will not continue until the Manual Web Task's endpoint has completed the task.
Set Process Variable Task: The Set Process Variable task (SPV) is used to set the value of a process variable either though a hard-coded value, adding or subtracting a value from the variable, or by specifying a function to fetch data with.
Maestro's API in conjunction with the power of Drupal 8's underlying structure means that if a type of task that you require is missing, one can be written. Examples of both interactive and non-interactive tasks are shipped with Maestro.
Nextide provides consulting and support services for all of your workflow needs. Contact us today with your project requirements!
