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

[schwern at bestpractical.com]

Author: schwern
Date: Wed Sep 27 20:11:53 2006
New Revision: 6065

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

Log:
 r19379 at Master-Windhund-IV:  schwern | 2006-09-27 17:10:34 -0700
 Fill in the rest of the docs.


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 20:11:53 2006
@@ -10,13 +10,18 @@
 =head1 DESCRIPTION
 
 This extension allows closed tickets to be made inaccessable and
-finally completely deleted as they get older.
+finally completely deleted as they get older.  It adds a new global
+ticket field, "Age", to track a ticket's movement through the life
+cycle.
 
-=head2 Age
+The rt-aging program (see below) is used to move tickets through the
+life cycle and must be run separately.
 
-To determine the age of a ticket the "LastUpdated" property is used.
+When we speak of "age" we are referring to a ticket's "LastUpdated"
+property.
 
-=head3 Default life cycle
+
+=head2 Default life cycle
 
 The default life cycle is:
 
@@ -54,13 +59,24 @@
 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>.
+SQL dump file from which they can be restored.
 
 See L<RT::Shredder> for more information.
 
 =back
 
-=head3 Aging configuration
+
+=head2 rt-aging
+
+The real work is done by the rt-aging program installed to your RT
+local sbin.  In general you simply run rt-aging from the command line
+or periodically from cron as an RT administrator.  It will apply the
+aging rules and alter the tickets as necessary.
+
+See L<rt-aging> for more details.
+
+
+=head2 Aging configuration
 
 Administrators may define their own aging behaviors.
 
@@ -70,10 +86,10 @@
 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>
+=head2 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.
+to the default life cycle.  Its easiest to illustrate this with code.
 
     Set( $TicketAgingMap, {
              AgeName => {
@@ -87,6 +103,31 @@
              }
          });
 
+=head3 Arguments
+
+The aging conditions and actions generally have these arguments.
+
+=over 4
+
+=item Age
+
+This is the name of the age being processed.  For example "Active".
+
+=item Collection
+
+This is an RT::Tickets object representing all the tickets visible to
+the C<$RT::SystemUser>.  It can be filtered by the Callbacks and the
+SQL.
+
+=item Object
+
+An individual RT::Ticket from the ticket C<Collection>.
+
+=back
+
+
+=head3 Fields
+
 =over 4
 
 =item AgeName
@@ -95,7 +136,16 @@
 
 =item Condition
 
-Holds the rules for determining what tickets fall into this age.
+Holds the rules for determining what tickets fall into this age.  The
+rules are run in this order (excuse the pseudo-code):
+
+    CallbackPre
+    SQL
+    CallbackPost
+    foreach $Object ($Collection) {
+        Filter
+        Action
+    }
 
 =over 8
 
@@ -106,23 +156,90 @@
 
     SQL => sub { "LastUpdated < '-2 months'" }
 
+The TicketSQL is run against the Collection.
+
 
 =item CallbackPre
 
 =item CallbackPost
 
+These callbacks can be used to alter the Collection before the SQL is
+run or before the Filter.
+
+Called with C<Age> and C<Collection> arguments.
+
+Must return true on success or a tuple of C<(false, $error_message)>
+on failure.
+
+For example:
+
+    # Search for deleted tickets
+    CallbackPre => sub {
+        my %args = @_;
+        return $args{Collection}{allow_deleted_search} = 1;
+    };
+
+
 =item Filter
 
+Each ticket found by the SQL condition in the C<Collection> is
+iterated over and the C<Filter> is called on each one.  This gives an
+opportunity to cull out individual tickets.
+
+Called with C<Age>, C<Collection> and C<Object> arguments.  C<Object>
+is an individual RT::Ticket from the ticket C<Collection>.
+
+Returns true if the ticket should be included in the age, false if it
+should be ignored.
+
+    # Filter out tickets whose children are not of the same age.
+    Filter => sub {
+        my %args = @_;
+        my $id = $args{Object}->id;
+
+        my $find_different_children = qq{
+              (CF.{Age} IS NULL OR CF.{Age} != $args{Age})
+              AND Linked = $id
+        };
+
+        my $tickets = RT::Tickets->new( $RT::SystemUser );
+        $tickets->{allow_deleted_search} = 1;
+        $tickets->FromSQL( $find_different_children );
+        return !$tickets->Count;
+    }
+
 =back
 
 =item Action
 
+After filtering, each ticket found in the C<Collection> is iterated
+over and the C<Action> is called on each one.  This is where whatever
+changes that need to be made to individual tickets when they change
+age should be done.
+
+Called with C<Age>, C<Collection> and C<Object> arguments.
+
+Like the Callbacks, it returns true on success or a tuple of C<(false,
+$error_message)> on failure.
+
+    # Mark the ticket as deleted.
+    Action => sub {
+        my %args = @_;
+        my $ticket = $args{Object};
+
+        return $ticket->__Set( Field => "Status", Value => "deleted" );
+    }
+
 =back
 
 
-=head3 C<$TicketAgingFilenameTemplate>
+=head2 C<$TicketAgingFilenameTemplate>
+
+This is the filename template used to create the Shredder dump file
+when tickets are Destroyed.  Defaults to the RT::Shredder default.
 
-=head3 rt-aging
+See the documentation for C<<RT::Shredder->GetFileName>> for more
+details.
 
 =cut