===== Vortex WorkFlows =====

As of version 1.2.1120 the Vortex has a built in workflow editor. The workflows are connected to tables using various triggers, scripts and mapping rules and allow for automated processes to be run.
Workflows are edited in their own section in the admin tools and will be further discussed below.\\
{{:vortex:workflow.png|}}

==== Overview ====

In //Vortex//, a WorkFlow is a predefined path of actions performed in sequence on a given object or set of objects.\\
A workflow can include conditionals used to determin which path the object will propagate through the workflow, dead ends that terminate the workflow prematurely as well as other workflows. Using theese building blocks workflows can be used for anything as simple as setting a status field for all new records in a table, to complex tasks including (but not limited to) calling webservices, sending e-mail messages, fetching information from the web and so forth.

The real advantage of using workflows instead of scripts is that workflows are easy to grasp as they are graphically represented to the user both during administration and in the details view of all //TableRecords// currently propagating a workflow. Changing the path of actions in a workflow is as easy as dragging the mouse around and changes will affect all posts that is currently propagating the workflow.

==== Administration - building your own workflows ====

If the workflow engine is enabled in your //Vortex// installation the workflow administration is accessable under the //Admin// menu. Editing workflows is done in the same way as all tables are edited. First you need to create a new workflow by entering its name in the //ShowList// table visible. The fields that describes a workflow are the following:
|Field|Description|
|name|The name of the workflow. Please keep theese names unique since theese are used to reference the workflow from within other workflows.|
|startnode|This is the name of the first script in the workflow. This is the entry point for the workflow. If multiple scripts has the same name, the script that was first created will have precedence.|
|data|This is the data of the workflow. This field will be automatically filled with data from the workflow edit view, please do not alter this data if you're not sure what you're doing as it will cripple the workflow.|

==== Workflow Scripts ====

All Scripts in the WorkFlow engine has the possibility to //Change name//, create a //New connection from// and //Remove//. Theese functions should not require any further explaining. However the common attribute //Scriptmethod// might be worth mentioning.
The //Scriptmethod// attribute defines which method to execute when executing this specific script. This defaults to the //execute// method of the Script class, but can be changed to whatever you want. If you implement another method accepting a vxWorkFlowData parameter you can, for certain instances of scripts, point to this method instead and it will then execute when the script is run.

=== Standard scripts ===

Here is a listing of the default scripts included in the Vortex WorkFlow engine.

=== Checkpoint ===
{{:vortex:scripts_checkpoint.png |}} The //Checkpoint// is simply a marker to use for better being able to follow the path of an executing WorkFlow. It performs no action whatsoever but is good to use as a dead-end node or similar.

Attributes: None.

=== Condition ===
{{:vortex:scripts_condition.png |}} The //Condition// script evaluates a condition and chooses execution path accordingly. The return value of the condition is the name of the path chosen, if found. If not found the path named //_// is chosen.

Attributes:
  * Match: A //SearchString// to check wether the active TableRecord matches. Returns true or false.
  * Get: A [[vortex:scripting:vxstring|VXString]] defining what value to retrieve from the active TableRecord.

=== Send email ===
{{:vortex:scripts_email.png |}} Sends an email to a recipient.

Attributes: 
  * From address: A [[vortex:scripting:vxstring|VXString]] defining the address to set as the sender of the email
  * To address: A [[vortex:scripting:vxstring|VXString]] defining the address to set as the recipient of the email
  * Subject: A [[vortex:scripting:vxstring|VXString]] defining the subject of the email
  * Body: A [[vortex:scripting:vxstring|VXString]] defining the body of the email

=== Start ===
{{:vortex:scripts_start.png |}} The //Start// script is the starting point of the workflow. If the attributes matches a saved TableRecord this workflow is started for that record.

Attributes:
  * Table: The name of the table to match. If left empty it matches all tables, to match no tables set to //-// or similar.
  * Search criteria: A //searchstring// that is used to match the record.
  * New post: If set to //1// this script will only match new posts, all previously created nodes will not match.

=== Wait for criteria ===
{{:vortex:scripts_wait.png |}} Pauses WorkFlow execution until the criteria is met

Attributes:
  * Search criteria: A //SearchString// defining the criteria to be met, ex //[step1=1]//

=== Workflow ===
{{:vortex:scripts_workflow.png |}} Executes another WorkFlow on this TableRecord. The TableRecord does not have to meet the target WorkFlows Start criteria.

Attributes: 
  * WorkFlow: Name of the WorkFlow to execute

=== Making your own custom scripts ===

Custom WorkFlow scripts are created by adding a class extending the //vxWorkFlowScript// interface to the scope of the Vortex. This is done by adding it to a //.php// file in the //scripts/// directory in the DBI.

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

The class has a statically accessable member //$SCRIPTDEF// which is the script definition for this script. The definition is on the form: name;icon;parametername=parametervalue

Adding a //log// Script will look something like:
<code php>
class myFWScript extends vxWorkFlowScript {
  public static $SCRIPTDEF = "Log;gfx/log_64_64.png;Logmessage=";
}  
</code>

When the script is executed the //execute// method is called in the class instance, and a //vxWorkFlowData// is passed with the call.  The //vxWorkFlowData// contains references to all parameters and the current tablerecord on which the WorkFlow is run, and they can be accessed in the following way:

<file php workflow.php>
class myFWScript extends vxWorkFlowScript {
  public static $SCRIPTDEF = "Log;gfx/log_64_64.png;Logmessage=";
  
  public function execute( &$vxWorkFlowData ) {
    $params = $vxWorkFlowData->currentScript->parameters;
    if( $params['Logmessage'] == '' ) return '_';
    
    $vxWorkFlowData->tableRecord->set( 'logField', $params['Logmessage'] );
    return '1';
  }
}  
</file>


==== Tracking current workflow executions ====

For TableRecords that currently are connected to a not-finished WorkFlow there will be a //Category// shown in the details view called //Active Workflows//. Here the progress of all the currently connected workflows is shown.
{{ :vortex:examples:active_workflow_2.png?600 |}}

The green path is the path that the WorkFlow has taken in it's execution, and the blue circle is where it's stuck at right now.