Zeta Components - high quality PHP components

Tutorial
API

eZ Components - WorkflowDatabaseTiein

Introduction
Class overview
Database tables
- Mysql schema
- Database independent schema
Usage

Introduction

The WorkflowDatabaseTiein component allows you to store workflows in a relational database. It also provides a workflow execution environment that makes workflow execution states persistent. The persistence allows you to resume workflows between different PHP requests.

Class overview

ezcWorkflowDatabaseExecution

Workflow executer that suspends and resumes workflow execution states to and from a database.

ezcWorkflowDatabaseDefinitionStorage: Workflow definition storage handler that saves and loads workflow definitions to and from a database.

Database tables

This component requires a specific set of tables to exist in your database. As a reference of the tables and fields required we have provided a schema for MySQL. To ease the installation process we also provide the database independent .dba file.

Mysql schema

This is the reference schema for MySQL 5.

DROP TABLE IF EXISTS workflow;
CREATE TABLE workflow (
  workflow_id      INTEGER      UNSIGNED NOT NULL AUTO_INCREMENT,
  workflow_name    VARCHAR(255)          NOT NULL,
  workflow_version INTEGER      UNSIGNED NOT NULL DEFAULT 1,
  workflow_created INTEGER               NOT NULL,

  PRIMARY KEY              (workflow_id),
  UNIQUE  KEY name_version (workflow_name, workflow_version)
) ENGINE=InnoDB;

DROP TABLE IF EXISTS node;
CREATE TABLE node (
  workflow_id        INTEGER      UNSIGNED NOT NULL REFERENCES workflow.workflow_id,
  node_id            INTEGER      UNSIGNED NOT NULL AUTO_INCREMENT,
  node_class         VARCHAR(255)          NOT NULL,
  node_configuration BLOB                      NULL,

  PRIMARY KEY             (node_id),
          KEY workflow_id (workflow_id)
) ENGINE=InnoDB;

DROP TABLE IF EXISTS node_connection;
CREATE TABLE node_connection (
  node_connection_id INTEGER UNSIGNED NOT NULL AUTO_INCREMENT,
  incoming_node_id   INTEGER UNSIGNED NOT NULL,
  outgoing_node_id   INTEGER UNSIGNED NOT NULL,

  PRIMARY KEY (node_connection_id)
) ENGINE=InnoDB;

DROP TABLE IF EXISTS variable_handler;
CREATE TABLE variable_handler (
  workflow_id INTEGER      UNSIGNED NOT NULL REFERENCES workflow.workflow_id,
  variable    VARCHAR(255)          NOT NULL,
  class       VARCHAR(255)          NOT NULL,

  PRIMARY KEY (workflow_id, class)
) ENGINE=InnoDB;

DROP TABLE IF EXISTS execution;
CREATE TABLE execution (
  workflow_id              INTEGER UNSIGNED NOT NULL REFERENCES workflow.workflow_id,
  execution_id             INTEGER UNSIGNED NOT NULL AUTO_INCREMENT,
  execution_parent         INTEGER UNSIGNED     NULL REFERENCES execution.execution_id,
  execution_started        INTEGER          NOT NULL,
  execution_suspended      INTEGER              NULL,
  execution_variables      BLOB                 NULL,
  execution_waiting_for    BLOB                 NULL,
  execution_threads        BLOB                 NULL,
  execution_next_thread_id INTEGER UNSIGNED NOT NULL,

  PRIMARY KEY                  (execution_id, workflow_id),
          KEY execution_parent (execution_parent)
) ENGINE=InnoDB;

DROP TABLE IF EXISTS execution_state;
CREATE TABLE execution_state (
  execution_id        INTEGER UNSIGNED NOT NULL REFERENCES execution.execution_id,
  node_id             INTEGER UNSIGNED NOT NULL REFERENCES node.node_id,
  node_state          BLOB                 NULL,
  node_activated_from BLOB                 NULL,
  node_thread_id      INTEGER UNSIGNED NOT NULL,

  PRIMARY KEY (execution_id, node_id)
) ENGINE=InnoDB;

Database independent schema

To load the .dba definition into your database you must have the DatabaseSchema component installed. Save the file to your harddrive and use the following code to load it:

<?php
$db = ezcDbInstance::get(); // replace if you get your database instance differently
$schema = ezcDbSchema::createFromFile( 'array', 'workflow.dba' );
$schema->writeToDb( $db );
?>

You may need to extend 'workflow.dba' to contain the proper path to the file.

Usage

Storing a workflow to database

This example shows how to store a workflow to database. The example assumes that the workflow is available in the $workflow variable.

<?php
// Set up database connection.
$db = ezcDbFactory::create( 'mysql://test@localhost/test' );
// Set up workflow definition storage (database).
$definition = new ezcWorkflowDatabaseDefinitionStorage( $db );
// Save workflow definition to database.
$definition->save( $workflow );
?>

Loading a workflow from the database

This example loads the workflow named 'test' into the variable $workflow.

<?php
// Set up database connection.
$db = ezcDbFactory::create( 'mysql://test@localhost/test' );
// Set up workflow definition storage (database).
$definition = new ezcWorkflowDatabaseDefinitionStorage( $db );
// Load latest version of workflow named "Test".
$workflow = $definition->loadByName( 'Test' );
?>

Executing a workflow

Executing a workflow is done by calling the method start on the execution object. This example shows how to execute the workflow test that is stored in the database. The id that is returned by the execute method identifies this execution thread and can be used later if the workflow must be resumed.

Executing a workflow using the ezcWorkflowDatabaseExecution executer requires the definition of the workflow (and all of its sub-workflows) to be stored in the database.

<?php
// Set up database connection.
$db = ezcDbFactory::create( 'mysql://test@localhost/test' );
// Set up workflow definition storage (database).
$definition = new ezcWorkflowDatabaseDefinitionStorage( $db );
// Load latest version of workflow named "Test".
$workflow = $definition->loadByName( 'Test' );
// Set up database-based workflow executer.
$execution = new ezcWorkflowDatabaseExecution( $db );
// Pass workflow object to workflow executer.
$execution->workflow = $workflow;
// Start workflow execution.
$id = $execution->start();
?>

Resuming a workflow execution

If a workflow execution is suspended and needs to be resumed the method resume should be used. This example shows how to resume a suspended workflow and provide the input data 'choice'. The id is the one provided by the original call to execute.

<?php
// Set up database connection.
$db = ezcDbFactory::create( 'mysql://test@localhost/test' );
// Set up database-based workflow executer.
$execution = new ezcWorkflowDatabaseExecution( $db, $id );
// Resume workflow execution.
$execution->resume(
array( 'choice' => true )
);
?>

Cancelling a workflow execution

If a workflow execution is suspended it can be cancelled by calling the cancel() method on the executer object.

<?php
// Set up database connection.
$db = ezcDbFactory::create( 'mysql://test@localhost/test' );
// Set up database-based workflow executer.
$execution = new ezcWorkflowDatabaseExecution( $db, $id );
// Cancel workflow execution.
$execution->cancel();
?>

This method is also automatically called when the workflow execution reaches a ezcWorkflowNodeCancel node.

When the execution of a workflow is cancelled all nodes that are currently activated will be deactivated and the optional sequence of final activities that starts in $workflow->finallyNode is activated.