File Coverage

lib/Workflow/History.pm
Criterion Covered Total %
statement 32 32 100.0
branch 7 8 87.5
condition n/a
subroutine 9 9 100.0
pod 5 5 100.0
total 53 54 98.1


line stmt bran cond sub pod time code
1              
2             use warnings;
3 22     22   581 use strict;
  22         42  
  22         837  
4 22     22   115 use base qw( Class::Accessor );
  22         39  
  22         625  
5 22     22   140 use DateTime;
  22         34  
  22         3131  
6 22     22   1746  
  22         39  
  22         6662  
7             $Workflow::History::VERSION = '1.60';
8              
9             my @FIELDS
10             = qw( id workflow_id action description date user state time_zone );
11             __PACKAGE__->mk_accessors(@FIELDS);
12              
13             my ( $class, $params ) = @_;
14             my $self = bless { _saved => 0 }, $class;
15 35     35 1 14012 for (@FIELDS) {
16 35         124 $self->$_( $params->{$_} ) if ( $params->{$_} );
17 35         96 }
18 280 100       2549  
19             my $time_zone
20             = exists $params->{time_zone} ? $params->{time_zone} : 'floating';
21             $self->time_zone($time_zone);
22 35 100       284  
23 35         123 unless ( $self->date ) {
24             $self->date( DateTime->now( time_zone => $self->time_zone() ) );
25 35 100       340 }
26 11         130 return $self;
27             }
28 35         6490  
29             my ( $self, $new_state ) = @_;
30             unless ( $self->state ) {
31             $self->state($new_state);
32 10     10 1 177 }
33 10 50       39 }
34 10         116  
35             my ($self) = @_;
36             return $self->{_saved};
37             }
38              
39 43     43 1 3852 my ($self) = @_;
40 43         162 $self->{_saved} = 1;
41              
42             return 1;
43             }
44 36     36 1 321  
45 36         76 my ($self) = @_;
46             $self->{_saved} = 0;
47 36         76  
48             return 0;
49             }
50              
51 1     1 1 2 1;
52 1         2  
53              
54 1         3 =pod
55              
56             =head1 NAME
57              
58             Workflow::History - Recorded work on a workflow action or workflow itself
59              
60             =head1 VERSION
61              
62             This documentation describes version 1.60 of this package
63              
64             =head1 SYNOPSIS
65              
66             # in your action
67             sub execute {
68             my ( $self, $wf ) = @_;
69             my $current_user = $wf->context->param( 'current_user' );
70             # ... do your work with $ticket
71             $wf->add_history( action => 'create ticket',
72             user => $current_user->full_name,
73             description => "Ticket $ticket->{subject} successfully created" );
74             }
75              
76             # in your view (using TT2)
77             [% FOREACH history = workflow.get_history %]
78             On: [% OI.format_date( history.date, '%Y-%m-%d %H:%M' ) %]<br>
79             Action: [% history.action %] (ID: [% history.id %])<br>
80             by: [% history.user %]<br>
81             [% history.description %]
82             [% END %]
83              
84             =head1 DESCRIPTION
85              
86             Every workflow can record its history. More appropriately, every
87             action the workflow executes can deposit history entries in the
88             workflow to be saved later. Neither the action nor the workflow knows
89             about how the history is saved, just that the history is available.
90              
91             =head1 METHODS
92              
93             =head2 Public Methods
94              
95             =head3 new( \%params )
96              
97             Create a new history object, filling it with properties from
98             C<\%params>.
99              
100             =head3 set_new_state( $new_state )
101              
102             Assigns the new state C<$new_state> to the history if the state is not
103             already assigned. This is used when you generate a history request in
104             a L<Workflow::Action> since the workflow state will change once the
105             action has successfully completed. So in the action you create a
106             history object without the state:
107              
108             $wf->add_history(
109             Workflow::History->new({
110             action => "Cocoa Puffs",
111             description => "They're magically delicious",
112             user => "Count Chocula",
113             })
114             );
115              
116             And then after the new state has been set but before the history
117             objects are stored the workflow sets the new state in all unsaved
118             history objects.
119              
120             =head3 is_saved()
121              
122             Returns true (1) if this history object has been saved, false (0) if not.
123              
124             =head2 Properties
125              
126             =over 4
127              
128             =item *
129              
130             B<id> - ID of history entry
131              
132             =item *
133              
134             B<workflow_id> - ID of workflow to which history is attached
135              
136             =item *
137              
138             B<action> - Brief description of action taken
139              
140             =item *
141              
142             B<description> - Lengthy description of action taken
143              
144             =item *
145              
146             B<date> - Date history noted, set to a L<DateTime> object.
147              
148             =item *
149              
150             B<time_zone> - Time zone to pass to the L<DateTime> object.
151              
152             =item *
153              
154             B<user> - User name (ID, login, or full name, up to you) taking action
155             (may be blank)
156              
157             =item *
158              
159             B<state> - State of workflow as history was recorded.
160              
161             =back
162              
163             =head3 clear_saved
164              
165             Sets saved state to false and returns 0
166              
167             =head3 set_saved
168              
169             Sets saved state to true and returns 1
170              
171             =head1 SEE ALSO
172              
173             =over
174              
175             =item * L<Workflow>
176              
177             =back
178              
179             =head1 COPYRIGHT
180              
181             Copyright (c) 2003-2022 Chris Winters. All rights reserved.
182              
183             This library is free software; you can redistribute it and/or modify
184             it under the same terms as Perl itself.
185              
186             Please see the F<LICENSE>
187              
188             =head1 AUTHORS
189              
190             Please see L<Workflow>
191              
192             =cut