Feb 08 2019
Feb 08

Innovation within Canadian healthcare continues to provide better care experiences for those using the system.  As the population ages and strains our facilities to care for those nearing their end-of-life, hospitals are looking at technological solutions to ease the burden on emergency rooms and give people access to accurate and timely healthcare.   Nextide partnered with uCarenet, a Toronto-based e-health company, to create an innovative health and wellness application to monitor the condition of palliative care patients for a major Canadian hospital.

The Requirements:

The hospital required an application that could gather critical patient data through forms, compile the results daily, report those results to the patient’s healthcare team and alert the team in the event the results warranted intervention.  The application had to be accessible to all participants, easy to use and mimic the existing paper-based data collection mechanism the palliative care team employed. The hospital staff required administrative logins to create users and monitor the entered data in a simple-to-use and uncluttered dashboard.  Doctors and nurses should be able to determine who has symptoms which require immediate attention, and be able to view the discrete data if required.

The Solution:

At Nextide, we look at Drupal as a platform to build applications and not purely as a feature-rich content management system for websites.  We were confident that Drupal was the right selection for the application. Through careful design, our team was able to create an interactive application that gathered patient data, compiled and weighted the results based on current and historical data, and send the palliative care team notifications when warranted.

First, the palliative care user’s experience:

User's view when ability to enter data is open or closed

The image above shows two versions of the palliative care user’s home page.  The left side is the home page when they are able to complete their daily forms.  On the right, if the user completed their forms within the last 24 hours, they’re locked out of completing a new set of forms until the 24 hour window has passed.

Once daily the palliative care users are able to fill in the three required forms.  An example of one of the forms is shown here:

Showing the Brief Pain Inventory Form

On any device the patient or caregiver has, patient data can recorded using Drupal to store all form data in custom entities.  Themed form buttons and select lists are presented in easy-to-use clickable human bodies, sliders and radio buttons.

Upon completion of the patient information forms, the results are compiled according to the hospital’s predefined requirements.  The three forms have at least 50 discrete data points in total. We take the data entered, compare it to the last three to five days of the patient’s data and determine trends within those fields which require an alert being triggered.  If a user is deemed to be “alerting”, we send a notification to the healthcare team and flag the user and the fields as alerting.

The Healthcare User’s Experience:

When a healthcare user enters the system, their homepage is comprised of a simple to use dashboard.  The dashboard presents the user with an easy-to-read listing of patients with their status plainly visible.

Healthcare Dashboard

The healthcare user is able to drill into any patient’s data, giving them a graphical breakdown of the historical patient data.  The nurse or doctor is able to see the trends in the patient data and is able to take appropriate action. Healthcare users are able to acknowledge the alerts, thereby clearing the status of the patient, and they’re able to silence alarms for any given patient so they do not receive alerts for 24, 48 or 72 hours.

Drilldown into stats

We generate on-the-fly graphs of patient data.  Healthcare professionals can also drill even further into each entity where they’re able to view each form’s entry and mute any alerting fields.

Alerts panel

Themed Drupal entities give the healthcare professional a quick breakdown of patient entered values.  If a field is alerting, it’s highlighted and gives the user the option to silence the alarm by clicking on the alerting symbol.  Users are able to scan back and forth through daily entries. The interface is easy to use, uncluttered and responsive in design.


The Outcomes:

The initial pilot phase of the project had between 15 and 20 patients entering data at any given time.  In the first 3 months of the pilot:

  • 105 critical alerts were generated by the system and sent to the patients’ circle of care.
  • 46 of the 105 critical alerting patients received follow-up intervention.
  • 7 patients who had not triggered an alert received telephone intervention after the healthcare staff noticed trends in their data.
  • Saved an estimated $62 000.  That’s right!  This single application over the course of three months saved over sixty-thousand dollars in unnecessary care in the Emergency Room!

Every time a patient receives proactive care, the likelihood that they require an Emergency Room visit is reduced, thereby reducing the load on the hospital.  When you consider the small pilot size and the number of interventions required, each intervention could have eliminated a potential Emergency Room visit. A resounding success!

When you look at Drupal as “just a content management system”, you lose sight of what it really is:  a platform to produce applications that matter. At Nextide, we have been focused on Drupal since 2009. Our experience in Drupal ensures that we utilize the most effective modules to construct sites and applications that are optimized for performance and functionality. We continue to leverage Drupal in many more ways than just content management.  Our core strengths are focused on the design and build of creative sites, and web based business applications, that mirror the way people think and work. We can custom create any business function or create the ideal work environment for people to perform at their best. The capability to deliver robust custom applications to our customers allows us to deliver solutions from healthcare, to HR, and everything in-between.

Need Help?

Do you have a Healthcare initiative we can help with?

Jan 29 2019
Jan 29

Innovation within Canadian healthcare continues to provide better care experiences for those using the system.  As the population ages and strains our facilities to care for those nearing their end-of-life, hospitals are looking at technological solutions to ease the burden on emergency rooms and give people access to accurate and timely healthcare.   Nextide partnered with uCarenet, a Toronto-based e-health company, to create an innovative health and wellness application to monitor the condition of palliative care patients for a major Canadian hospital.

The Requirements:

The hospital required an application that could gather critical patient data through forms, compile the results daily, report those results to the patient’s healthcare team and alert the team in the event the results warranted intervention.  The application had to be accessible to all participants, easy to use and mimic the existing paper-based data collection mechanism the palliative care team employed. The hospital staff required administrative logins to create users and monitor the entered data in a simple-to-use and uncluttered dashboard.  Doctors and nurses should be able to determine who has symptoms which require immediate attention, and be able to view the discrete data if required.

The Solution:

At Nextide, we look at Drupal as a platform to build applications and not purely as a feature-rich content management system for websites.  We were confident that Drupal was the right selection for the application. Through careful design, our team was able to create an interactive application that gathered patient data, compiled and weighted the results based on current and historical data, and send the palliative care team notifications when warranted.

First, the palliative care user’s experience:

User's view when ability to enter data is open or closed

The image above shows two versions of the palliative care user’s home page.  The left side is the home page when they are able to complete their daily forms.  On the right, if the user completed their forms within the last 24 hours, they’re locked out of completing a new set of forms until the 24 hour window has passed.

Once daily the palliative care users are able to fill in the three required forms.  An example of one of the forms is shown here:

Showing the Brief Pain Inventory Form

On any device the patient or caregiver has, patient data can recorded using Drupal to store all form data in custom entities.  Themed form buttons and select lists are presented in easy-to-use clickable human bodies, sliders and radio buttons.

Upon completion of the patient information forms, the results are compiled according to the hospital’s predefined requirements.  The three forms have at least 50 discrete data points in total. We take the data entered, compare it to the last three to five days of the patient’s data and determine trends within those fields which require an alert being triggered.  If a user is deemed to be “alerting”, we send a notification to the healthcare team and flag the user and the fields as alerting.

The Healthcare User’s Experience:

When a healthcare user enters the system, their homepage is comprised of a simple to use dashboard.  The dashboard presents the user with an easy-to-read listing of patients with their status plainly visible.

Healthcare Dashboard

The healthcare user is able to drill into any patient’s data, giving them a graphical breakdown of the historical patient data.  The nurse or doctor is able to see the trends in the patient data and is able to take appropriate action. Healthcare users are able to acknowledge the alerts, thereby clearing the status of the patient, and they’re able to silence alarms for any given patient so they do not receive alerts for 24, 48 or 72 hours.

Drilldown into stats

We generate on-the-fly graphs of patient data.  Healthcare professionals can also drill even further into each entity where they’re able to view each form’s entry and mute any alerting fields.

Alerts panel

Themed Drupal entities give the healthcare professional a quick breakdown of patient entered values.  If a field is alerting, it’s highlighted and gives the user the option to silence the alarm by clicking on the alerting symbol.  Users are able to scan back and forth through daily entries. The interface is easy to use, uncluttered and responsive in design.


The Outcomes:

The initial pilot phase of the project had between 15 and 20 patients entering data at any given time.  In the first 3 months of the pilot:

  • 105 critical alerts were generated by the system and sent to the patients’ circle of care.
  • 46 of the 105 critical alerting patients received follow-up intervention.
  • 7 patients who had not triggered an alert received telephone intervention after the healthcare staff noticed trends in their data.
  • Saved an estimated $62 000.  That’s right!  This single application over the course of three months saved over sixty-thousand dollars in unnecessary care in the Emergency Room!

Every time a patient receives proactive care, the likelihood that they require an Emergency Room visit is reduced, thereby reducing the load on the hospital.  When you consider the small pilot size and the number of interventions required, each intervention could have eliminated a potential Emergency Room visit. A resounding success!

When you look at Drupal as “just a content management system”, you lose sight of what it really is:  a platform to produce applications that matter. At Nextide, we have been focused on Drupal since 2009. Our experience in Drupal ensures that we utilize the most effective modules to construct sites and applications that are optimized for performance and functionality. We continue to leverage Drupal in many more ways than just content management.  Our core strengths are focused on the design and build of creative sites, and web based business applications, that mirror the way people think and work. We can custom create any business function or create the ideal work environment for people to perform at their best. The capability to deliver robust custom applications to our customers allows us to deliver solutions from healthcare, to HR, and everything in-between.

Need Help?

Do you have a Healthcare initiative we can help with?

Oct 22 2018
Oct 22

NASA’s Jet Propulsion Laboratory (JPL) needed to automate an internal document approval process where any given launch of the workflow could:

  • Have unique and a varying number of approvers.
  • Abort the approval process immediately upon a single approver rejecting, even if other approvers have approved or have yet to view the document.
  • Re-route rejected documents to the initiator of the approval process.
  • Upon all assigned approvers approving the document, route the document to completion, notifying stakeholders in the process.

Using Drupal and Nextide’s Maestro workflow module, JPL was able to prototype a base workflow template to automate their process.  However, the missing element was the ability to implement a workflow that allows for on-the-fly selection of approvers, the number of approvers and managing the acceptance and rejection of the document.

 

The Issue

Maestro supports the ability to assign a single unique instance of a task to one or more users dynamically.  In this scenario a single task would be created with multiple users assigned to it, however, the first person to complete the task would complete it for everyone assigned. This produces a “one task, one user completes” scenario regardless of how many people were assigned to the task. JPL’s requirement was the need to assign a multiple number of unique instances of the same approval task to a set of users and continue the workflow past the multiple-assignee stage when all tasks are approved or a single task is rejected. 

In a standard workflow template, the workflow administrator would logically build the template accounting for the tasks required and who is assigned to those tasks. 

Figure 1 - Typical Workflow Approval TemplateFigure 1 - Typical Approval Workflow Template

To illustrate the problem, Figure 1 shows a simple (and non-functional!) approval workflow template with four approvers.  The template is like most other simple approval processes, however, JPL’s issue was that you never know how many approvers will be assigned to any given document.  In the shaded area of Figure 1, you see four tasks: Approval 1 through 4.  This is optimal if you always have four approvers.  JPL required a dynamic number of approvers, each with their own task.  What if there were five approvers required?  What if there were three?  Ten?  The issue for this use-case is that dynamic assignments and rigid templates are not the answer.

The Solution

Our solution was to get Maestro to spawn a variable number of sub-approval processes as required by the initiator.  The parent process was able to spawn as many child approval processes as required, and each child was able to signal its completion, accepted or rejected status to the parent.

Figure 2 - Our Solution TemplateFigure 2 - Simplified Workflow Solution Template

Figure 2 is an over-simplified representation of the workflow for JPL.  The workflow template shows the parent process which is responsible for spawning the n-number of approval sub-flows and waiting for the sub-approval flows to be approved or rejected before continuing on.

Figure 3 - JPL Data FlowFigure 3 - JPL Data Flow

Figure 3 illustrates how the parent process and the child communicate with each other using the Maestro API.  The parent is able to spawn sub-flows, while the sub-flows are able to communicate their approval status back to the parent.  The “Wait” task in the parent process is able to detect if all sub-flows are complete or if a sub-flow has signalled a rejection.

The Outcome

The workflows were put into production, successfully automating an internal business approval process for JPL.  The shuffling of paper, sending manual emails to people, and the complete lack of visibility of where processes stall has been eliminated.  Using our workflow as a base, JPL has automated a number of other internal processes.  Letting Drupal manage the content and Maestro manage the business process has proven to be a success.

Need Automation?

Do you have manual processes that are slowing your business down? Do you still have untapped areas for business improvements?

Apr 10 2018
Apr 10

As Drupal module maintainers, we at Nextide need to be constantly updating our modules to add new features or patch issues.  Whether your module is available for download or is a custom module for a client site, you can't expect users to uninstall and reinstall it to pick up new features.  If you have data or configuration changes, update hooks are mandatory to learn.  This post will show how we created a new content entity in a Drupal update hook.

Our Maestro module's first release for Drupal 8 housed the core workflow engine, task console and template builder.  It was a rewrite of the core engine's capabilities and was a major undertaking.  However, as Drupal 8's core matures, and as our deployments of Maestro continue, new features, patches and bug fixes for Maestro are inevitable.  In order to bring those new features to the core product, we had to ensure that anything we added to the module was available to existing users and deployed sites via the Drupal update routine.

One of the first new features of Maestro, not included in the initial release, is the capability to show a linear bird's eye view of the current progression through a process.  This feature requires a new content entity to be created.  A fresh install of Maestro would install the entity, however, for existing sites, uninstalling and reinstalling Maestro is not an option.  A Drupal update hook is required to install the entity.  What we found was the available documentation describing how to create a new content entity via an update hook was nearly non-existent.  Some of the top Google results showing how others have solved this issue provide outdated and even dangerous methods to solve the problem.

 

Define Your Content Entity

The first step is to define your entity.  Drupal 8's coding structure requires that you place your content entity in your /src/Entity folder.  There's a good deal of documentation on how to create a content entity for Drupal 8 on module install.  Follow the documentation on creating the entity's required permissions and routes based on your requirements. You can find our Maestro Process Status entity defined in code here:  https://cgit.drupalcode.org/maestro/tree/src/Entity/MaestroProcessStatus.php

The Maestro Process Status Entity code in conjunction with the appropriate permissions, routes and access control handlers will install the Maestro Status Entity on module install.  However, if you already have Maestro installed, configured and executing workflows, running update.php will not install this entity!  Update hooks to the rescue...

Creating a Drupal 8 Update Hook

There's good documentation available on how to write update hooks, but what's missing is how to inject a new content entity for already installed modules. If you use the Google machine, you'll come across many posts and answers to this question showing the following as the (wrong) solution:

/**
  * This is an example of WHAT NOT TO DO! DON'T DO THIS!
  *
  */
function hook_update_8xxx() {
  //For the love of Drupal, do not do this.
  \Drupal::entityDefinitionUpdateManager()->applyUpdates(); //No, really, don't do this.
  //Are you still trying to do this?  Don't.
}

WRONG!!!  DON'T DO THIS!!!

This simple update hook will most certainly pick up and install your new entity.  It will also apply any other module's entity updates along with yours!  This can cause catastrophic issues when modules that have not yet been updated get their entities altered by other modules.  What you need to do is tell Drupal to install the new entity explicitly with this less than obvious piece of code which I will explain after showing it:

/**
 * Update 8001 - Create maestro_process_status entity.
 */
function maestro_update_8001() {
  //check if the table exists first.  If not, then create the entity.
  if(!db_table_exists('maestro_process_status')) {
    \Drupal::entityTypeManager()->clearCachedDefinitions();
    \Drupal::entityDefinitionUpdateManager()
      ->installEntityType(\Drupal::entityTypeManager()->getDefinition('maestro_process_status'));
  }
  else {
    return 'Process Status entity already exists';
  }
}

The update hook is found in the maestro.install file and I've removed some of the extra Maestro-specific code to simply show how to get your content entity recognized and installed. 

  1. We do a simple check to see if the maestro_process_status table exists.  Since content entities store their data in the database, if the table doesn't exist, our content entity is not installed. 
  2. We clear the cached definitions from the entityTypeManager.  This should force Drupal to read in all of the definitions from storage.
  3. Using the entityDefinitionUpdateManager (also used in the "wrong" example), we use the installEntityType method which takes an entity definition as an input.
  4. We pass in the maestro_process_status definition using the getDefinition method of the entityTypeManager object.

At this point, Drupal installs the entity based on the definition I showed above.  Your content entity is installed, including the database table associated with the entity.

Nov 02 2017
Nov 02

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.
 

Maestro D8 Concepts Interactive Task Edit fixed assignmentInteractive Task Edit - Fixed value assignment

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.

Maestro D8 Conepts Interactive Task Edit Assignment by VariableInteractive Task Edit - By Variable assignment

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.  

Maestro D8 Concepts Interactive Task Notification AssignmentsA portion of the Interactive Task Notification Assignments


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.  

Maestro D8 Concepts Interactive Task General EditInteractive Task General Edit Options

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.

Maestro D8 Concepts Content Type Task Edit OptionsContent Type Task Edit Options

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.

Nov 02 2017
Nov 02

This is part 3 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, and Part 2 for the Maestro's workflow engine internals.  This post will help workflow administrators understand why Maestro for Drupal 8's validation engine warns about the potential for loopback conditions known as "Regeneration".

Loopbacks and Regeneration

Since 2003, Maestro had the concept of "Regeneration".  Regeneration for Maestro on Drupal 7 was a rather nebulous concept if you didn't understand the complexities that exist within the original engine.  Most administrators would simply check the regeneration option to "on" and the option to "recreate all in production tasks" and never worry about what it actually meant.  Simply put, as a human reading a workflow diagram, we can understand when a logic condition causes a loop-back over already executed tasks. However, for a machine to detect when we're looping-back over already executed tasks produces a set of logical issues that are not easily overcome.

Unfortunately for the machine logic in the Drupal 7 Maestro engine, a loop-back over already executed tasks signaled that something is terribly wrong!  It is a safety mechanism that prevented logic traps when executing a single task multiple times.  The solution was to have an administrative option in Drupal 7 (and prior non-Drupal versions) to tell the engine that indeed we do want to re-create the task in the queue and that we would like it if the workflow could re-spawn itself with a wholly new process ID and copy over all in-production tasks and data.  Regeneration was an evil necessity until recently.

We embarked on a project to simplify the engine execution of templates by trying to remove the notion of regeneration on logical loopbacks.  The obvious thing we could have done was to hide the regeneration option and just have it turned on for each task.  Problem solved!  Well, sort of.  Regeneration, while crafty in its approach, produces multiple processes linked via a linked list from the parent to its children.  The cascading of processes caused confusion to new Maestro admins and is a concept that is hard to grasp except for those of us who have lived with the logic of regeneration for nearly 15 years.

The resolution to the regeneration problem is to re-code the engine such that it recognizes a logical loopback condition and tries to understand whether it should or should not create tasks that have already been created in the queue.  The default scenario of "always regenerate" is now the default in the Maestro D8 engine, but it has some caveats explained further here.

Consider the workflow of the example Form Approval Flow provided with Maestro:

Workflow showing a regeneration or loopback situationContent Type task is internally flagged as having multiple pointers.


As shown, the content type task is the first task in the task chain that has the capacity to be executed multiple times during the workflow's lifetime.  It is the first "real" task of the workflow (Start task is the first task, but is just a placeholder) and it can be looped over and over again until the form is approved.  Maestro for D8 will now re-create the content type task as many times as required all without ever changing the process ID!  This not only has simplified the administration of the engine, but also removes a point of possible failure if a regeneration copy of the process failed.  While the tasks following the Content Type task are re-executed during a loopback, it is critical that each task doesn't flag the engine as being "regenerated", thus causing the engine to constantly flag and update the existing open process' tasks as regenerated.  This too is handled by the new Maestro engine in Drupal 8.

Because this task has multiple pointers pointing to it from the Start task and from the Set Process Variable task, and the fact that it is not one of the two special task types of AND or OR (more on this later), a loopback condition is signaled in the engine.  The engine automatically handles the loopback condition, preserving the process ID and all in-production and executed tasks in the queue.

Validating the workflow with regeneration messageRegeneration message on validity check.

When you validate the example Form Approval flow, you should see the warning message shown above.  The message reads, "This task, with two pointers to it, will cause a regeneration to happen".  This message is either confusing to you or is what you expect to happen anyway!  What the validation engine is telling you is that because this is not an AND or OR task, the engine will recreate the already created once task for you in the queue.  The validation engine is showing this as a warning/informational message only and will allow the template to be put into production.


Special Tasks - The AND and OR

The AND and OR tasks are the ONLY two tasks that the engine will allow two or more pointers to and will NOT signal a loopback condition.  It is critical as a workflow designer to understand that if you wish to do a loopback to previously executed tasks, pointing to an AND or OR task will NOT produce a loopback scenario.  Looping back to an AND task is logically incorrect to begin with as the AND task will never complete in the first place if one of its input pointers is coming from an area of the template that falls logically after the AND.  Looping back to an OR task, while not logically incorrect, simply does not reproduce the OR.  A loopback to an OR may simply just stall the workflow at that point as the OR has already been created in the queue and does not produce a loopback regeneration condition.

In short, excluding the start, end, OR and AND tasks, all other tasks produce a logical loopback condition and will signal the engine to re-create already created tasks in the queue for execution.  The workflow administrator's job of figuring out where logical loopbacks may occur or which options to enable on the workflow are now a thing of the past. Maestro for Drupal 8 now takes care of the logic and provides the workflow administrator with validation messages, predicting where loopback conditions may occur.

Nov 02 2017
Nov 02

The Maestro Engine is the mechanism responsible for executing a workflow template by assigning tasks to actors, executing tasks for the engine and providing all of the other logic and glue functionality to run a workflow.  The maestro module is the core module in the Maestro ecosystem and is the module that houses the template, variable, assignment, queue and process schema.  The maestro module also provides the Maestro API for which developers can interact with the engine to do things such as setting/getting process variables, start processes, move the queue along among many other things.

As noted in the preamble for our Maestro D8 Concepts Part 1: Templates and Tasks post, there is jargon used within Maestro to define certain aspects of the engine and data.  The major terms are as follows:

Template:  The workflow pattern which you can edit via the Template Builder module.  Defines the logical pattern the engine should follow.

Tasks:  Tasks are defined in the Template Builder and are either executed by the engine or assigned to actors.  

Template Variables:  Variables defined on a template and used in the Template Builder for logical operations, task operations or task assignments.

Process:  When a template has been started (there are multiple ways to start a template), the template is used by the engine as the path for execution.  Thus, the first entity created by the engine when a template is started is the process entity.  Thus a template put into production is a process and each process has it's own unique ID called the process ID.  

Queue:  The queue is the entity that holds information for what the engine is to execute or what is presented to the task console for the assigned actors to execute.  Each task in the template becomes an entry in the queue when a template has been put into production.  Only those tasks which are ready to be executed are created in the queue table by the engine.

Process Variables:  Template variables that have been copied over into the execution process variables entity to track and store variables.  Using the Maestro API, developers can get/set values, tasks can be assigned and logic tests can be done on variable values.  Variable values can be unique from process to process, thus producing routing or logic operations that are different from process to process even if those processes are based on the same template.

Production Assignment:  Tasks are assigned to actors or roles either explicitly or by variable in the template builder.  When a template is put into production, those assignments are translated from the template and injected into the production assignments entity.  Only interactive tasks such as the interactive task, manual web task and content type task (shipped by Maestro at this point) are assignable to human actors.  Thus only those task types will have production assignments in the production assignments entity.  Engine executable tasks are simply executed by Maestro.

The Orchestrator:  The Orchestrator is the crucial piece to the Maestro puzzle.  The Orchestrator is responsible for marshalling the process to completion.  There is one and only one instance of the orchestrator that is allowed to run at any given time, thus forcing the movement of processes forward task-by-task.  It is highly recommended that the Orchestrator be run on a relatively frequent basis via the Orchestrator URL (http://site_url/orchestrator/{token}).  You can also run the Orchestrator via refreshes of the Task Console.  You can configure the Orchestrator by going to /admin/config/workflow/maestro, and setting a token to be used in the Orchestrator URL and turning on/off the execution via the Task Console.  Setting the Orchestrator to run every minute is not uncommon and allows processes to continue without the need to hit the Task Console to move the processes forward.

Task Completion:  When a task completes, the software flags the task's status as being complete.  During the Orchestrator's execution, it reads the status of the task and determines if it has been completed and will flag the task as "archived" once the next task in the template has been created.  

Process Completion:  When the End task is executed, the engine will execute code to flag the process as complete.  If a process has open tasks appearing in users' Task Consoles and the process is flagged as completed, those tasks disappear as only active processes and active process' tasks are actioned upon by Maestro.  If you do not have an End task for any flows that can have multiple end points, the process will never be flagged as complete unless you flag it as such via the Maestro API.

Validation:  New for Maestro on Drupal 8, the validation engine helps ensure that templates are created properly and that the template has a higher probability of executing error free (no guarantees as the engine has no concept if a user SHOULD be assigned to tasks or if your logic is sound).  Thus when you make changes to a template in the template builder, the template is flagged as invalid and cannot be put into production if it has not been validated.

Nov 02 2017
Nov 02

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 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.

Maestro Workflow Concepts: Initiator and entity_identifier variablesThe template variable editor showing initiator, entity_identifiers and a third variable.

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.

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 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!

Nov 02 2017
Nov 02

We've put together a Maestro overview video introducing you to Maestro for Drupal 8.  Maestro is a workflow engine that allows you to create and automate a sequence of tasks representing any business process. Our business workflow engine has existed in various forms since 2003 and through many years of refinements, it was released for Drupal 7 in 2010. 

If it can be flow-charted, then it can be automated

Now, with the significant updates for Drupal 8, maestro was has been rewritten to take advantage of the Drupal 8 core improvements and module development best practices. Maestro now provides a tighter integration with native views and entity support.

Maestro is a solution to automate business workflow which typically include the movement of documents or forms for editing and review/approval. A business process that would require conditional tests - ie: IF this Then that.

  • if this document is approved then send it to the department manager else return to the initiator
  • or ... if this form/document requires a security review, then sent it to the security team
  • or .. if the last task set the flag for Purchasing .. then launch the purchasing sub workflow

A number of condition checks (if tasks) can be incorporated through simple admin functions without any coding. Complex business processes which include parallel approvals and serial grouping of tasks with dynamic routing can be modeled. There really is no limit to how large or complex a workflow can be. All business workflows are just a series of interactive tasks, batch tasks, and conditional tasks. The module provides a number of different interactive and batch tasks and the module API makes it easy to extend and provide your own custom tasks. The visual workflow editor will automatically support your custom task types.

Example business workflows:

  • Expense Approval
  • New employee hire (procurement, application access, building access, office manager ....)
  • Product Development (marketing, engineering, sales, design, manufacturing ... )
  • Project Management
  • New Idea Submission
  • Contract Management
  • Document Management / Revision Management
  • Legal
  • Request Tracking

This video will provide an overview of how to create a workflow template (set of tasks) for a simple approval workflow and the admin features like tracking or tracing workflows. 

[embedded content]

  • Link to the maestro project page and download on drupal.org
  • Subscribe to our YouTube channel so you don't miss any videos about how to use Maestro for your workflow automation projects.
Nov 02 2017
Nov 02

The Maestro Workflow Engine for Drupal 8 is now available as a Beta download!  It has been many months of development to move Maestro out of the D7 environment to a more D8 integrated structure and we think the changes made will benefit both the end user and developer.  This post is the first of many on Maestro for D8, which will give an overview of the module and provide a starting point for those regardless of previous Maestro experience.

If you can flowchart it, we can automate it!

Maestro is a business process workflow automation engine which ships with a process template editor and end user task console.  Maestro's slogan is: "If you can flowchart it, we can automate it".  With Maestro's template editor, you can visually design a workflow which has human-interaction-required tasks and machine-executed tasks, complete with logic, looping, branching and variables.

Maestro Workflow Engine for Drupal 8 Template EditorMaestro Drupal 8 Template Editor

Maestro's first generation release was back in 2003 where a rudimentary version of our current workflow engine was developed.  Over the intervening 14 years, Maestro has been steadily updated and in 2011, Maestro was released as a full version module on Drupal 7.  Maestro's D7 release heralded a new beginning for the engine with Nextide's focus for Maestro being solely centred on Drupal.  Maestro for D8 is now more integrated with Drupal, provides a rich Drupal 8 development environment while still delivering the basic functionality out of the box.

Maestro's workflow engine is known as the "Orchestrator".  The Orchestrator is responsible for marshaling workflow processes through their templated paths.  The maestro module contains the workflow engine, the entities and the API used for managing workflow processes.  The Orchestrator is designed to run independently from the rest of Drupal in a similar fashion to Drupal Cron, thus allowing the workflow process to proceed without having to wait for a user to hit the site and bootstrap Drupal.

Entities

Maestro for D8 now uses Drupal 8 config entities for the templates and content entities for the in-production templates (called processes).  The introduction of native Drupal 8 entities for the engine means that site builders can now use Views as a means to create interfaces and reports for active processes.  Maestro ships with a few out-of-the-box views for showing outstanding and in-production tasks to help administrators with their daily routines. 

Maestro Drupal 8 Configuration EntityTemplates are now Config Entities

 

API

Maestro's API has been revamped and updated to provide a much more streamlined development experience.  A separate blog post will be used to highlight the basic API.  The maestro_engine provides the basic API for use in your own Maestro-related applications.

The Template Builder is the interface workflow administrators will spend a great deal of time.  As shown in the image in the "What is Maestro" section, the interface allows administrators to drag-and-drop tasks on to a visual workflow designer.  The Maestro D8 template builder is an SVG-based tool that works on all platforms, including iOS and Android browsers.  The editor interface has been updated to allow single-click operations for editing and moving of tasks in the interface. 

Developers using the new template builder will be pleased to know that the edit screens for tasks are now full Form API driven interfaces, giving developers the ability to inject their own form fields and manage that data as they see fit.

Task Editing via the Form APITask Editing interface

Maestro for D8 has introduced the concept of validated templates.  In order for a template to be put into production, it must first be validated by the engine.  The validation routine ensures that tasks have the appropriate fields or task pointers in place to allow a template to function as error free as possible.

Ultimate end users of the workflow engine are not administrators, but rather the users in your environment that must complete assigned tasks in order for the workflow to continue.  The task console is the default application provided by Maestro to show users their tasks.  Tasks are assigned to users based on the template and the configuration provided for the task.

Maestro's Task ConsoleMaestro's Task Console

The task console provides users with a simple interface to execute their tasks.  Maestro developers can customize the functionality, look and feel of the tasks to suit the business' requirements.  A number of APIs and hooks exist for the Maestro Engine and the task console to augment and customize the text and appearance of the console columns themselves.

Nov 01 2017
Nov 01

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.

Sep 30 2017
Sep 30

This is part 3 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, and Part 2 for the Maestro's workflow engine internals.  This post will help workflow administrators understand why Maestro for Drupal 8's validation engine warns about the potential for loopback conditions known as "Regeneration".

Sep 30 2017
Sep 30

The Maestro Engine is the mechanism responsible for executing a workflow template by assigning tasks to actors, executing tasks for the engine and providing all of the other logic and glue functionality to run a workflow.  The maestro module is the core module in the Maestro ecosystem and is the module that houses the template, variable, assignment, queue and process schema.  The maestro module also provides the Maestro API for which developers can interact with the engine to do things such as setting/getting process variables, start processes, move the queue along among many other things.

As noted in the preamble for our Maestro D8 Concepts Part 1: Templates and Tasks post, there is jargon used within Maestro to define certain aspects of the engine and data.  The major terms are as follows:

Sep 30 2017
Sep 30

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.

 

Sep 30 2017
Sep 30

We've put together a Maestro overview video introducing you to Maestro for Drupal 8.  Maestro is a workflow engine that allows you to create and automate a sequence of tasks representing any business process. Our business workflow engine has existed in various forms since 2003 and through many years of refinements, it was released for Drupal 7 in 2010. 

If it can be flow-charted, then it can be automated

Now, with the significant updates for Drupal 8, maestro was has been rewritten to take advantage of the Drupal 8 core improvements and module development best practices. Maestro now provides a tighter integration with native views and entity support.

Maestro is a solution to automate business workflow which typically include the movement of documents or forms for editing and review/approval. A business process that would require conditional tests - ie: IF this Then that.

Sep 30 2017
Sep 30

The Maestro Workflow Engine for Drupal 8 is now available as a Beta download!  It has been many months of development to move Maestro out of the D7 environment to a more D8 integrated structure and we think the changes made will benefit both the end user and developer.  This post is the first of many on Maestro for D8, which will give an overview of the module and provide a starting point for those regardless of previous Maestro experience.

Sep 29 2017
Sep 29

This is part 3 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, and Part 2 for the Maestro's workflow engine internals.  This post will help workflow administrators understand why Maestro for Drupal 8's validation engine warns about the potential for loopback conditions known as "Regeneration".

Sep 08 2017
Sep 08

The Maestro Engine is the mechanism responsible for executing a workflow template by assigning tasks to actors, executing tasks for the engine and providing all of the other logic and glue functionality to run a workflow.  The maestro module is the core module in the Maestro ecosystem and is the module that houses the template, variable, assignment, queue and process schema.  The maestro module also provides the Maestro API for which developers can interact with the engine to do things such as setting/getting process variables, start processes, move the queue along among many other things.

As noted in the preamble for our Maestro D8 Concepts Part 1: Templates and Tasks post, there is jargon used within Maestro to define certain aspects of the engine and data.  The major terms are as follows:

Sep 08 2017
Sep 08

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.

 

Sep 08 2017
Sep 08

We've put together a Maestro overview video introducing you to Maestro for Drupal 8.  Maestro is a workflow engine that allows you to create and automate a sequence of tasks representing any business process. Our business workflow engine has existed in various forms since 2003 and through many years of refinements, it was released for Drupal 7 in 2010. 

If it can be flow-charted, then it can be automated

Now, with the significant updates for Drupal 8, maestro was has been rewritten to take advantage of the Drupal 8 core improvements and module development best practices. Maestro now provides a tighter integration with native views and entity support.

Maestro is a solution to automate business workflow which typically include the movement of documents or forms for editing and review/approval. A business process that would require conditional tests - ie: IF this Then that.

Sep 08 2017
Sep 08

The Maestro Workflow Engine for Drupal 8 is now available as a Beta download!  It has been many months of development to move Maestro out of the D7 environment to a more D8 integrated structure and we think the changes made will benefit both the end user and developer.  This post is the first of many on Maestro for D8, which will give an overview of the module and provide a starting point for those regardless of previous Maestro experience.

Sep 06 2017
Sep 06

The Maestro Engine is the mechanism responsible for executing a workflow template by assigning tasks to actors, executing tasks for the engine and providing all of the other logic and glue functionality to run a workflow.  The maestro module is the core module in the Maestro ecosystem and is the module that houses the template, variable, assignment, queue and process schema.  The maestro module also provides the Maestro API for which developers can interact with the engine to do things such as setting/getting process variables, start processes, move the queue along among many other things.

As noted in the preamble for our Maestro D8 Concepts Part 1: Templates and Tasks post, there is jargon used within Maestro to define certain aspects of the engine and data.  The major terms are as follows:

Template:  The workflow pattern which you can edit via the Template Builder module.  Defines the logical pattern the engine should follow.

Tasks:  Tasks are defined in the Template Builder and are either executed by the engine or assigned to actors.  

Template Variables:  Variables defined on a template and used in the Template Builder for logical operations, task operations or task assignments.

Process:  When a template has been started (there are multiple ways to start a template), the template is used by the engine as the path for execution.  Thus, the first entity created by the engine when a template is started is the process entity.  Thus a template put into production is a process and each process has it's own unique ID called the process ID.  

Queue:  The queue is the entity that holds information for what the engine is to execute or what is presented to the task console for the assigned actors to execute.  Each task in the template becomes an entry in the queue when a template has been put into production.  Only those tasks which are ready to be executed are created in the queue table by the engine.

Process Variables:  Template variables that have been copied over into the execution process variables entity to track and store variables.  Using the Maestro API, developers can get/set values, tasks can be assigned and logic tests can be done on variable values.  Variable values can be unique from process to process, thus producing routing or logic operations that are different from process to process even if those processes are based on the same template.

Production Assignment:  Tasks are assigned to actors or roles either explicitly or by variable in the template builder.  When a template is put into production, those assignments are translated from the template and injected into the production assignments entity.  Only interactive tasks such as the interactive task, manual web task and content type task (shipped by Maestro at this point) are assignable to human actors.  Thus only those task types will have production assignments in the production assignments entity.  Engine executable tasks are simply executed by Maestro.

The Orchestrator:  The Orchestrator is the crucial piece to the Maestro puzzle.  The Orchestrator is responsible for marshalling the process to completion.  There is one and only one instance of the orchestrator that is allowed to run at any given time, thus forcing the movement of processes forward task-by-task.  It is highly recommended that the Orchestrator be run on a relatively frequent basis via the Orchestrator URL (http://site_url/orchestrator/{token}).  You can also run the Orchestrator via refreshes of the Task Console.  You can configure the Orchestrator by going to /admin/config/workflow/maestro, and setting a token to be used in the Orchestrator URL and turning on/off the execution via the Task Console.  Setting the Orchestrator to run every minute is not uncommon and allows processes to continue without the need to hit the Task Console to move the processes forward.

Task Completion:  When a task completes, the software flags the task's status as being complete.  During the Orchestrator's execution, it reads the status of the task and determines if it has been completed and will flag the task as "archived" once the next task in the template has been created.  

Process Completion:  When the End task is executed, the engine will execute code to flag the process as complete.  If a process has open tasks appearing in users' Task Consoles and the process is flagged as completed, those tasks disappear as only active processes and active process' tasks are actioned upon by Maestro.  If you do not have an End task for any flows that can have multiple end points, the process will never be flagged as complete unless you flag it as such via the Maestro API.

Validation:  New for Maestro on Drupal 8, the validation engine helps ensure that templates are created properly and that the template has a higher probability of executing error free (no guarantees as the engine has no concept if a user SHOULD be assigned to tasks or if your logic is sound).  Thus when you make changes to a template in the template builder, the template is flagged as invalid and cannot be put into production if it has not been validated.

Aug 14 2017
Aug 14

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 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.

Maestro Workflow Concepts: Initiator and entity_identifier variablesThe template variable editor showing initiator, entity_identifiers and a third variable.

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.

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 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!

Aug 01 2017
Aug 01

We've put together a Maestro overview video introducing you to Maestro for Drupal 8.  Maestro is a workflow engine that allows you to create and automate a sequence of tasks representing any business process. Our business workflow engine has existed in various forms since 2003 and through many years of refinements, it was released for Drupal 7 in 2010. 

If it can be flow-charted, then it can be automated

Now, with the significant updates for Drupal 8, maestro was has been rewritten to take advantage of the Drupal 8 core improvements and module development best practices. Maestro now provides a tighter integration with native views and entity support.

Maestro is a solution to automate business workflow which typically include the movement of documents or forms for editing and review/approval. A business process that would require conditional tests - ie: IF this Then that.

  • if this document is approved then send it to the department manager else return to the initiator
  • or ... if this form/document requires a security review, then sent it to the security team
  • or .. if the last task set the flag for Purchasing .. then launch the purchasing sub workflow

A number of condition checks (if tasks) can be incorporated through simple admin functions without any coding. Complex business processes which include parallel approvals and serial grouping of tasks with dynamic routing can be modeled. There really is no limit to how large or complex a workflow can be. All business workflows are just a series of interactive tasks, batch tasks, and conditional tasks. The module provides a number of different interactive and batch tasks and the module API makes it easy to extend and provide your own custom tasks. The visual workflow editor will automatically support your custom task types.

Example business workflows:

  • Expense Approval
  • New employee hire (procurement, application access, building access, office manager ....)
  • Product Development (marketing, engineering, sales, design, manufacturing ... )
  • Project Management
  • New Idea Submission
  • Contract Management
  • Document Management / Revision Management
  • Legal
  • Request Tracking

This video will provide an overview of how to create a workflow template (set of tasks) for a simple approval workflow and the admin features like tracking or tracing workflows. 

[embedded content]

  • Link to the maestro project page and download on drupal.org
  • Subscribe to our YouTube channel so you don't miss any videos about how to use Maestro for your workflow automation projects.
Jul 31 2017
Jul 31

If you can flowchart it, we can automate it!

The Maestro Workflow Engine for Drupal 8

The Maestro Workflow Engine for Drupal 8 is now available as a Beta download!  It has been many months of development to move Maestro out of the D7 environment to a more D8 integrated structure and we think the changes made will benefit both the end user and developer.  This post is the first of many on Maestro for D8, which will give an overview of the module and provide a starting point for those regardless of previous Maestro experience.

Maestro is a business process workflow automation engine which ships with a process template editor and end user task console.  Maestro's slogan is: "If you can flowchart it, we can automate it".  With Maestro's template editor, you can visually design a workflow which has human-interaction-required tasks and machine-executed tasks, complete with logic, looping, branching and variables.

Maestro Workflow Engine for Drupal 8 Template EditorMaestro Drupal 8 Template Editor

Maestro's first generation release was back in 2003 where a rudimentary version of our current workflow engine was developed.  Over the intervening 14 years, Maestro has been steadily updated and in 2011, Maestro was released as a full version module on Drupal 7.  Maestro's D7 release heralded a new beginning for the engine with Nextide's focus for Maestro being solely centred on Drupal.  Maestro for D8 is now more integrated with Drupal, provides a rich Drupal 8 development environment while still delivering the basic functionality out of the box.

Maestro's workflow engine is known as the "Orchestrator".  The Orchestrator is responsible for marshaling workflow processes through their templated paths.  The maestro module contains the workflow engine, the entities and the API used for managing workflow processes.  The Orchestrator is designed to run independently from the rest of Drupal in a similar fashion to Drupal Cron, thus allowing the workflow process to proceed without having to wait for a user to hit the site and bootstrap Drupal.

Entities

Maestro for D8 now uses Drupal 8 config entities for the templates and content entities for the in-production templates (called processes).  The introduction of native Drupal 8 entities for the engine means that site builders can now use Views as a means to create interfaces and reports for active processes.  Maestro ships with a few out-of-the-box views for showing outstanding and in-production tasks to help administrators with their daily routines. 

Maestro Drupal 8 Configuration EntityTemplates are now Config Entities

 

API

Maestro's API has been revamped and updated to provide a much more streamlined development experience.  A separate blog post will be used to highlight the basic API.  The maestro_engine provides the basic API for use in your own Maestro-related applications.

The Template Builder is the interface workflow administrators will spend a great deal of time.  As shown in the image in the "What is Maestro" section, the interface allows administrators to drag-and-drop tasks on to a visual workflow designer.  The Maestro D8 template builder is an SVG-based tool that works on all platforms, including iOS and Android browsers.  The editor interface has been updated to allow single-click operations for editing and moving of tasks in the interface. 

Developers using the new template builder will be pleased to know that the edit screens for tasks are now full Form API driven interfaces, giving developers the ability to inject their own form fields and manage that data as they see fit.

Task Editing via the Form APITask Editing interface

Maestro for D8 has introduced the concept of validated templates.  In order for a template to be put into production, it must first be validated by the engine.  The validation routine ensures that tasks have the appropriate fields or task pointers in place to allow a template to function as error free as possible.

Ultimate end users of the workflow engine are not administrators, but rather the users in your environment that must complete assigned tasks in order for the workflow to continue.  The task console is the default application provided by Maestro to show users their tasks.  Tasks are assigned to users based on the template and the configuration provided for the task.

Maestro's Task ConsoleMaestro's Task Console

The task console provides users with a simple interface to execute their tasks.  Maestro developers can customize the functionality, look and feel of the tasks to suit the business' requirements.  A number of APIs and hooks exist for the Maestro Engine and the task console to augment and customize the text and appearance of the console columns themselves.

Jun 22 2015
Jun 22

A very common use-case for Maestro is to launch a workflow in order to moderate some piece of content. You may have an expense form as a content type and you wish to have a manager review and approve it before handing it off to other departments for processing.

This post will show you how to fire off a moderation workflow after saving content with Rules.

Step 1: Create a simple test flow

I know you have a super-ultra-complex workflow, but this is best to get off the ground with a simple 1 step flow for the time being!

Step 1 - create a simple test flow

As shown, this is a simple 1 step flow to ensure that you're getting all of the mechanics to work. This is an interactive function task with the handler set to "maestro_show_message".

When you're editing the interactive function task, go to the "Optional" tab, and create a variable named "message" and type in a simple message for its value. This will be a simple placeholder so the task actually does something in the task console.

Assign the task to a user that has rights to view and edit Article content. Using the Admin user is fine for this example to avoid permission problems for the time being. You also will have to create a new process variable for this workflow.

Step 1.5 - create a node_id variable

As you can see, this variable is called "node_id" and will be used to store the created node's ID inside of the process after it has been created.

Step 2: Create a new rule

I trust that you know how to create rules. When you create the rule, ensure that you create it based on the event of firing after saving of new content. Create a rule condition to only fire the rule when a certain type of content is created. In my example, I'm using the default Article content type that comes out-of-the-box with Drupal.

Step 2 - create a simple rule

At this point, the rule will fire any time a new Article is created.

Step 3: Rule Actions

What's most important about this step is to get the newly created node automagically added to a Maestro workflow.

We need to do this by associating the node's ID with the node_id process variable we created in step 1. You do this by first creating an action to "Add a variable". It must be an integer value, and the variable label and variable name should be "node_id". Maestro will look for these specifically named rules variables in order to try to set its own "node_id" variable from step 1.

Next, create a second action that will "Set a data value". You will set the newly created node_id rule variable with the created content's node:nid.

Finally, you will create a third action to "Launch a Maestro Workflow". In the value drop down, select the workflow you wish to launch. In Step 1, I named ours "Rules based workflow". Check off the "Content Moderation Workflow" checkbox as that will allow Maestro to pre-populate some of the internal Maestro data elements with content linkages. The Process ID section should simply have "Process ID" as the variable label and "process_id" as the variable name.

Your Actions should look similar to this: Step 3 - rule actions

Done!

At this point, you've created a rule that will pass off node information to Maestro and launch a workflow.

Here's a sample of what my task console looks like when I created an article.

Step 4 - task console

As shown, the task console has a flow created that has a single task. When you expand the task details, you will see the Article content type listed under the Content area. If you have permissions to view/edit, you can click on the content link to the Article and view it.

Mar 07 2014
Mar 07

With Drupal 8 emerging on the horizon, we've started to delve in to our core modules, Maestro and Filedepot, beginning the process of porting them from Drupal 7 to 8.

For our Drupal 8 version of Maestro, I have some immediate concerns that I would like addressed, but also some "wish list" items which I feel would bring a great deal of flexibility.

A condensed road map, of sorts, for Maestro's first release on Drupal 8 would be:

1. Modularize as many components as possible. For example, we need to remove the task console from Maestro as a piece that travels along with the core Maestro module, allowing people to create their own consoles as they see fit.

2. Entities - We need entities such that the in-production processes and queue is accessible via the entity API and as a result, views. While we do have some rudimentary capabilities currently in Maestro, having a full entity governing over the data structures in Maestro is a must. I embarked on an entity project for Maestro on D7 and hope to leverage some of that for the D8 version.

3. Revamp of the template builder. The strength of Maestro is that it is a workflow engine, capable of routing tasks through your task template created with the visual workflow editor. There is nothing like Maestro that exists in the Drupal realm - We need to keep focus on Maestro's strengths and make them stronger. Modularizing the admin template creator will allow anyone to create a Maestro template builder. However we'll be including one that uses more up-to-date technologies. Scalable vector graphics is one such avenue that would allow for a dynamically scaling/scalable canvas to create a Maestro template. SVG based template views would allow the template to be exported as images and even as a PDF!

We've embarked on determining the best route for entities (both config and content) for both Filedepot and Maestro and how they fit in and how we can leverage them in the D8 environment. So while entities are progressing, in parallel I've jumped head first in to creating an SVG based Maestro template editor.

Behold! SVG template in D8!

The screen shot above is an example of some of my work over the last few days to get an existing Maestro template represented as an SVG.
Granted, it doesn't look quite as nice as the current D7 Maestro template editor... This is a prototype which will only get better over time. Currently the SVG template editor is complete with the ability to:

  • drag and drop
  • dynamically drawn connector lines
  • colour coding and success/failure
  • respects D7's Maestro template placement locations

Its a start. Stay tuned, more to come!

Dec 14 2012
Dec 14

On December 17th, Nextide and Conestoga College are proud to jointly kick off the Conestoga Centre for Open Source (CCOS).
 
The Conestoga Centre for Open Source is a volunteer driven organization founded by Conestoga College and Nextide Inc. Together, Conestoga and Nextide want students to participate in meaningful Open Source projects to not only get exposure to new development concepts, but to also create a community of developers who understand the value of Open Source and how to work on projects which have a distributed base of users and core developers.
 
Since Nextide is a Drupal based development shop, and Drupal is one of the leading Open Source PHP based Content Management Systems (CMS), it is an obvious choice to have students get ramped up on Drupal, mentored by Nextide, in order to start meaningful development on new projects anchored in Drupal.
 
The goal of CCOS is to have a collection of students who are able to participate in projects for which they have attributed code to and have had their code peer reviewed.
 
As students enter CCOS, the existing student base in CCOS can bring new students up to speed on current projects and in turn provide mentorship to them. CCOS is about community, sharing, growing as a developer and as a member of a project.
 
Nextide has been in business since 2000, became 100% devoted to Open Source solutions in 2003 and since early 2009, Nextide has been solely focused on Drupal. As a company, Nextide has done and continues to do a variety of outreach programs with the Drupal community. We have been a sponsor of Drupal Camp Toronto for the last 3 years, attend the local Drupal meetups, and have helped bring Open Source to predominantly closed source institutions.
 
Getting the CCOS initiative off the ground is a major milestone for Conestoga. While the Engineering programs at the college do mention open source, the curriculum does not necessarily take advantage of open source or mandate its usage. Through CCOS and mentoring by Nextide, we hope that a new wave of Drupal expertise emerges from the college.

Sep 07 2011
Sep 07

The regenerate functionality goes back many years in the history of the Maestro engine.  I wrote the very first instance of the "Maestro" engine back in 2004/2005 where it was nowhere near as flexible and nowhere near as extensible as it is today as Maestro.  That being said, the engine's internals have been updated and upgraded over the years which has culminated in what you see today.  The concept of regenerate and regenerate all live tasks comes from the very beginning of the engine's life and lives today in Maestro 1.0's engine. 

During the inception of the engine, we were automating a rather simple workflow (only about 20 steps in total) -- however this specific workflow had many instances where it had to loop back to earlier executed tasks based on IF tasks determining if something was accepted or rejected.  Seems easy!  Just point the true or false branch of an IF task to any other task "higher" up in the chain of tasks and you're done!
Well, not quite.  That approach works... and doesn't work all at the same time.  The problem I ran in to was a simple one.  The engine has what I would call a self regulating mechanism in it to not re-create the same task twice during the execution of a flow.  The reason why the engine has to have a self regulation mechanism to prevent duplicate tasks being created is to ensure that the engine is not stuck in a deadlock loop due to a misbehaving task (especially a batch task or AND task).  I had to have full human control over the engine to specifically tell it to either recreate the task it is looping back over and that it was OK to do so.  More specifically, the engine is built this way to only ever create one instance of an AND task.  You can have many AND tasks in a flow, but there can only be one instance of each AND task created.  Enter the concept of Regeneration.
 
To Regenerate or not to Regenerate.... that is usually the question.

When in doubt, you probably want to regenerate a task.   So what does regenerate mean?  Simply put, when a flow loops back over itself due to a logic condition or path branch tells it to, the task that has a regenerate flag turned on tells the engine that it is OK to re-create that task.  This effectively bypasses the self regulating mechanism of the engine that resists creation of duplicate tasks in a flow.
A by-product of a regenerated flow means that the current process is suspended and given a status of "Regenerated".  The engine creates a new process instance of the workflow and starts it off at the regenerated task.  All data with the execution of the original flow up to the point of regeneration is all there.  Untouched.  However with only the regenerate flag on, ONLY that task will be active once the new process executes.  All other currently-in-execution or currently assigned tasks disappear.

Great!  Problem solved!!!  Not quite.... 
Remember that simple 20 step flow I mentioned above?  That flow became a 40 step flow which included the magnificent AND task.  Yes, the AND task... the task that is able to wait for all incoming branches of a flow to execute up to the AND and only continue execution when all branches have reached the AND.  Well, picture the following scenario:

As you see, there are 2 branches with an IF in only one of the branches.  The flow says to only loop back inside of the current left branch... not back up to the top of the parallel branch parent (Step 1).  With just a Regenerate flag set to "ON" on Step 2, the task Step 3 and the AND task would have been trapped in the original process which would have been put in to regeneration status.  A new process is created and as a result the ONLY active task in the new process is Step 2.  All other assigned tasks that existed disappear as they do not exist in the new process.

Sounds fine right?  No!!
The user who is assigned Step 2 would get that task in their task console.  The user assigned to Step 3 would see the task disappear from their console.
The user completes Step 2, gets assigned Step 4.  User completes Step 4, and this time passes the IF condition and as a result the AND task is created.  The AND task will wait for all incoming branches to finish..... see the problem yet?  Issue is that before regeneration, Step 3 existed.  Once completed Step 3 would flow in to the AND and as such, the AND could complete.
Not after regeneration.  The engine did not re-create Step 3 and as a result only ONE of the branches in to the AND completed.  The engine will hold the AND task as active forever.

Enter Regenerate All In Production Tasks flag.
The solution to this was to have a second flag on a task to tell the engine to not only regenerate THAT task, but also to regenerate all tasks that were not completed at that time. 
While this may seem to be what the default option should be, that is not the case.  Consider this flow:

The flow in this case will redirect back up to the top of the parallel branch chain.  In this case you do NOT want to regenerate all tasks that are in production.  Simply put, you will only regenerate the single parent-of-the-parallel-branches task.  As a result, only using the Regenerate flag is sufficient.

In either case, the regeneration options are there for you as a workflow administrator to accommodate the creation of tasks as you see fit. 
At Nextide, we've got a concept engine in the works that removes the need for both regenerate and regenerate all in production flags.  The engine's logic is altered to make some relatively safe assumptions about your flow and do the appropriate regeneration for you. 

Aug 05 2011
Aug 05

How do I..... ?  is a question we hear quite a bit when it comes to the Maestro API. We have a few very good blog posts on our site and also bundle Maestro with some good example code. However time has come to begin to document how to do a variety of common things with the Maestro API.

New Maestro Process

First, let's look at how to programmatically create a Maestro process. Programmatically firing off a process opens up numerous possibilities to handle complex workflows that are not always initiated by human interaction.  

To name a few possibilities:

  • Daisy-chaining multiple Maestro processes together
  • Using Drush’s scripting abilities to launch a new process
  • Drupal and module hooks can be used to write custom code to launch a new process
  • Creation of custom menu functions to launch a process when clicked

Out of the box we’ve provided a simple drop down in the task console to launch a process. As convenient as that is, I personally find that approach only useful for testing. For each of the workflow apps we’ve ever deployed, we’ve always front-ended the initiation of a flow with a button click, creation of content or some other means. 

A Maestro process is always based on a Maestro Template. A Template is the workflow pattern that is created in the Maestro Visual Workflow Designer. 

The following code initiates a new process:

$maestro = Maestro::createMaestroObject(1);

$newprocess_id = $maestro->engine()->newProcess($template_id);

The first line creates a Maestro object. The createMaestroObject(1) method will create a singleton object using version 1 of the Maestro engine. Since we only have version 1 of the engine right now, this is perfect!

The second line creates a new process and assigns the newly created process ID to the $newprocess_id variable. What you need to know as a developer is what numerical template ID to use for the process. Each Maestro template has an associated numerical ID shown in the template listing. Simply use the ID found there for the $template_id  variable value.

When a new process is spawned, Maestro will use the current user’s UID to track who the initiator is. If you need to augment that value and set it to someone specific, use the following 1 line of code:

$maestro->engine()->setProcessVariable('INITIATOR', $specific_uid, $newprocess_id);

Where the $specific_uid variable is the numeric user ID you wish to set.

Setting/Getting Process Variables

As shown in the code above, it is easy to use the Maestro API to set a process variable. Variables are defined when you create a template. The INITIATOR variable is always present and cannot be deleted. However you can create or delete any number of variables for your specific process as you see fit. 

Each time a process is spawned, each of the template variables defined become process variables. Therefore each process has its own set of variables named identically to those variables defined in the template. This gives each process its own set of unique variables that can be used to assign tasks, carry out logical functions, transport data between tasks etc.

In order to programmatically set a process variable’s value, you need to know the numerical process ID for which the variable resides in. Not the template ID, the process ID. 

In the example above, we created the process, and therefore we know the process ID. However depending on what you are trying to accomplish, you may have to write your own queries to deduce what the ID is. Later in this post we show you how to create a batch function which gives you the process ID automatically.

We will assume the process ID is set in a $pid variable and the variable name we are trying to set is ‘MyVariable’:

$maestro->engine()->setProcessVariable(‘MyVariable’, ‘this is a new hardcoded value’,$pid);

That’s it! Now to read a variable’s value, use the following code:

$variable_value = $maestro->engine()->getProcessVariable(‘MyVariable’, $pid);

The getter/setter methods for process variables are extremely useful for data and state information propagation in a process.

Creating a Batch Function

Batch functions are extremely useful for carrying out programmatic events during a Maestro process flow. 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:

First, you 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 Maestro module as described in our blog post so that you can easily maintain your own custom codebase.

Once you’ve created a place for your code, you will start by using Maestro’s handler hook to define your batch function name and handler:

function YOUR_MODULE_NAME_maestro_handler_options ()  {

 $handlers = array(

    'MaestroTaskTypeBatchFunction'  => array(

      'a_function_name_of_your_choice'  => t('This Description shows up in the Maestro Admin interface.')

    ),

 );

 return $handlers;

}

Clear your cache and the new handler will appear in the drop down list for the batch function task. You still need to create the actual handler now! When the batch function is executed by Maestro, its handler is what is executed. That is nothing more than a function defined in the handler_options function shown above. In our example, “a_function_name_of_your_choice” is our handler name. Therefore we need to implement it in our custom coded module:

function a_function_name_of_your_choice($queue_id, $process_id)  {

                …..put your custom code in here….

}

You will notice that the batch function’s production queue ID and process ID values are passed to your custom handler. These two values give you all of the information you require to pick off any related data from the database or set/get process variables.

Mar 30 2011
Mar 30

I'm working on another SQL Server 2008 and Drupal 7 project right now.  This particular project has a great deal of stored procedures and triggers in it to massage extrenal data to the right format for display in Drupal.

Doing Drupal/PHP development with SQL Server 2008 is easy using the 2008 Express (free) edition for those of us who don't use SQL Server regularily as a database on our development machines.  However, there is one small problem I ran in to on this current project:   SQL 2008 Express does not have any UI mechanisms in the SQL Management Studio to allow you to manage triggers!

The UI has been pared down as this is a free database engine from Microsoft after all.  Rightfully so -- if you want to have all of the features and benefits of SQL Server, you should buy a legitimate license for it (You can't run SQL Express in a production environment anyways).

However for development (especially for my current project), this is an issue that needed to be overcome. In this particular instance, I couldn't use the customer's environment to do development directly on -- just too cumbersome over a vpn without any PHP Development tools loaded in their environment.  

So the following few Transact-SQL statements are incredibly helpful for those of us using SQL 2008 Express for trigger management:

To see a listing of all of the triggers in your database:

SELECT * FROM sys.triggers

To delete/drop a specific trigger:

DROP TRIGGER triggername

To see the actual textual data that makes up your trigger:

sp_helptext 'triggername'

 Finally, here's a great little stored procedure I put together that produces text output in the SQL management studio to help you cleanly get the text out of an existing trigger: 

GO
SET ANSI_NULLS ON
GO
SET QUOTED_IDENTIFIER ON
GO
CREATE PROCEDURE _getTriggerCode
@triggerName varchar(100)
AS
BEGIN
DECLARE @txt varchar(500) -- used to store the row data we're picking off
SET NOCOUNT ON;
CREATE TABLE #tmp
(
txt varchar(500)
)
INSERT #tmp EXEC sp_helptext @triggerName

--now define a simple cursor to iterate thru the results
DECLARE txtCursor CURSOR FOR
SELECT txt FROM #tmp

OPEN txtCursor
FETCH NEXT FROM txtCursor INTO @txt

WHILE @@FETCH_STATUS = 0  
BEGIN  
    print @txt
    FETCH NEXT FROM txtCursor INTO @txt
END  

CLOSE txtCursor  
DEALLOCATE txtCursor
DROP TABLE #tmp
END

Use the stored procedure like this:

DECLARE @RC int
DECLARE @triggerName varchar(100)
set @triggerName = 'triggername' 
EXECUTE @RC = _getTriggerCode
   @triggerName
GO

Then just simply look at the Messages tab output in SQL Server Management Studio and voila, you have your trigger code.

Feb 02 2011
Feb 02

With the increased level of support by Microsoft for not only PHP on IIS, but also getting SQL Server support for Drupal 7, the barriers to entry for Enterprise level customers for Drupal are diminishing rapidly.

Case and point – we recently deployed a Maestro managed workflow process for an Enterprise level customer who would have never entertained the notion of using Drupal or Maestro if it ran only on MySQL. As sad as that sounds, it’s a stark reality for many large companies who will outright refuse even the best solution due to their perceived increased support costs for “yet another database engine” (MySQL).

With that said, my time on our Drupal 7/SQL Server/Maestro project went smoothly as I could have hoped for. There were a few curveballs here and there that hopefully this posting can help someone else overcome. So here I go:

Initial Setup for PHP and IIS

I’ve been a Windows Desktop and Server user for years. I’ve run PHP on IIS for as long as I can remember for my local development. During the “dark ages” of PHP4 IIS support, it was a real treat to see a PHP application run on IIS brilliantly with 1 person connected and fail miserably with 2 or more connected. Ok, so a bit of a stretch there, but IIS support for PHP4 was limited at best and performance wasn’t stellar. 

Microsoft realized PHP wasn’t going away – Thankfully IIS was revamped and improved immeasurably to support PHP. So with that said, using PHP on IIS7 is actually, dare I say it... FUN! 

For testing purposes I was running a development instance on my laptop – configuring IIS to use a virtual directory vs. a web site is something I leave to you to figure out. There’s plenty of documentation out there to help you along.

At the start of our Maestro project I already had a version of PHP installed locally – PHP 5.2.10. I figured that it was “good enough” for use with PDO and Drupal 7. So I started by installing the right Microsoft supported PDO drivers and Enabling PDO in PHP. I grabbed the sqlsrv Drupal 7 Database driver, and proceeded to install D7.

Installation went well! I was sufficiently impressed. 

So off I went to test out basic functionality – like creating content types and fields. This is where the trouble started -- FastCGI 0x00000000 errors constantly occurring during the saving of content types.   The issues just got worse and worse as time went on. Clearly this was NOT what Mark Brown from Microsoft was talking about during Drupal Camp Toronto! 

Trust Microsoft

This could be a stretch for some, but honestly, do yourself a favour and use the Web Platform Installer for IIS. It seems that Microsoft really got this right. After using the Web PI, I enabled PHP 5.2.14 (at that time), the appropriate PDO SQL Server drivers and the PHP Manager. All of it installed seamlessly. I created a new virtual directory, plunked D7 into it along with the sqlsrv driver and started from scratch. What do you know? It works like a charm. 500 errors were a thing of the past and the installation of PHP now has a PHP manager Icon in the IIS admin panel. Nice!

The nice thing about the Web PI is that the specific configurations of php.ini for IIS are done for you – such as the ever elusive fastcgi.impersonate and cgi.force_redirect settings. PDO drivers are installed in the right location.

web.config

The web.config shipped with D7 is fine to use with a “full web site” in IIS. However if you’re running D7 in a test environment on Vista or Windows 7, the web.config file plunked into a virtual directory may cause IIS to fail with something that looks like this:

HTTP Error 500.19 - Internal Server Error

The requested page cannot be accessed because the related configuration data for the page is invalid.

No problem. For now, just disable the web.config file by either deleting it or renaming it. Drupal should come up just fine.

NOTE: I’m not saying that this is a good idea for production sites! By totally removing web.config, you won’t be able to use things like URL redirects or properly redirect 403 errors. Disabling web.config for now just lets you get up and running IF and ONLY IF you receive the 500.19 error message shown above. 

 

SQL Server Configuration

This is where I deviated from the “norm”. I didn’t use the Web PI to install Drupal. I did this manually as I have a specific setup requirement for my SQL Server instance (In other words I didn’t want to install D7 in my SQLEXPRESS\SQLEXPRESS instance!). 

First, install SQL Server. SQL Server 2008 R2 Express is what I use on a laptop/desktop for development. 

Next, create a database and create the appropriate SQL authenticated user. This takes a bit of know-how to navigate the SQL Server Users and Security and areas.

I installed D7 exactly the same way I would with MySQL – Except you choose SQL Server from the database selection mechanism. 

Eventually, my settings.php in Drupal 7 file has the following in it:

$databases = array (
  'default' =>
    array (
    'default' =>
    array (
    'database' => 'NAMEOFTHEDB',
    'username' => 'sqlusername',
    'password' => 'sqlpassword',
    'host' => 'MACHINENAME\\INSTANCENAME,
    'port' => '',
    'driver' => 'sqlsrv',
    'prefix' => '',
    ),
  ),
);
 

I suppose you could take a shortcut and plunk the $databases array as shown above into the settings.php file and alter the database, username, password and host to suit your needs prior to running the installer. However during the installation routine, you will have the opportunity to manually fill in all of the required information – specifically when you’re filling in the database information, click on the “Advanced Options” information area and ensure you enter in your proper hostname (as it shows up in your SQL Server Management Studio connections panel). 

Drupal 7 is Up! Tidy up the Configuration now…

At this point, you’re probably staring at a freshly installed instance of Drupal 7 running on SQL Server. You may or may not have installed other optional components for IIS early on – such as URL Rewrite. 

URL Rewrite in IIS will give you similar functionality as Apache rewrite rules gives you. Most importantly, you’ll be able to activate Clean URLs in Drupal. 

In my specific case, Clean URLs were not a requirement – thankfully so, as the production server I was given for deployment didn’t have the IIS URL Rewrite mechanism installed (I’m not the admin!). 

However I ran into some interesting issues. During the installation of D7, Drupal seemed to recognize that URL Rewrite was supported and thus enabled Clean URLs. That would be fantastic if not for the fact that it wasn’t supported on that server! Generally you can disable the Clean URLs by simply navigating to the following URL:

http://fqdnOfMyServer/?q=admin/config/search/clean-urls

Worst case scenario, you can force Drupal to not use clean URLs by tacking the following line of code at the bottom of your settings.php file:

$conf['clean_url'] = 0;

Word of warning: by adding the $conf line above to settings.php, you’re hard coding Clean URLs to be off. 

Issues You May Come Across

1.     Access denied redirects don’t work!

I found an interesting issue during deployments between multiple IIS instances (usual porting process from Dev to staging to production). 

The desired functionality: Anonymous user clicks on a link to create some content. Since the content type is secured by permissions to only allow logged in users to create said content, the user gets redirected to the /user page to log in.

The issue: Testing directly on the server (using the browsers right on the system) the anonymous redirect to /user worked flawlessly. Using a browser on a separate machine caused 403 errors (Access denied) to appear even though D7 was configured to redirect to /user in the site config.

The solution: Either by editing the web.config file, or by editing the “Error Pages” mechanism in the IIS Manager app, you’ll have to add in the proper redirects for 403s. Here is an example of what a web.config file might look like for you:

 
<xml version="1.0" encoding="UTF-8">
<configuration>
  <system.webserver>
    <httperrors>
      <remove substatuscode="-1" statuscode="404"></remove>
      <error responsemode="ExecuteURL" path="/index.php" prefixlanguagefilepath="" statuscode="404"></error>
      <remove substatuscode="-1" statuscode="403"></remove>
      <error responsemode="ExecuteURL" path="/index.php?q=user" prefixlanguagefilepath="" statuscode="403"></error>
    </httperrors>
  </system.webserver>
</configuration>

The configuration above shows that the 404 and 403 errors will get redirected to /index.php or /index.php?q=user respectively. You can achieve the same result by editing the 404 and 403 error pages in the IIS manager Error Pages configuration area.

2.     Windows doesn’t have cron! How do I run Maestro’s Orchestrator?

On a UNIX system, using a cron job is trivial to simply run a wget of the Orchestrator as noted in the Maestro README file (you did read that didn’t you?).

The desired functionality: Run the Orchestrator on Windows!

The issue: Windows only has the task scheduler and is clearly missing the wget command.

The solution: Use a simple vbscript that can easily be supported on Windows, and can be launched through the Task Scheduler. 

 - Create a text file somewhere on the server in question. Name it what you’d like, but make the extension “.vbs”

 - Edit the vbs file and place the following code in to it. Edit the FQDNofTHEserver to match that of your server. Alter the CONST SLEEPTIME=2000 line to suit how often you want the orchestrator to run. In my example below, the 2000 means 2000 milliseconds (2 seconds):

CONST URL="http://FQDNofTHEserver/?q=maestro/orchestrator"
CONST USER=""
CONST PASSWORD=""
CONST MESSAGES=0
CONST SLEEPTIME=2000 'sleep for 2 seconds
ON ERROR RESUME NEXT

set WshShell = WScript.CreateObject("WScript.Shell")
while true
runOrchestrator()
WScript.Sleep SLEEPTIME
wend

sub runOrchestrator
set objHttp= CreateObject("Msxml2.ServerXMLHttp")
objHttp.open "GET", url ,false ,USER,PASSWORD
objHttp.send()
str=objHttp.responseText
if MESSAGES then msgbox str
end sub

- Now navigate to the Task Scheduler and create a new task that starts up when the machine starts. The script above is coded to stay resident in memory and execute every 2 seconds. Ensure you don’t schedule a task to run every minute or so otherwise you will have many, many instances of the orchestrator running.

- When configuring the task, use the following parameters (altered to suit your Windows installation of course). The optional arguments will fire up the task in the background with no visible window:

Program/script: c:\windows\system32\cscript.exe

Add Arguments (optional): //B //Nologo path\to\your\vbs\orchestrator.vbs

- Edit the Maestro Configuration to turn off the Orchestrator running through the task console.

- Start the scheduled task.

Feb 01 2011
Feb 01

With the recent release of Drupal 7, its PDO database abstraction layer means that Drupal 7 can technically support a variety of databases (provided they have the proper Drupal 7 database interface).

Of course, what Drupal 7 + PDO means is that yet another barrier to entry for "Microsoft Shops" to use Drupal has faded away.  One of the biggest reasons.... ahem.. excuse to not use Drupal (or just about any other Open Source CMS for that matter) was that the CMS needed to run on _______  (fill in the blank here with whichever database you like that is NOT SQL Server).  Not to mention the poor support that used to plague PHP on IIS.

Thanks to hard work by Commerce Guys, the sqlsrv project was born, giving Drupal 7 the required SQL Server database driver. That being said, you may notice that the sqlsrv project is still in an Alpha release state at the time of writing of this blog article (Update -- January 31st 2011  -- sqlsrv is now in RC status!). The Alpha state of modules generally turns people away from using it. However I strongly urge people to continue to use it and help work out any bugs with sqlsrv to bring it to a stable release. Regardless of the release state of sqlsrv and some of the outstanding issues in its issue queue, it does run quite well and actually didn’t give me any major issues when working on a Maestro project for a client.  

There are (at least) 2 things to keep in mind when you’re creating modules or writing custom code to ensure that it is a portable for SQL Server as possible:

  1.      Ensure that your SQL statements are… well… portable! Remember to use your GROUP BY clauses properly. MySQL is much more forgiving when using grouping functions in the select and omitting the non grouped columns in a GROUP BY clause. SQL SERVER (and rightfully so) will reject the query and obviously fail.
  2.      Avoid LIMIT. I’m not talking about something like $query->limit(10); On the contrary. I’m referring to MySQL’s LIMIT clause in the execution of a db_query statement. SQL server has its own mechanisms to limit return row counts using things like “ROW_NUMBER() OVER”, nested sub-selects with TOP or even cursors and temp tables. Yuck. See item #1 above.

I’m pretty sure there are a vast number of other things to keep in mind when dealing with SQL Server, however using PDO smoothes those issues out considerably.

Aug 24 2010
Aug 24

Recently we posted a blog entry Introducing Maestro and it's task types. As noted in that blog post, Maestro was a rewrite/refactor of our Nexflow product. When I wrote the first iteration of the Nexflow engine, I always had an Object Oriented approach in mind. While the original Nexflow engine is object oriented, it lacked a clear and clean way to easily implement new features. Although you could easily write a new task type, it was much more difficult to implement in the engine, requiring editing of core code which would always require extensive engine retesting.

Maestro Development Methodology:

Our overriding goal was to create a development environment that was suitable for developers to easily attach their own task types and notification mechanisms in to the system without overwriting or hacking core code. Leveraging the strength of Drupal's core functionality along with some neat OO patterns, we were able to create a base set of modules for Maestro that lets developers add their own task types and/or notification mechanisms via add-on modules.

In order to create a Maestro task module, you need to first understand that there are 2 sides of a Maestro Task. There is the User Interface side and the Engine side.

The UI side is responsible for providing the end-to-end user driven experience in creating a workflow using the visual workflow editor. The user interface provides the hooks for showing a task's general display widget as well as its associated editing panel. Without a UI component, users can't use the task in the workflow designer.

The Engine side is responsible for providing the behind-the-scenes worflow engine capabilities that allow Maestro to carry a process forward through the template created by the UI side. The engine side provides all of the necessary logic to execute and complete a task by the Maestro engine.

Maestro is a Drupal 7 module -- meaning that it will not run on Drupal 6. All development for Maestro in terms of its engine must be done on Drupal 7. This blog post is 100% dedicated to showing you how to create a D7 Maestro task module.

Drupal 7 Modules:

As noted above, Maestro tasks should be added to Maestro via add-on modules thus providing a seamless and easy way to create new task types without requiring any core Maestro engine changes. If you find yourself hacking core code to add a new task type, you're doing something wrong! Stop yourself, grab a coffee, and start over!

We acknowledge that this means that developing a new Maestro task module will require some Drupal 7 module knowledge and expertise. So to alleviate the 1st time developer jitters, the following the steps below show a step-by-step method to create a D7 Maestro Task Type module.

Step 1 - Create the module base:

Choose a name for your module. For this example, we'll call this our "Maestro Sample Task" module. Locate the modules folder under the Maestro installation. Generally this will be found in the /sites/all/modules/maestro/modules directory. Using your favourite editor, create a folder for your module under the Maestro module directory called "maestro_sample_task".

Inside of the folder, create the following files:

  • maestro_sample_task.module
  • maestro_sample_task.info
  • maestro_sample_task.install

Edit the maestro_sample_task.info file and add the following to it:

; $Id:
name = Maestro Sample Task
description = Sample Task for the Maestro Engine
package = Maestro
version = 7.x-1.0-dev
core = 7.x
dependencies[] = maestro
files[] = maestro_sample_task.module
files[] = maestro_sample_task.install


Save the file. Edit your maestro_sample_task.module file and add the following to it:

<?php
// $Id:

That's it! its just a simple placeholder file for now. We will be adding to this file later.

Edit the maestro_sample_task.install file and add the following to it:

<?php
// $Id:
function maestro_sample_task_install() {
}function maestro_sample_task_uninstall(){
}

The .install file will be simply used as a placeholder for the time being. For the purposes of this blog post, that is all we're going to have in the .install file.

At this point, your skeleton Maestro module should be able to be installed and uninstalled from the Drupal Module Admin panel. Although it doesn't do anything useful, the fact that the module actually does install and uninstall is rather important ;-). You should be able to find your module's install grouped with the Maestro package on the modules admin page.

Step 2 - Creating the task's working UI bits:

In order to attach your new task to a workflow, we have to create our Maestro UI components. The Maestro UI components are the elements needed to allow your sample task to show up in the Maestro Visual Designer and have that task saved to Maestro's internal template tables.

The base Maestro UI code is completely Object Oriented in nature. In order for developers to attach a new task to the Maestro UI, you have to extend the functionality. As mentioned earlier, if you find yourself modifying Maestro code, you're probably doing something wrong!

So first things first -- you need to understand WHAT you are extending for the UI. Maestro ships with base task UI code and is found in the maestro_task_interface.class.php file. The very first class definition is for the abstract class named MaestroTaskInterface. It is the MaestroTaskInterface class that you will be extending. The base class provides a wide variety of functionality for the Maestro UI which you will be leveraging for your Task.

Create a file named maestro_sample_task_interface.class.php file in your module's root folder and edit it. Add the following code to it:

<?php
class MaestroTaskInterfaceSample extends MaestroTaskInterface {
  function __construct($task_id=0, $template_id=0) {
    $this->_ask_type = 'Sample';
    $this->_is_interactive = MaestroInteractiveFlag::IS_NOT_INTERACTIVE;
    parent::__construct($task_id, $template_id);
}

  function display() {
    return theme('maestro_task_sample',
      array(
        'tdid' => $this->_task_id,
        'taskname' => $this->_taskname,
        'ti' => $this
        ));
  }

  function getEditFormContent() {
    $this->_fetchTaskInformation();
    return theme('maestro_task_sample_edit',
      array(
        'tdid' => $this->_task_id,
        'td_rec' => $this->_task_data,
        'ta_rec' => $this->_task_assignment_data
        ));
  }

  function save() {
    return parent::save();
  }

}

The first line of code in the file is where we are extending the base MaestroTaskInterface object. This means that as a developer, you have all of the methods and properties from the parent available to you in your class.

So, lets go through what we've got in this code segment now:

We have a constructor for this class that sets the overall task's type and defines whether the task is interactive (that is, has a human interaction element to it) or otherwise. Interactive is a simple bit flag that is either 1 or 0 (using Maestro defined constants) denoting interactive or not respectively. Interactive tasks require interactivity meaning that at some point, a human interaction with the task is required. Non interactive tasks are executed directly by the engine.

For our example, we've set the interactive flag to MaestroInteractiveFlag::IS_NOT_INTERACTIVE, denoting that this is NOT an interactive task. The task will be executed by the engine only. If your task requires human interactivity, you must use the MaestroInteractiveFlag::IS_INTERACTIVE constant.

The display method is responsible for returning the appropriate display themed file. The display method is for showing the task's non-edit mode display. As you can see in the file, we have used the Drupal theme function which means that we will have to implement a maestro_task_sample template for display use.

The getEditFormContent method is used to aggregate any settings you wish on the main edit panel for the task. Again, as you can see by the code, we are calling the Drupal theme function. We must implement the maestro_task_sample_edit template in order for us to visually see anything in the edit panel.

The save method is used to perform any task saving routines that you wish to implement. You dont' have to worry about saving the base task information, that will be done when you include a call to parent::save() in your method. So ensure that you add that call and the parent class will automatically save things like the task name, assignments etc.

As noted above, we need to create 2 template files to support the display and context menu edit functionality. First, create a file named 'theme/structure/tasks/maestro-task-sample.tpl.php'. The maestro-task-sample file will be used for the general block display of your maestro task. This file has to be created in the theme/structure/tasks hierarchy in your module's folder. Add the following content to it:

<?php
// $Id:
?>

<div class="maestro_task">
<div class="t"><div class="b"><div class="r"><div class="l"><div class="bl"><div class="br"><div class="tl-gry"><div class="tr-gry">

<div id="task_title<?php print $tdid; ?>" class="tm-gry maestro_task_title">
<?php print $taskname; ?>
</div>
<div class="maestro_task_body">
<?php print t('Sample'); ?>
</div>

</div></div></div></div></div></div></div></div>
</div>

The template (tpl) file above provides a basic display block that the Maestro UI mechanism will use to show it on the template editor page.

There is a key replacement variable in the tpl file. Namely it is the $taskname variable that is being set by the overall task name stored in the database. The task's name is set when you edit the task and THAT overall functionality is provided by Maestro's core.

Now for the second tpl file. The second tpl file is used for creating the edit panel display. You must create a second file named maestro-task-sample-edit.tpl.php in the same theme folder as the file above. Edit it and add the following to it:

<?php
// $Id:
?>

<table>
  <tr>
    <td>
      Add any fields in here you wish to edit.
      Save them via the Task UI's save method to the serialized task_data field.
      Display them in here with the $td_rec->task_data['...field...'] construct.
    </td>
  </tr>
</table>

Finally! We have the edit panel! As noted in the text for the edit, you as the developer need to determine what type of editable data to show. The edit panels for other tasks in Maestro are great examples of how we've pulled data from the task_data serialized field and used it in the edit panel.

Now that you've got the task's Maestro UI class created AND the two corresponding theme files, we can now edit the .module file we created in Step 1 to add in the module's hook_theme() implementation

Add the following lines of code to the .module file:

<?php

include('maestro_sample_task_interface.class.php');

function maestro_sample_task_theme() {
  return array(
    'maestro_task_sample' => array(
    'template' => 'theme/structure/tasks/maestro-task-sample',
    'variables' => array('tdid' => NULL)
    ),
    'maestro_task_sample_edit' => array(
    'template' => 'theme/structure/tasks/maestro-task-sample-edit',
    'variables' => array('tdid' => NULL, 'td_rec' => NULL, 'ta_rec' => NULL)
    ),
  );
}

function maestro_sample_task_maestro_get_taskobject_info() {
  $options = array(
    array('display_name' => 'Sample Task',
      'class_name' => 'MaestroTaskInterfaceSample',
      'file_location' => ''
      ),
    );
  return $options;
}

The first line we've added is an include() php directive telling php to include the extended task code we created above. Maestro already includes the base class definitions and adds those references during run time thus you do not have to re-include them.

The maestro_sample_task_theme() function implements Drupal's hook_theme() function so that the display and edit tpl files are accessible from the theme function calls we used in the code above.

Finally, we've created a maestro_sample_task_maestro_get_taskobject_info function which is an implemention of a Maestro hook for adding a task to the right-click menu on the template editor. If you do not implement the maestro_context_menu hook, your task will not show up in the Maestro editing UI. The $options array returns the task's display name, as well as its associated class name. The class_name array key needs to be set to the actual textual name of the Maestro UI class that handles its functionality. We created the MaestroTaskIntrefaceSample class above, and thus that is the value we set class_name to. The file_location array key is used to denote where the class file is actually located. Since we've accomplished this by using an include() php directive at the top of the file, we can safely leave this option blank.

Step 3 - Creating the Maestro Engine Hooks:

The Maestro engine is an OO mechanism, meaning that in order for you to write a new task type for it, you must extend the existing base task object. By doing so means that you will have all of the necessary mechanisms at your disposal to integrate with the engine without altering any engine code. Likewise, extending the existing base task object means that the appropriate methods that the engine needs are already defined for you.

Create the file maestro_sample_task_engine.class.php in the root of your module's folder. Add the following code to it:

class MaestroTaskTypeSample extends MaestroTask {

function execute() {
  $msg = 'Execute Task Type: "Sample" - properties: ' . print_r($this->_properties, true);
  watchdog('maestro',$msg);
  $this->setMessage( $msg . print_r($this->_properties, true) . '<br>');
  db_update('maestro_queue')
    ->fields(array('started_date' => time()))
    ->condition('id', $this->_properties->id, '=')
    ->execute();
  $this->executionStatus = TRUE;
  $this->completionStatus = MaestroTaskStatusCodes::STATUS_COMPLETE;
  return $this;
}

function prepareTask() {
  $serializedData = db_query("SELECT task_data FROM {maestro_template_data} WHERE id = :tid",
  array(':tid' => $this->_properties->taskid))->fetchField();
  $taskdata = @unserialize($serializedData);
  return array('handler' => '' ,'serialized_data' => $serializedData);
}

function getTaskConsoleURL() { }

}

The OO code above extends the existing MaestroTask class which provides a slew of defined methods which the engine uses as well as some methods that you as a developer can override or must implement.

The methods which you MUST implement are execute() and prepareTask().

execute() is, well, executed by the engine when the task is sitting in the queue.

prepareTask() is used during task creation time to prepare the task's internal data structures. If there is some data manipulation that you wish to carry out at task creation time, prepareTask is the method in which to do it in.

I've shown the getTaskConsoleURL() method above. This is an example of an overridden method that the base MaestroTask class already provides for you. The parent getTaskConsoleURL method simply returns a # symbol. In our implementation, we just override the method and return nothing as we are creating a non-interactive task. If you require a special Task Console URL for your Task type, you can define it using the getTaskConsoleURL method. Content type, Interactive and manual web tasks both have examples of creating a Task Console URL via the getTaskConsoleURL method.

Now, re-edit the .module file and place an include to the maestro_sample_task_engine.class.php you just created. The top of your .module file should look like this:

<?phpinclude('maestro_sample_task_interface.class.php');
include('maestro_sample_task_engine.class.php');
include_once('maestro_constants.class.php');

NOTE: Ensure that the rest of the code from Step 2 is still in the .module file!

The Final Module

Now that you've completed your module, all you have to do is compress the module and share it with others! The module installs through the regular install routine in Drupal and instantly provides the consumer of the module with the theme files, UI and engine hooks without them having to do any customization or file manipulation.

If your module has specific workflows that should accompany it, you may have to also include a workflow template to show how to use it. This is easily done via the workflow export. We will have a follow-up blog posting talking about how to create a workflow export and import module.

About Drupal Sun

Drupal Sun is an Evolving Web project. It allows you to:

  • Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
  • Facet based on tags, author, or feed
  • Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
  • View the entire article text inline, or in the context of the site where it was created

See the blog post at Evolving Web

Evolving Web