/ 
BPM-Engine-0.01
River stage zero No dependents
/ BPM::Engine::ProcessRunner

NAME

BPM::Engine::ProcessRunner - Runs workflow processes

VERSION

0.01

SYNOPSIS

  use BPM::Engine::ProcessRunner;

  my $callback = sub {
      my($runner, $entity, $action, $node, $instance) = @_;
      ...        
      return 1;
      };

  my $runner = BPM::Engine::ProcessRunner->new(
      process_instance => $instance,
      callback         => $callback,
      );

  $runner->start_process();

  # somewhere else, after completing a task, 
  # from an asynchronous task handler...

  $runner->complete_activity($activity, $instance, 1);

DESCRIPTION

Implements the workflow enactment logic.

CALLBACKS

The methods in this package emit callback events to a callback handler that may be passed to the constructor. If no callback handler is specified, the default return values are applied for these event calls.

The following callback actions are emitted for a process event:

start_process

Arguments: $process, $process_instance

start_activity

Arguments: $activity, $instance

continue_activity

Arguments: $activity, $instance

execute_activity

Argments: $activity, $instance

On this event, the callback should return false if the workflow process should be interrupted, true (default) if otherwise, which executes the activity and progresses the workflow.

execute_task

Argments: $task, $activity_instance

Returning true (default) will assume the task completed and call complete_activity() within ProcessRunner. Return false to halt the process thread.

complete_activity

Arguments: $activity, $instance

execute_transition

Arguments: $transition, $from_instance

complete_process

Arguments: $process, $process_instance

Returning true (default) will set the process state to closed.comleted.

Callback methods are directly available under its name prefixed by cb_, for example

   $runner->cb_start_process($process, $process_instance);

The callback handler receives the following options:

  • $runner

    This ProcessRunner instance.

  • $entity

    Type of entity the node represents. This is either process, activity, transition or task.

  • $action

    The event action called on the entity. This is either start, continue, complete or execute.

  • $node

    The first argument passed to the cb_* callback method, the respective entity node in the process that this callback is emitted for. On activity callbacks, this is the activity object, the task object on task callbacks, the process object for process entities, and transition for transition calls.

  • $instance

    The second argument passed to the cb_* callback method, being the instance for the node called on. In case of a transition callback, this is the activity instance the transition originated from (the activity being executed).

The callback should return true on succesful/normal processing of events, and false if something stalled or went wrong. Example:

my $callback = sub {
    my($runner, $entity, $action, $node, $instance) = @_;
        
    ## call your task execution sub when tasks need executing:
    if ($entity eq 'task' && $action eq 'execute') {
        return &execute_task($node, $instance); 
        }

    return 1;
    };

my $runner = BPM::Engine::ProcessRunner->new(
    callback => $callback,
    process_instance => $pi
    );

CONSTRUCTOR

new

Returns a new BPM::Engine::ProcessRunner instance. Optional arguments are:

process_instance => $process_instance

The process instance to run. Required.

callback => \&cb

Optional callback &cb which is called on all process instance events.

dryrun => 0 | 1

Boolean indicating whether or not the execute_task phase should be skipped. Defaults to 0.

ATTRIBUTE METHODS

process_instance

The BPM::Engine::Store::Result::ProcessInstance to run.

process

The BPM::Engine::Store::Result::Process of the process instance.

graph

The directed graph (an instance of Graph::Directed) for the process.

stash

Returns a hash reference stored as a heap, that is local to this runner object that lets you store any information you want.

dryrun

Returns the dryrun flag

evaluator

Returns the BPM::Engine::Util::ExpressionEvaluator object attached to this instance.

METHODS

start_process

$runner->start_process;

Call the 'start_process' callback, set the process instance to the 'started' state, and call start_activity() with an activity instance created for each of the auto_start start activities.

start_activity

$runner->start_activity($activity, $instance, $run);

start_activity() takes an activity, an activity instance and an optional 'run' flag. It calls the 'start_activity' callback, sets the activity instance state to 'assigned', enqueues the activity instance to be executed, and optionally runs all queued activity instances

continue_activity

$runner->continue_activity($activity, $instance, $run);

Call the 'continue_activity' callback, enqueue the activity instance to be executed, and optionally run all queued activity instances.

execute_task

$runner->execute_task($task, $instance);

Call the 'execute_task' callback, and returns 1 or 0 depending on the existance of a callback return value. This method is called on activity implementation when the activity instance is executed, and is meant to be used in Traits, not to be called directly.

complete_activity

$runner->complete_activity($activity, $instance, $run);

Call the 'complete_activity' callback, sets the activity instance state to 'closed.completed', and sets the completion datetime. and either calls complete_process() Outgoing transitions, if any, are followed. If it's an end activity and there are no active activity instances left, complete_process() is called, otherwise it optionally runs all enqueued activity instances.

complete_process

$runner->complete_process;

Return unless the 'complete_process' returns true. Set the process instance state to 'closed.completed', set the completion datetime, and clear the activity instance execution queues.

LOGGING METHODS

$runner->debug('Something happened');

log, debug, info, notice, warning, error, critical, alert, emergency

AUTHOR

Peter de Vos, <sitetech@cpan.org>

COPYRIGHT AND LICENSE

Copyright (c) 2010, 2011 Peter de Vos <sitetech@cpan.org>.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.