This is part 4 of the Maestro for Drupal 8 blog series, defining and documenting the various aspects of the Maestro workflow engine.  Please see Part 1 for information on Maestro's Templates and Tasks, Part 2 for the Maestro's workflow engine internals and Part 3 for information on how Maestro handles logical loopback scenarios.

Expanding on my blog about Maestro's Tasks, this post is to help clarify the usage of some of the options in the task editor for interactive tasks.  Interactive tasks present the actor assigned to a task defined in the workflow template with an interface that allows them to "interact" with the workflow and complete the task.  Interactive task types are human-executable tasks, therefore the workflow's progression through a template will be held up by incomplete (not executed) interactive tasks as the workflow is waiting for human intervention to complete it.  The Interactive (Function*) and the Content Type Task are the two interactive task types included with Maestro.  The differences between the Interactive (Function*) task type and the Content Type task type are as follows:

• Interactive Function task types allow the workflow administrator to configure the task to show the end user a specific task completion interface when clicked on in the task console. The task completion interface is a function written in a Drupal module.
• Content Type task types allow the workflow administrator to configure the task to show an existing content type for editing in the task console.

(* - In the Maestro interface, the Interactive Function task type is simply called an "Interactive Task".)

For all Interactive Task Types: Assignment Details

Interactive, or human executable tasks, are assigned one of two ways.  Via a fixed value or via variable.
 

As shown in the image, when assigned by a fixed value, you will have the option of assigning to a user or role out-of-the-box.  The assignments are then shown in the table where the assignment to what, by and who is assigned are shown.  Assignments by fixed value means each time the task is created in the queue for execution, those users or roles will always be assigned.  There can be no deviation from assignment when done by fixed value unless assignments are altered manually or via the APIs.

Assignment by variable allows the administrator to assign a task to a user or role (out of the box) based on the value stored in a template variable.

The assignment by variable produces dynamically assigned workflows where assignments are done based on inputs into the workflow, stored in variables, which can be unique every time the workflow executes.  Assignments to users or roles are supported out-of-the box.  Assignments to users or roles are done via the user account name or role name.

For all Interactive Task types: Notification Details

Similar to assignments, notifications can be done by fixed value to a role or user, or by variable to roles or users.  

There are three notification types:

1. Assignment
    When a task is assigned, a notification email is sent to the assigned actor or role with an assignment message.  You can customize the assignment message.

2. Reminder
    Based on the "Reminder After (days)" input field, a reminder notification email will be sent to the assigned actor or role.  The message is customizable as well.

3. Escalation
    Based on the "Escalation After (days)" input field, an escalation notification email will be sent to the assigned actor or role.  The message is also customizable.

Edit Options

Interactive (Function) tasks:

The Interactive Function task allows workflow admins and developers to create custom UIs for their workflows.  

Out-of-the-box, the Interactive Task has a simple Accept or Reject set of buttons.  In our Form Approval workflow example (example module included with Maestro), we have a customized modal manager-approval Interactive Task which shows the actor the submitted form from the user.  The "Handler" field is where you would specify the function you wish the Task Console to use to show the assigned actor their completion options.

In the image shown, the handler field is filled in with a function name.  When filled in, Maestro hands off the creation of the Interactive Task's user facing UI to the function listed in the Handler field.  When left blank,  Maestro defaults to a simple Accept/Reject button UI.

The "Return Path" option specifies where to redirect the user to after completion.  By default this is set to "taskconsole", which means that the task will redirect to the url "/taskconsole" after completion.

The "Task presentation" drop down gives you two options:  Modal or Full Page.  The Modal option will pop up the task's user facing UI in a modal dialog window, whereas the Full Page option takes the user to a full page rendering of the handler.

Content Type tasks:

The Content Type task, when executed from the task console, directs the assigned user to the edit page of a content type.

The editable options begin with "Content type".  In this field you enter the machine name of the content type you wish to show the user.  In our Form Approval example workflow, we've created a content type with the machine name of "approval_form" as shown in the image.

"Give this piece of content a unique identifier" option is critical for the operation of the task.  In any given workflow, you can have many types of content associated with the flow.  In fact, you can attach multiple different instances of the same content type to your workflow.  Therefore, Maestro needs to know which specific piece of content you wish to present to the user.  In our example image, we have "request" as the unique identifier.  We could have another Content Type task later in our flow that uses the same unique identifier in order for Maestro to show THIS specific piece of content to the end user.  In your workflow, you can have a second Content Type task that has a different unique identifier with the same content type, and that will inject a second unique piece of content into the workflow to manage.

The "Show a Save and Edit Later button..." option will show a "Save and Edit Later" option on the bottom of the content type.  The button allows users to fill in the content, saving it, but not completing the content type task.  The task will remain in their console until such time they save and complete the task.  Keep in mind, holding an interactive task uncompleted in a task console means the workflow after the task is stalled until completion.

"Return Path" is functionally identical to that of the Interactive tasks's Return Path option.  In our example, Maestro will redirect back to /taskconsole.