Workflow::State - Information about an individual state in a workflow


NAME

Workflow::State - Information about an individual state in a workflow


SYNOPSIS

 # This is an internal object...
 <workflow...>
   <state name="Start">
     <action ... resulting_state="Progress" />
   </state>
      ...
   <state name="Progress" description="I am in progress">
     <action ... >
        <resulting_state return="0" state="Needs Affirmation" />
        <resulting_state return="1" state="Approved" />
        <resulting_state return="*" state="Needs More Info" />
     </action>
   </state>
      ...
   <state name="Approved" autorun="yes">
     <action ... resulting_state="Completed" />
      ...


DESCRIPTION

Each the Workflow::State manpage object represents a state in a workflow. Each state can report its name, description and all available actions. Given the name of an action it can also report what conditions are attached to the action and what state will result from the action (the 'resulting state').

Resulting State

The resulting state is action-dependent. For instance, in the following example you can perform two actions from the state 'Ticket Created' -- 'add comment' and 'edit issue':

  <state name="Ticket Created">
     <action name="add comment"
             resulting_state="NOCHANGE" />
     <action name="edit issue"
             resulting_state="Ticket In Progress" />
   </state>

If you execute 'add comment' the new state of the workflow will be the same ('NOCHANGE' is a special state). But if you execute 'edit issue' the new state will be 'Ticket In Progress'.

You can also have multiple return states for a single action. The one chosen by the workflow system will depend on what the action returns. For instance we might have something like:

  <state name="create user">
     <action name="create">
         <resulting_state return="admin"    state="Assign as Admin" />
         <resulting_state return="helpdesk" state="Assign as Helpdesk" />
         <resulting_state return="*"        state="Assign as Luser" />
     </action>
   </state>

So if we execute 'create' the workflow will be in one of three states: 'Assign as Admin' if the return value of the 'create' action is 'admin', 'Assign as Helpdesk' if the return is 'helpdesk', and 'Assign as Luser' if the return is anything else.

Autorun State

You can also indicate that the state should be automatically executed when the workflow enters it using the 'autorun' property. Note the slight change in terminology -- typically we talk about executing an action, not a state. But we can use both here because an automatically run state requires that one and only one action is available for running. That doesn't mean a state contains only one action. It just means that only one action is available when the state is entered. For example, you might have two actions with mutually exclusive conditions within the autorun state.


PUBLIC METHODS

get_conditions( $action_name )

Returns a list of the Workflow::Condition manpage objects for action $action_name. Throws exception if object does not contain $action_name at all.

contains_action( $action_name )

Returns true if this state contains action $action_name, false if not.

is_action_available( $workflow, $action_name )

Returns true if $action_name is contained within this state and it matches any conditions attached to it, using the data in the context of the $workflow to do the checks.

evaluate_action( $workflow, $action_name )

Throws exception if action $action_name is either not contained in this state or if it does not pass any of the attached conditions, using the data in the context of $workflow to do the checks.

get_all_action_names()

Returns list of all action names available in this state.

get_available_action_names( $workflow )

Returns all actions names that are available given the data in $workflow. Each action name returned will return true from is_action_available().

get_next_state( $action_name, [ $action_return ] )

Returns the state(s) that will result if action $action_name is executed. If you've specified multiple return states in the configuration then you need to specify the $action_return, otherwise we return a hash with action return values as the keys and the action names as the values.

get_autorun_action_name( $workflow )

Retrieve the action name to be autorun for this state. If the state does not have the 'autorun' property enabled this throws an exception. It also throws an exception if there are multiple actions available or if there are no actions available.

Returns name of action to be used for autorunning the state.


PROPERTIES

All property methods act as a getter and setter. For example:

 my $state_name = $state->state;
 $state->state( 'some name' );

state

Name of this state (required).

description

Description of this state (optional).

autorun

Returns true if the state should be automatically run, false if not. To set to true the property value should be 'yes', 'true' or 1.


INTERNAL METHODS

init( $config )

Assigns 'state', 'description', and 'autorun' properties from $config. Also assigns configuration for all actions in the state, performing some sanity checks like ensuring every action has a 'resulting_state' key.


SEE ALSO

Workflow

the Workflow::Condition manpage

the Workflow::Factory manpage


COPYRIGHT

Copyright (c) 2003-2004 Chris Winters. All rights reserved.

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


AUTHORS

Chris Winters <chris@cwinters.com>

 Workflow::State - Information about an individual state in a workflow