1Workflow::State(3)    User Contributed Perl Documentation   Workflow::State(3)
2
3
4

NAME

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

VERSION

9       This documentation describes version 1.14 of this package
10

SYNOPSIS

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

DESCRIPTION

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
37   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
42         <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
49       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
53       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
57         <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
65       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
70   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
81       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

PUBLIC METHODS

93       get_conditions( $action_name )
94
95       Returns a list of Workflow::Condition objects for action $action_name.
96       Throws exception if object does not contain $action_name at all.
97
98       contains_action( $action_name )
99
100       Returns true if this state contains action $action_name, false if not.
101
102       is_action_available( $workflow, $action_name )
103
104       Returns true if $action_name is contained within this state and it
105       matches any conditions attached to it, using the data in the context of
106       the $workflow to do the checks.
107
108       evaluate_action( $workflow, $action_name )
109
110       Throws exception if action $action_name is either not contained in this
111       state or if it does not pass any of the attached conditions, using the
112       data in the context of $workflow to do the checks.
113
114       get_all_action_names()
115
116       Returns list of all action names available in this state.
117
118       get_available_action_names( $workflow, $group )
119
120       Returns all actions names that are available given the data in
121       $workflow. Each action name returned will return true from
122       is_action_available().  $group is optional parameter. If it is set,
123       additional check for group membership will be performed.
124
125       get_next_state( $action_name, [ $action_return ] )
126
127       Returns the state(s) that will result if action $action_name is
128       executed. If you've specified multiple return states in the
129       configuration then you need to specify the $action_return, otherwise we
130       return a hash with action return values as the keys and the action
131       names as the values.
132
133       get_autorun_action_name( $workflow )
134
135       Retrieve the action name to be autorun for this state. If the state
136       does not have the 'autorun' property enabled this throws an exception.
137       It also throws an exception if there are multiple actions available or
138       if there are no actions available.
139
140       Returns name of action to be used for autorunning the state.
141
142       clear_condition_cache ( )
143
144       Empties the condition result cache for a given state.
145

PROPERTIES

147       All property methods act as a getter and setter. For example:
148
149        my $state_name = $state->state;
150        $state->state( 'some name' );
151
152       state
153
154       Name of this state (required).
155
156       description
157
158       Description of this state (optional).
159
160       autorun
161
162       Returns true if the state should be automatically run, false if not. To
163       set to true the property value should be 'yes', 'true' or 1.
164
165       may_stop
166
167       Returns true if the state may stop automatic execution silently, false
168       if not. To set to true the property value should be 'yes', 'true' or 1.
169

INTERNAL METHODS

171       init( $config )
172
173       Assigns 'state', 'description', 'autorun' and 'may_stop' properties
174       from $config. Also assigns configuration for all actions in the state,
175       performing some sanity checks like ensuring every action has a
176       'resulting_state' key.
177

SEE ALSO

179       Workflow
180
181       Workflow::Condition
182
183       Workflow::Factory
184
186       Copyright (c) 2003-2007 Chris Winters. All rights reserved.
187
188       This library is free software; you can redistribute it and/or modify it
189       under the same terms as Perl itself.
190

AUTHORS

192       Jonas B. Nielsen (jonasbn) <jonasbn@cpan.org> is the current
193       maintainer.
194
195       Chris Winters <chris@cwinters.com>
196
197
198
199perl v5.12.0                      2010-05-07                Workflow::State(3)
Impressum