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