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.