1Workflow::State(3) User Contributed Perl Documentation Workflow::State(3)
2
6 Workflow::State - Information about an individual state in a workflow
7
9 # This is an internal object...
10 <workflow...>
11 <state name="Start">
12 <action ... resulting_state="Progress" />
13 </state>
14 ...
15 <state name="Progress" description="I am in progress">
16 <action ... >
17 <resulting_state return="0" state="Needs Affirmation" />
18 <resulting_state return="1" state="Approved" />
19 <resulting_state return="*" state="Needs More Info" />
20 </action>
21 </state>
22 ...
23 <state name="Approved" autorun="yes">
24 <action ... resulting_state="Completed" />
25 ...
26
28 Each Workflow::State object represents a state in a workflow. Each
29 state can report its name, description and all available actions. Given
30 the name of an action it can also report what conditions are attached
31 to the action and what state will result from the action (the 'result‐
32 ing state').
33 Resulting State
35 The resulting state is action-dependent. For instance, in the following
37 example you can perform two actions from the state 'Ticket Created' --
38 'add comment' and 'edit issue':
39 <state name="Ticket Created">
41 <action name="add comment"
42 resulting_state="NOCHANGE" />
43 <action name="edit issue"
44 resulting_state="Ticket In Progress" />
45 </state>
46 If you execute 'add comment' the new state of the workflow will be the
48 same ('NOCHANGE' is a special state). But if you execute 'edit issue'
49 the new state will be 'Ticket In Progress'.
50 You can also have multiple return states for a single action. The one
52 chosen by the workflow system will depend on what the action returns.
53 For instance we might have something like:
54 <state name="create user">
56 <action name="create">
57 <resulting_state return="admin" state="Assign as Admin" />
58 <resulting_state return="helpdesk" state="Assign as Helpdesk" />
59 <resulting_state return="*" state="Assign as Luser" />
60 </action>
61 </state>
62 So if we execute 'create' the workflow will be in one of three states:
64 'Assign as Admin' if the return value of the 'create' action is
65 'admin', 'Assign as Helpdesk' if the return is 'helpdesk', and 'Assign
66 as Luser' if the return is anything else.
67 Autorun State
69 You can also indicate that the state should be automatically executed
71 when the workflow enters it using the 'autorun' property. Note the
72 slight change in terminology -- typically we talk about executing an
73 action, not a state. But we can use both here because an automatically
74 run state requires that one and only one action is available for run‐
75 ning. That doesn't mean a state contains only one action. It just means
76 that only one action is available when the state is entered. For exam‐
77 ple, you might have two actions with mutually exclusive conditions
78 within the autorun state.
79 If no action or more than one action is available at the time the work‐
81 flow enters an autorun state, Workflow will throw an error. There are
82 some conditions where this might not be what you want. For example when
83 you have a state which contains an action that depends on some condi‐
84 tion. If it is true, you might be happy to move on to the next state,
85 but if it is not, you are fine to come back and try again later if the
86 action is available. This behaviour can be achived by setting the
87 'may_stop' property to yes, which will cause Workflow to just quietly
88 stop automatic execution if it does not have a single action to exe‐
89 cute.
90
92 get_conditions( $action_name )
93 Returns a list of Workflow::Condition objects for action $action_name.
95 Throws exception if object does not contain $action_name at all.
96 contains_action( $action_name )
98 Returns true if this state contains action $action_name, false if not.
100 is_action_available( $workflow, $action_name )
102 Returns true if $action_name is contained within this state and it
104 matches any conditions attached to it, using the data in the context of
105 the $workflow to do the checks.
106 evaluate_action( $workflow, $action_name )
108 Throws exception if action $action_name is either not contained in this
110 state or if it does not pass any of the attached conditions, using the
111 data in the context of $workflow to do the checks.
112 get_all_action_names()
114 Returns list of all action names available in this state.
116 get_available_action_names( $workflow )
118 Returns all actions names that are available given the data in $work‐
120 flow. Each action name returned will return true from is_action_avail‐
121 able().
122 get_next_state( $action_name, [ $action_return ] )
124 Returns the state(s) that will result if action $action_name is exe‐
126 cuted. If you've specified multiple return states in the configuration
127 then you need to specify the $action_return, otherwise we return a hash
128 with action return values as the keys and the action names as the val‐
129 ues.
130 get_autorun_action_name( $workflow )
132 Retrieve the action name to be autorun for this state. If the state
134 does not have the 'autorun' property enabled this throws an exception.
135 It also throws an exception if there are multiple actions available or
136 if there are no actions available.
137 Returns name of action to be used for autorunning the state.
139
141 All property methods act as a getter and setter. For example:
142 my $state_name = $state->state;
144 $state->state( 'some name' );
145 state
147 Name of this state (required).
149 description
151 Description of this state (optional).
153 autorun
155 Returns true if the state should be automatically run, false if not. To
157 set to true the property value should be 'yes', 'true' or 1.
158 may_stop
160 Returns true if the state may stop automatic execution silently, false
162 if not. To set to true the property value should be 'yes', 'true' or 1.
163
165 init( $config )
166 Assigns 'state', 'description', 'autorun' and 'may_stop' properties
168 from $config. Also assigns configuration for all actions in the state,
169 performing some sanity checks like ensuring every action has a 'result‐
170 ing_state' key.
171
173 Workflow
174 Workflow::Condition
176 Workflow::Factory
178
180 Copyright (c) 2003-2004 Chris Winters. All rights reserved.
181 This library is free software; you can redistribute it and/or modify it
183 under the same terms as Perl itself.
184
186 Chris Winters <chris@cwinters.com>
187perl v5.8.8 2007-04-25 Workflow::State(3)