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 documentation describes version 1.61 of this package
10
12 # This is an internal object...
13 <workflow...>
14 <state name="Start">
15 <action ... resulting_state="Progress" />
16 </state>
17 ...
18 <state name="Progress" description="I am in progress">
19 <action ... >
20 <resulting_state return="0" state="Needs Affirmation" />
21 <resulting_state return="1" state="Approved" />
22 <resulting_state return="*" state="Needs More Info" />
23 </action>
24 </state>
25 ...
26 <state name="Approved" autorun="yes">
27 <action ... resulting_state="Completed" />
28 ...
29
31 Each Workflow::State object represents a state in a workflow. Each
32 state can report its name, description and all available actions. Given
33 the name of an action it can also report what conditions are attached
34 to the action and what state will result from the action (the
35 'resulting state').
36 Resulting State
38 The resulting state is action-dependent. For instance, in the following
39 example you can perform two actions from the state 'Ticket Created' --
40 'add comment' and 'edit issue':
41 <state name="Ticket Created">
43 <action name="add comment"
44 resulting_state="NOCHANGE" />
45 <action name="edit issue"
46 resulting_state="Ticket In Progress" />
47 </state>
48 If you execute 'add comment' the new state of the workflow will be the
50 same ('NOCHANGE' is a special state). But if you execute 'edit issue'
51 the new state will be 'Ticket In Progress'.
52 You can also have multiple return states for a single action. The one
54 chosen by the workflow system will depend on what the action returns.
55 For instance we might have something like:
56 <state name="create user">
58 <action name="create">
59 <resulting_state return="admin" state="Assign as Admin" />
60 <resulting_state return="helpdesk" state="Assign as Helpdesk" />
61 <resulting_state return="*" state="Assign as Luser" />
62 </action>
63 </state>
64 So if we execute 'create' the workflow will be in one of three states:
66 'Assign as Admin' if the return value of the 'create' action is
67 'admin', 'Assign as Helpdesk' if the return is 'helpdesk', and 'Assign
68 as Luser' if the return is anything else.
69 Autorun State
71 You can also indicate that the state should be automatically executed
72 when the workflow enters it using the 'autorun' property. Note the
73 slight change in terminology -- typically we talk about executing an
74 action, not a state. But we can use both here because an automatically
75 run state requires that one and only one action is available for
76 running. That doesn't mean a state contains only one action. It just
77 means that only one action is available when the state is entered. For
78 example, you might have two actions with mutually exclusive conditions
79 within the autorun state.
80 If no action or more than one action is available at the time the
82 workflow enters an autorun state, Workflow will throw an error. There
83 are some conditions where this might not be what you want. For example
84 when you have a state which contains an action that depends on some
85 condition. If it is true, you might be happy to move on to the next
86 state, but if it is not, you are fine to come back and try again later
87 if the action is available. This behaviour can be achived by setting
88 the 'may_stop' property to yes, which will cause Workflow to just
89 quietly stop automatic execution if it does not have a single action to
90 execute.
91
93 get_conditions( $action_name )
94 Returns a list of Workflow::Condition objects for action $action_name.
96 Throws exception if object does not contain $action_name at all.
97 get_action( $workflow, $action_name )
99 Returns an Workflow::Action instance initialized using both the global
101 configuration provided to the named action in the "action
102 configuration" provided to the factory as well as any configuration
103 specified as part of the listing of actions in the state of the
104 workflow declaration.
105 contains_action( $action_name )
107 Returns true if this state contains action $action_name, false if not.
109 is_action_available( $workflow, $action_name )
111 Returns true if $action_name is contained within this state and it
113 matches any conditions attached to it, using the data in the context of
114 the $workflow to do the checks.
115 evaluate_action( $workflow, $action_name )
117 Throws exception if action $action_name is either not contained in this
119 state or if it does not pass any of the attached conditions, using the
120 data in the context of $workflow to do the checks.
121 get_all_action_names()
123 Returns list of all action names available in this state.
125 get_available_action_names( $workflow, $group )
127 Returns all actions names that are available given the data in
129 $workflow. Each action name returned will return true from
130 is_action_available(). $group is optional parameter. If it is set,
131 additional check for group membership will be performed.
132 get_next_state( $action_name, [ $action_return ] )
134 Returns the state(s) that will result if action $action_name is
136 executed. If you've specified multiple return states in the
137 configuration then you need to specify the $action_return, otherwise we
138 return a hash with action return values as the keys and the action
139 names as the values.
140 get_autorun_action_name( $workflow )
142 Retrieve the action name to be autorun for this state. If the state
144 does not have the 'autorun' property enabled this throws an exception.
145 It also throws an exception if there are multiple actions available or
146 if there are no actions available.
147 Returns name of action to be used for autorunning the state.
149 clear_condition_cache ( )
151 Deprecated, kept for 1.61 compatibility.
153 Used to empties the condition result cache for a given state.
155
157 All property methods act as a getter and setter. For example:
158 my $state_name = $state->state;
160 $state->state( 'some name' );
161 state
163 Name of this state (required).
165 description
167 Description of this state (optional).
169 autorun
171 Returns true if the state should be automatically run, false if not. To
173 set to true the property value should be 'yes', 'true' or 1.
174 may_stop
176 Returns true if the state may stop automatic execution silently, false
178 if not. To set to true the property value should be 'yes', 'true' or 1.
179
181 init( $config )
182 Assigns 'state', 'description', 'autorun' and 'may_stop' properties
184 from $config. Also assigns configuration for all actions in the state,
185 performing some sanity checks like ensuring every action has a
186 'resulting_state' key.
187
189 • Workflow
190 • Workflow::Condition
192 • Workflow::Factory
194
196 Copyright (c) 2003-2022 Chris Winters. All rights reserved.
197 This library is free software; you can redistribute it and/or modify it
199 under the same terms as Perl itself.
200 Please see the LICENSE
202
204 Please see Workflow
205perl v5.36.0 2023-01-20 Workflow::State(3)