===== Vortex WorkFlow - setup and customize =====

For an in-depth documentation on WorkFlows, see [[vortex:workflow|the WorkFlow documentation]] in the User Manual.

=== Requirements ===

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 [[vortex:installation#upgrading|upgrade]] before continuing this tutorial. **

=== Step 1: Creating a table for the Workflow to process ===

For more information on how to create the table, see the [[vortex:examples:create_table|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.
{{ :vortex:examples:vortex_18.png?600 |}}

=== Step 2: Creating a new WorkFlow to catch the creation of new posts in 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. {{ :vortex:examples:workflow_2.png?600 |}}

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.{{ :vortex:examples:workflow_3.png |}}
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 [[vortex:usermanual#filters||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.

=== Step 2: Waiting for Step1 criteria to be set ===

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.{{ :vortex:examples:workflow_4.png |}}

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

{{ :vortex:examples:workflow_5.png |}}

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.

=== Step 3: Choosing path depending on field value ===

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 [[vortex:scripting:vxstring|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. {{ :vortex:examples:workflow_6.png |}}

=== Step 4: Make a custom Script to log events to the logfield of the current record ===

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:

<code php>
class myWFScript extends vxWorkFlowScript {}
</code>

The class contains a static member //$SCRIPTDEF// describing the Script to the Vortex, for more information see [[id=vortex:workflow|WorkFlow manual]].

Creating the Script the class will look like this:
<file php 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 '_';
  }
}
?>
</file>

Where the icon is this one:
{{ :vortex:examples:log_64_64.png |}}
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.

=== Step 5: Using our new log script to log information to the current record ===

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.

=== Step 6: Executing another WorkFlow ===

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:
{{ :vortex:examples:workflow_7.png |}}

Now add a condition to our first WorkFlow letting it execute this //Log something// if the flag //dosomethingelse// is set in the tableRecord:
{{ :vortex:examples:workflow_8.png |}}

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.

=== Step 7: Testing ===

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:
{{ :vortex:examples:active_workflow_2.png?600 |}}
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.

=== Summary ===

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.