Workflow::Action(3pm)

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

NAME

6       Workflow::Action - Base class for Workflow actions
7

VERSION

9       This documentation describes version 1.62 of this package
10

SYNOPSIS

12        # Configure the Action...
13        <action name="CreateUser"
14                class="MyApp::Action::CreateUser">
15          <field name="username" is_required="yes"/>
16          <field name="email" is_required="yes"/>
17          <validator name="IsUniqueUser">
18              <arg>$username</arg>
19          </validator>
20          <validator name="IsValidEmail">
21              <arg>$email</arg>
22          </validator>
23        </action>
24
25        # Define the action
26
27        package MyApp::Action::CreateUser;
28
29        use base qw( Workflow::Action );
30        use Workflow::Exception qw( workflow_error );
31
32        sub execute {
33            my ( $self, $wf ) = @_;
34            my $context = $wf->context;
35
36            # Since 'username' and 'email' have already been validated we
37            # don't need to check them for uniqueness, well-formedness, etc.
38
39            my $user = eval {
40                User->create({ username => $context->param( 'username' ),
41                               email    => $context->param( 'email' ) })
42            };
43
44            # Wrap all errors returned...
45
46            if ( $@ ) {
47                workflow_error
48                    "Cannot create new user with name '", $context->param( 'username' ), "': $EVAL_ERROR";
49            }
50
51            # Set the created user in the context for the application and/or
52            # other actions (observers) to use
53
54            $context->param( user => $user );
55
56            # return the username since it might be used elsewhere...
57            return $user->username;
58        }
59

DESCRIPTION

61       This is the base class for all Workflow Actions. You do not have to use
62       it as such but it is strongly recommended.
63

CONFIGURATION

65       You configure your actions and map them to a specific module in your
66       actions configuration file using the syntax above and that shown in
67       Workflow. In some cases, you'll have actions that apply to all
68       workflows. In more elaborate configurations, you may have one workflow
69       server loading multiple workflows and multiple actions for each.  In
70       these cases, you'll have multiple workflow types and you may want
71       actions with the same names to have different behaviors for each type.
72
73       For example, you may have a workflow type Ticket and another type
74       Order_Parts.  They both may have a Submit action, but you'll want the
75       Submit to be different for each.
76
77       You can specify a type in your actions configuration to associate that
78       action with that workflow type. If you don't provide a type, the action
79       is available to all types. For example:
80
81         <actions>
82           <type>Ticket</type>
83           <description>Actions for the Ticket workflow only.</description>
84           <action name="TIX_NEW"
85                  class="TestApp::Action::TicketCreate">
86         ...Addtional configuration...
87
88       The type must match an existing workflow type or the action will never
89       be called.
90

STANDARD ATTRIBUTES

92       Each action supports the following attributes:
93
94       •   "class"
95
96           The Perl class which provides the behaviour of the action.
97
98       •   "description"
99
100           A free text field describing the action.
101
102       •   "group"
103
104           The group for use with the "get_available_action_names" in
105           Workflow::State $group filter.
106
107       •   "name"
108
109           The name by which workflows can reference the action.
110
111       •   "type"
112
113           Associates the action with workflows of the same type, when set.
114           When not set, the action is available to all workflows.
115
116       These attributes (except for the "class" attribute) all map to instance
117       properties by the same name.
118

ADDITIONAL ATTRIBUTES

120       You can validate additional attributes in of your action by doing two
121       things:
122
123       •   Set $Workflow::Factory::VALIDATE_ACTION_CONFIG to 1.
124
125       •   Provide function validate_config() in your action class.
126
127       Then, this function will be called with all the acton attributes when
128       it is parsed.  For example, if your action XML looks like this:
129
130         <action name="BEGIN" class="My::Class" when="NOW">
131
132       You can validate it like this:
133
134         sub My::Class::validate_config {
135           my $config = shift;
136           unless ('NOW' eq $config->{when}) {
137             configuration_error "`$$config{when}' is not a valid value " .
138                                 "for `when'";
139           }
140         }
141

OBJECT METHODS

143   Public Methods
144       new()
145
146       Subclasses may override this method, but it's not very common. It is
147       called when you invoke a method in your Workflow object that returns an
148       Action object, for example, methods such as $wf->get_action will call
149       this method.
150
151       Your action classes usually subclass directly from Workflow::Action and
152       they don't need to override this method at all. However, under some
153       circumstances, you may find the need to extend your action classes.
154
155       init()
156
157       Suppose you want to define some extra properties to actions but you
158       also want for some of these properties to depend on a particular state.
159       For example, the action "icon" will almost allways be the same, but the
160       action "index" will depend on state, so you can display your actions in
161       a certain order according to that particular state. Here is an example
162       on how you easily do this by overriding new():
163
164       1) Set the less changing properties in your action definition:
165
166         <actions>
167           <type>foo</type>
168           <action name="Browse"
169             type="menu_button" icon="list_icon"
170             class="actual::action::class">
171           </action>
172
173       2) Set the state dependant properties in the state definition:
174
175        <state name="INITIAL">
176          <description>
177            Manage Manufaturers
178          </description>
179          <action index="0" name="Browse" resulting_state="BROWSE">
180            <condition name="roleis_oem_mgmt"/>
181          </action>
182          <action index="1" name="Create" resulting_state="CREATE">
183            <condition name="roleis_oem_mgmt"/>
184          </action>
185          <action index="2" name="Back" resulting_state="CLOSED"/>
186        </state>
187
188       3) Craft a custom action base class
189
190         package your::action::base::class;
191
192         use warnings;
193         use strict;
194
195         use base qw( Workflow::Action );
196         use Workflow::Exception qw( workflow_error );
197
198         # extra action class properties
199         my @EXTRA_PROPS = qw( index icon type data );
200         __PACKAGE__->mk_accessors(@EXTRA_PROPS);
201
202         sub init {
203           my ($self, $wf, $params) = @_;
204           $self->SUPER::init($wf, $params);
205           # set only our extra properties from action class def
206           foreach my $prop (@EXTRA_PROPS) {
207             next if ( $self->$prop );
208             $self->$prop( $params->{$prop} );
209           }
210           # override specific extra action properties according to state
211           my $wf_state = $wf->_get_workflow_state;
212           my $action = $wf_state->{_actions}->{$self->name};
213           $self->index($action->{index});
214         }
215
216
217         1;
218
219       4) Use your custom action base class instead of the default
220
221         package actual::action::class;
222
223         use warnings;
224         use strict;
225
226         use base qw( your::base::action::class );
227         use Workflow::Exception qw( workflow_error );
228
229         sub execute {
230           ...
231         }
232
233         1;
234
235       required_fields()
236
237       Return a list of Workflow::Action::InputField objects that are
238       required.
239
240       optional_fields()
241
242       Return a list of Workflow::Action::InputField objects that are
243       optional.
244
245       fields()
246
247       Return a list of all Workflow::Action::InputField objects associated
248       with this action.
249
250   Private Methods
251       init( $workflow, \%params )
252
253       init is called in conjuction with the overall workflow initialization.
254
255       It sets up the necessary validators based on the on configured actions,
256       input fields and required fields.
257
258       add_field( @fields )
259
260       Add one or more Workflow::Action::InputFields to the action.
261
262       add_validators( @validator_config )
263
264       Given the 'validator' configuration declarations in the action
265       configuration, ask the Workflow::Factory for the Workflow::Validator
266       object associated with each name and store that along with the
267       arguments to be used, runtime and otherwise.
268
269       get_validators()
270
271       Get a list of all the validator hashrefs, each with two keys:
272       'validator' and 'args'. The 'validator' key contains the appropriate
273       Workflow::Validator object, while 'args' contains an arrayref of
274       arguments to pass to the validator, some of which may need to be
275       evaluated at runtime.
276
277       validate( $workflow )
278
279       Run through all validators for this action. If any fail they will throw
280       a Workflow::Exception, the validation subclass.
281
282       execute( $workflow )
283
284       Subclasses must implement -- this will perform the actual work. It's
285       not required that you return anything, but if the action may be used in
286       a Workflow::State object that has multiple resulting states you should
287       return a simple scalar for a return value.
288
289       add_fields
290
291       Method to add fields to the workflow. The method takes an array of
292       fields.
293

COPYRIGHT

300       Copyright (c) 2003-2023 Chris Winters. All rights reserved.
301
302       This library is free software; you can redistribute it and/or modify it
303       under the same terms as Perl itself.
304
305       Please see the LICENSE
306

AUTHORS

308       Please see Workflow
309
310
311
312perl v5.38.0                      2023-07-21               Workflow::Action(3)