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