Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Workflow::State(3)    User Contributed Perl Documentation   Workflow::State(3)

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

       This documentation describes version 1.14 of this package

	# This is an internal object...
	  <state name="Start">
	    <action ...	resulting_state="Progress" />
	  <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" />
	  <state name="Approved" autorun="yes">
	    <action ...	resulting_state="Completed" />

       Each Workflow::State 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" />

       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" />

       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.

       If no action or more than one action is available at the	time the
       workflow	enters an autorun state, Workflow will throw an	error. There
       are some	conditions where this might not	be what	you want. For example
       when you	have a state which contains an action that depends on some
       condition. If it	is true, you might be happy to move on to the next
       state, but if it	is not,	you are	fine to	come back and try again	later
       if the action is	available. This	behaviour can be achived by setting
       the 'may_stop' property to yes, which will cause	Workflow to just
       quietly stop automatic execution	if it does not have a single action to

       get_conditions( $action_name )

       Returns a list of Workflow::Condition 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.


       Returns list of all action names	available in this state.

       get_available_action_names( $workflow, $group )

       Returns all actions names that are available given the data in
       $workflow. Each action name returned will return	true from
       is_action_available().  $group is optional parameter. If	it is set,
       additional check	for group membership will be performed.

       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.

       clear_condition_cache ( )

       Empties the condition result cache for a	given state.

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

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


       Name of this state (required).


       Description of this state (optional).


       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.


       Returns true if the state may stop automatic execution silently,	false
       if not. To set to true the property value should	be 'yes', 'true' or 1.

       init( $config )

       Assigns 'state',	'description', 'autorun' and 'may_stop'	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.




       Copyright (c) 2003-2007 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.

       Jonas B.	Nielsen	(jonasbn) <> is	the current

       Chris Winters <>

perl v5.32.1			  2021-02-28		    Workflow::State(3)


Want to link to this manual page? Use this URL:

home | help