[Rt-commit] r6064 - in RT-Extension-TicketAging: .

[schwern at bestpractical.com]

Author: schwern
Date: Wed Sep 27 18:53:02 2006
New Revision: 6064

Modified:
   RT-Extension-TicketAging/   (props changed)
   RT-Extension-TicketAging/lib/RT/Extension/TicketAging.pm

Log:
 r19376 at Master-Windhund-IV:  schwern | 2006-09-27 15:52:18 -0700
 Basic documention of the default ticket aging process and configuration.
 Left in some stubs I don't yet understand.
 
 Typos in the code, "Codition" instead of "Condition"
 
 Eliminated use of $_


Modified: RT-Extension-TicketAging/lib/RT/Extension/TicketAging.pm
==============================================================================
--- RT-Extension-TicketAging/lib/RT/Extension/TicketAging.pm	(original)
+++ RT-Extension-TicketAging/lib/RT/Extension/TicketAging.pm	Wed Sep 27 18:53:02 2006
@@ -2,6 +2,131 @@
 
 our $VERSION = '0.04';
 
+
+=head1 NAME
+
+RT::Extension::TicketAging
+
+=head1 DESCRIPTION
+
+This extension allows closed tickets to be made inaccessable and
+finally completely deleted as they get older.
+
+=head2 Age
+
+To determine the age of a ticket the "LastUpdated" property is used.
+
+=head3 Default life cycle
+
+The default life cycle is:
+
+=over 4
+
+=item Active
+
+Any unresolved ticket or a ticket with unresolved children is
+considered I<Active>.
+
+=item Finished
+
+When a ticket and all its children have been resolved it becomes
+I<Finished>.  No further activity is expected on this ticket.
+
+There is otherwise nothing special about a I<Finished> ticket.
+
+=item Dead
+
+When a ticket and all its children have been I<Finished> for a set
+period (default 2 months) then it becomes I<Dead>.  Dead tickets are
+just like Finished tickets except they do not show up in RTIR's
+special lookup tools.
+
+=item Extinct
+
+After being I<Dead> for a while (default 12 months) a ticket becomes
+I<Extinct>.  Extinct tickets have their status set to I<deleted>.
+They won't show up in any searches unless explicitly asked for
+(C<'CF.{Age} = "Extinct"'>).
+
+=item Destroyed
+
+After being I<Extinct> for a while (default 24 months) and if all
+linked tickets are also I<Extinct> a ticket is I<Destroyed>.
+Destroyed tickets are no longer available in RT.  They are wholely
+removed from RT using the Shredder.  Destroyed tickets are saved in a
+SQL dump file with a template of F<sqldump-I<timestamp>-I<XXXX>.sql>.
+
+See L<RT::Shredder> for more information.
+
+=back
+
+=head3 Aging configuration
+
+Administrators may define their own aging behaviors.
+
+The ages available to RT are configured by changing the available
+values for the C<Age> global custom field.  An administrator may
+remove values to disable pre-configured options.  Adding new values
+activates new age commands but if its not one of the above values you
+have to configure the conditions and actions for each age.
+
+=head3 C<$TicketAgingMap>
+
+C<$TicketAgingMap> can be set in your configuration to override or add
+to the default aging map.  Its easiest to illustrate this with code.
+
+    Set( $TicketAgingMap, {
+             AgeName => {
+                 Condition => {
+                     CallbackPre  => sub { ... },
+                     SQL          => sub { ... },
+                     CallbackPost => sub { ... },
+                     Filter       => sub { ... },
+                 },
+                 Action => sub { ... }
+             }
+         });
+
+=over 4
+
+=item AgeName
+
+The name of your Age field.  For example, "Active".
+
+=item Condition
+
+Holds the rules for determining what tickets fall into this age.
+
+=over 8
+
+=item SQL
+
+This is the TicketSQL to be run to get the tickets of this Age.
+Generally its a check against LastUpdated and perhaps Status.
+
+    SQL => sub { "LastUpdated < '-2 months'" }
+
+
+=item CallbackPre
+
+=item CallbackPost
+
+=item Filter
+
+=back
+
+=item Action
+
+=back
+
+
+=head3 C<$TicketAgingFilenameTemplate>
+
+=head3 rt-aging
+
+=cut
+
+
 sub loc(@) { return $RT::SystemUser->loc(@_) }
 
 my @ages = ();
@@ -112,15 +237,15 @@
             next;
         }
         if ( my $cond = $src->{ $age }{'Condition'} and ref $cond eq 'HASH' ) {
-            foreach my $field( qw(CallbackPre SQL CallbackPost Filter) ) {
+            foreach my $field ( qw(CallbackPre SQL CallbackPost Filter) ) {
                 next unless defined $cond->{ $field };
                 unless ( $cond->{$field} ) {
                     $RT::Logger->info( "$age -> Condition -> $field is disabled due to TicketAgingMap" );
-                    delete $dst->{ $age }{'Codition'}{ $field };
+                    delete $dst->{ $age }{'Condition'}{ $field };
                     next;
                 }
                 if ( ref $cond->{$field} eq 'CODE' || ( $field eq 'SQL' && !ref $cond->{$field} )) {
-                    $dst->{ $age }{'Codition'}{ $field } = $cond->{$field};
+                    $dst->{ $age }{'Condition'}{ $field } = $cond->{$field};
                     next;
                 }
                 $RT::Logger->info( "TicketAgingMap -> $age -> Condition -> $field has incorrect type" );
@@ -132,7 +257,7 @@
         if ( defined $src->{ $age }{'Action'} ) {
             unless ( $src->{ $age }{'Action'} ) {
                 $RT::Logger->info( "$age -> Action is disabled due to TicketAgingMap" );
-                delete $dst->{ $age }{'Codition'}{ $field };
+                delete $dst->{ $age }{'Condition'}{ $field };
             }
             elsif ( ref $src->{ $age }{'Action'} eq 'CODE' ) {
                 $dst->{ $age }{'Action'} = $src->{ $age }{'Action'};
@@ -163,8 +288,8 @@
         delete $condition->{'SQL'};
     }
 
-    foreach ( qw(CallbackPre Filter CallbackPost) ) {
-        next unless my $code_ref = $condition->{$_};
+    foreach my $callback ( qw(CallbackPre Filter CallbackPost) ) {
+        next unless my $code_ref = $condition->{$callback};
         unless ( ref $code_ref eq 'CODE' ) {
             return 0, loc "Filter(age [_1]) '[_2]' is not code reference", $age, $filter;
         }