Stilit Wiki

For an in-depth documentation on WorkFlows, see the WorkFlow documentation in the User Manual.

A working Vortex environment of at least version 1.2.1120 with WorkFlow engine enabled. Before activating WorkFlow we recommend that you upgrade to the latest version of the Vortex.

OBSERVE, version 1.2.1246 fixed a matching bug regarding WorkFlows, so if you're running an earlier version than 1.2.1246 please upgrade before continuing this tutorial.

For more information on how to create the table, see the Table Creation example

We'll create a table called workflowtest with the following fields:

• identification, text
• mailto, text
• step1, checkbox
• step2, checkbox
• step3, checkbox
• logfield, textarea, extra rows:10,cols:4
• sendemail, checkbox
• dosomethingelse, checkbox

Give the fields descriptives of your choosing. We also added a few category fields to make the presentation nicer, and remember to check the checkbox Enable WorkFlow for the table.

• Go to the Admin menu and choose WorkFlow.
• Create a new workflow by giving it a name and clicking Save
• Enter the Details view for the created workflow by left-clicking the i symbol on the workflow record

Now you will see the WorkFlow editor.

In the workflow fields you will have a field called Start node with the default value Start. This is the name of the WorkFlow script that will be activated as a start condition for this Workflow. Start is a good name for this script, so we'll let that be unchanged.

Now, create a start node by right-clicking the WorkFlow editor area and choosing the Start script. Now edit the properties for the Start script by right-clicking the script.

• If you changed the name of the Start node, change the name of this node to the same value.
• Enter the name of the table to activate this WorkFlow for in the table field, in this case workflowtest
• The searchcriteria is a normal Vortex SearchString (see |Filters) which will have to match the record for the WorkFlow to start. Since we want the workflow to start for all new posts we'll leave this field empty.
• New post tells the WorkFlow wether to only trigger on new posts or all posts, we'll want it to trigger on new posts so we'll set this to 1
• Scriptmethod - We'll cover this field later, leave the default value for now

Pick the Start script up by left-clicking and dragging it, and drop it wherever you want it to be in the editor window. Usually the start script goes far to the left.

Now the WorkFlow will start for all new records in the workflowtest table. Now we'll want it to do something, and the first thing we will do is to wait for a start criteria to be set. We'll add a Wait for criteria script that'll wait until the step1 flag is set on the record.

Add the script by right-clicking in the work area and choosing Wait for criteria. This will add the script to the work area.

Edit the parameters for this script by right-clicking it.

• Change the name of this node to Wait for Step1
• Set the Search criteria to [step1=1]
• Leave the script method as is

Now we've created a node that will wait until the Search criteria is met for the current record, that is, until the step1 field is set to 1. Now we need to connect this node to the start node.

• Right-click the start node and select New connection from
• In the popup box, choose the name of the connection. The default value is fine for unconditional connections.
• Left-click the target node, ie our Wait for step1
• A connection is now created leading from the start node to the condition node

This means that after the Start condition is met, the WorkFlow will traverse this connection to the next node Wait for step1 where it will wait until the condition is met.

What we want to do now is to check wether the sendemail flag is set, and if so send an email to the mailto recipient. To do this, we create a new Script node of the Condition type and connect it from the Wait for Step1 node.

Rename this node to Send email?. The Match attribute of the Condition node is a Searchstring that the current record is compared to. If it matches, true is returned, otherwise false is returned. We can use the Match attribute to check if the flag is set by giving it the value [sendemail=1] but the easier and better way to do this is to use the Get attribute. The Get attribute fetches the value from the given VXString. If we set the value [sendemail] in the Get attribute it will return the value of the sendemail field in the current record.

After having sent the email we will want the WorkFlow to wait until the step2 flag is set, so create a Wait for critieria node, rename it to something that describes what it'll do, and make it wait for the step2 flag to be set in the same way as step1 above.

Now to create a node that'll send an email, simply create a Send mail script, rename it if you wish, and drag it to a fitting position in the work area. The attributes of the Send mail script is quite self explanatory and we won't describe them further. Configure the script to send an email to [mailto] recipient, with some static content.

Now choose a new connection from the condition node. Since this is a conditional connection the name is important, the condition will trigger the connection named as the returned value. If a Match attribute is set, the connection should be named true or false and when the Get attribute is used, the connection should be named after the return values. If no connection matches the return value, the connection named _ will be triggered. Since sendemail is a checkbox having values 0 or 1 we will make a connection named _ from the condition to the Wait for step2 node, and a connection named 1 from the condition to the Send mail node.

If you want to remove a connection, simply right-click the name box and choose Remove.

Make a _ connection from the Send mail node to the Wait for Step2 node to make sure the WorkFlow doesn't halt after sending the email.

So far we've been using the standard components of the Vortex WorkFlow which cover basic WorkFlow functions as conditions, waiting and so on. Now we want to do something else, so we will have to create our own WorkFlow Script.

All .php-files residing in the scripts/ diretory in the DBI are automatically included in the scope of the Vortex, so to add functionallity to the DBI this functionallity has to originate in files in this directory. To add custom WorkFlow scripts we create the file scripts/workflow.php and write the Scripts there.

A WorkFlow script in the Vortex is made from a class extending the vxWorkFlowScript interface, so the first step is creating this class:

class myWFScript extends vxWorkFlowScript {}

The class contains a static member $SCRIPTDEF describing the Script to the Vortex, for more information see WorkFlow manual.

Creating the Script the class will look like this:

workflow.php 1

<?php
// Custom WorkFlow scripts for this DBI
 
class myWFScript extends vxWorkFlowScript {
  public static $SCRIPTDEF = "AppendLog;?vortex_callertype=getlocal&vortex_localfilename=gfx/log_64_64.png;Append=1;Message=";
 
  public function execute( &$vxWorkFlowData ) {
    $param = $vxWorkFlowData->currentScript->parameters;
    $cm = $vxWorkFlowData->tableRecord->get( 'logfield' );
 
    if( $param['Message'] != '' ) {
      if( $param['Append']->value == '0' ) $cm = "";
      $cm .= $param['Message']->value;
    }
    $vxWorkFlowData->tableRecord->set( 'logfield', $cm );
    return '_';
  }
}
?>

Where the icon is this one: which you put in the public/gfx directory in your DBI path.

What this code is:

• Defines a new class inheriting vxWorkFlowScript telling the Vortex that this is a WorkFlow script
• Creates a script definition naming the script AppeldLog, giving it an icon and two attributes: Append and Message, where Append has the default value of 1
• Implements an execute method that reads the parameters from the supplied vxWorkFlowData object, and changes the logfield value of the connected tableRecord.
• The return value of the execute method is the name of the connection to traverse. _ is the default value.

After step2 we will want to add something to the log. Add a AppendLog script to the workflow after Wait for Step2, name it and let it append a Message to the log. You should be able to do this by now. As you can see the Script method is set to myWFScript:execute which is the Class and Method that will be executed when this node is run. You can implement several methods in the same script and execute them differently by changing this attribute of the script in the work area.

You can include other WorkFlows to this one by adding the WorkFlow script. First create a new workflow, call it Log something and just let it log something. Should look something like this:

Now add a condition to our first WorkFlow letting it execute this Log something if the flag dosomethingelse is set in the tableRecord:

The WorkFlow attribute of the Workflow script is the name of the workflow to execute. Since the executed workflow will not trigger anything on its own, all attributes in the start condition are left empty except the table. An empty table will match ALL tables, so set the table attribute to - to make it not match anything. When there are no more connections leading from the currently executing script the workflow ends.

Now go to the table we created in the first step. You might have to log out and log in again to refresh the table list in the menu. Create a new record in this table, leaving all step-flags unchecked and the logfield emtpy. Save the record and enter the Details view for the record. It should look something like this: As you can see we've checked the step1 flag in the example to let the WorkFlow proceed past the first waiting point. The green path is the path the WorkFlow has taken, which is the Start → Wait for Step1 - >Send email? → Send email → Wait for Step2. The blue circle means that this is where the execution is halting right now.

Once the WorkFlow has finished it will disappear from the Details View of the record.

You have now created a complex workflow, a WorkFlow script of your own, and a linked WorkFlow. Using this toolset you can create very powerful graphical tools.