[Rt-commit] r6038 - RT-Extension-TicketAging
jesse at bestpractical.com
jesse at bestpractical.com
Tue Sep 26 13:56:32 EDT 2006
Author: jesse
Date: Tue Sep 26 13:56:30 2006
New Revision: 6038
Modified:
RT-Extension-TicketAging/ (props changed)
RT-Extension-TicketAging/SPECIFICATION
Log:
r27838 at 114: jesse | 2006-09-26 13:56:07 -0400
Spec / doc cleanup
Modified: RT-Extension-TicketAging/SPECIFICATION
==============================================================================
--- RT-Extension-TicketAging/SPECIFICATION (original)
+++ RT-Extension-TicketAging/SPECIFICATION Tue Sep 26 13:56:30 2006
@@ -1,13 +1,15 @@
-= Specification of RT-Extension-TicketAging
+=head1 OVERVIEW
+
+Name: Specification of RT-Extension-TicketAging
Version: 0.4
Author: Ruslan U. Zakirov <ruz at bestpractical.com>
-== INTRODUCTION
+=head1 INTRODUCTION
-RTIR MUST support a scheme for incident aging in which closed
+This tool provides a scheme for ticket/incident aging in which closed
incidents and associated tickets are made inaccessible through
the normal interface and are eventually removed from the database.
@@ -21,112 +23,124 @@
• Extinct (out of band access only, 6 month timeout)
• Destroyed (out of band procedure for destroying backups)
-== IMPLEMENTATION
+=head1 IMPLEMENTATION
-As RTIR is extension over RT core and aging make sense for
-none RTIR tickets too, so it was decided to make extension
-for RT that also would be compatible with RTIR.
+Based on early requests from the RTIR working group that all possible
+RTIR functionality which could separated from RTIR be made available
+to teams using RT, this extension was designed to work with both
+RT and RTIR.
-This extension is named RT-Extension-TicketAging.
+This extension is named B<RT-Extension-TicketAging>.
-When you install extension it sets up new global custom
-field 'Age' of 'select single' type with several predefined
+When you install the extension it sets up new global custom
+field 'Age' of type 'select single' with several predefined
values:
-• Active
-• Finished
-• Dead
-• Extinct
-• Destroyed
-Extension comes with scrip 'rt-aging' which could be ran from
-command line or by cron.
+=over
+
+=item Active
+
+=item Finished
+
+=item Dead
+
+=item Extinct
+
+=item Destroyed
+
+=back
+
+The extension comes with a script named C<rt-aging> which you can run
+either from the unix commandline or from cron as an RT administrator
+(By default C<root> is an RT administrator.)
Each age has several properties: search condition, filter and
action.
-Search condition is used to find ticket candidates for age
-changing. Filter is a function that could be used to filter
-collection by conditions that couldn't be impressed as search
-query. To the tickets left in collection custom action applied
-if it's defined, otherwise only age is changed.
+The search condition is used to find candidate tickets for aging
+The filter is a function that ccan be used to filter
+collection by conditions that can't be represented as search
+queries. If the custom action is defined, it's applied to the tickets
+left over after filtering before their C<Age> custom field is changed.
-=== NOTES
-* age is changed without transaction writing in order to avoid
- changing properties of the ticket.
+=head3 NOTES
-== DEFAULT SETUP
+B<The C<Age> custom filed is changed without writing an RT transaction in
+order avoid unnecessarily altering the tickets's properties.>
-=== Finished
+=head2 DEFAULT SETUP
+
+=head3 Finished
A ticket is finished when it and its children have been resolved.
No special action applied to the tickets.
-== Dead
+=head2 Dead
When a ticket and its children are finished for a set period
-of time(by default 2 months) then it is Dead. LastUpdated property
-of tickets is used to determine starting date of the period. Tickets
-of the dead age are available for generic search operations,
-except special requirement to hide these tickets from "whois"
-tool in the RTIR extension.
-
-== Extinct
-
-After a set period of time of being dead(by default 12 month since last
-update of ticket ) a ticket is extinct. Extinct tickets wont, by default
-show up in any searches. Unless the search has an explicit 'include extinct
-tickets' criterion is added to the search.
+of time (by default 2 months) then it is Dead. A ticket's C<LastUpdated>
+property is used to determine starting date of the period. Tickets
+of the I<dead> age are available for generic search operations,
+with the exception of a special requirement to hide these tickets from
+the "whois" tool in the RTIR extension.
+
+=head2 Extinct
+
+After a set period of time of being dead (by default 12 month since last
+update of the ticket) a ticket is extinct. Extinct tickets won't, by default
+show up in any searches, unless the search has an explicit 'include extinct
+tickets' criterion is added to the search:
* RT filters tickets with 'deleted' status from search results,
- so to hide tickets from searches we could use this status when age
+ so to hide tickets from searches we use this status when age
of a ticket is 'Extinct'. In order to allow user to find these
- tickets we can unhide them when search condition
+ tickets we explcitly unhide them when search condition
has 'CF.{Age} = "Extinct"'.
-== Destroyed
+=head2 Destroyed
-After a set period of time of being extinct(by default 24 month since last
+After a set period of time of being extinct (by default 24 month since last
update of ticket) a ticket is destroyed, but only if all linked tickets are
-of extinct age too. Destroyed tickets are deleted from the RT DB and saved
-as backups on a disk in files. Destroyed tickets are not available anymore
-throught any RT interfaces.
+also I<extinct> . Destroyed tickets are deleted from the RT the DB and saved
+as backups on a disk in files as specified below. Destroyed tickets are no
+longer available through any RT interfaces.
-Backup files can be used to restore information into data base.
-Location of the files as file name template are configurable from config. Files
-can be moved or deleted. Destroyed tickets are no more available from
-web or command line interface.
+Backup files can be used to restore information into the database. (See below)
-Also, script could be executed with '--prune-backups <days>' switch to cleanup
-files which are old.
+The c<rt-age> script can be executed with the '--prune-backups I<days>' switch to cleanup
+files which are older than I<days> days.
-== Format of the backup files
+=head2 Format of the backup files
-Default file name template is "sqldump-<timestamp>-<XXXX>.sql".
+The default file name template is "sqldump-I<timestamp>-I<XXXX>.sql".
-Each file contain SQL commands that insert or update prviously deleted/changed
-records back into RT DB. For example with MySQL you can run next command to
+Each file contain a full set of SQL commands to insert
+records back into RT DB. If you're using MySQL, the following command
+will restore the data contained in C<sqldump-20050316T134556-0000.sql>
+into an RT database called C<rt3db>
restore backup:
$> mysql -u root -p rt3db < sqldump-20050316T134556-0000.sql
-= CONFIGURATION
+=head1 CONFIGURATION
-== List of ages
+=head2 List of ages
-List of available ages are configured via list of values of
-the 'Age' custom field. System administrator may delete
-values to disable fields. Adding new values activates new
-age, but if name is not default you have to configure
-conditions and actions for the age.
+The list of available ticket "ages" is configured by changing the
+available values for the C<Age> custom field. A system administrator
+may delete values to disable pre-configured options. Adding new
+values activates new age commands, but if a new value isn't one of
+the ones shipped with the tool, you have to configure
+conditions and actions for the age. (See below)
-== Ages map
+=head2 Ages map
-User may define 'TicketAgingMap' config option to override
-default options. This option is hash with age values as keys
-and hash references as values with configuration.
+Administrators may define a C<TicketAgingMap> config option to override
+or supplement default options. This option is a hash with C<age> custom field
+values as keys and configuration hash references as values.
-Next options are available:
+The following options are available:
AgeName => {
Condition => {
@@ -141,42 +155,50 @@
...
}
-=== SQL
+=head3 SQL
-Tickets' SQL query you can setup to choose tickets for age switching.
+An RT C<TicketSQL> query you can set up to specify which tickets should have
+their ages switched.
For example:
- SQL => "LastUpdated < '-2 months'"
- SQL => "Status = 'resolved'"
-You may also provide code reference, function should return SQL string.
-Function called with one named parametr 'Age'.
+ SQL => "LastUpdated < '-2 months'"
+
+ SQL => "Status = 'resolved'"
+
+You may also provide code reference which returns a C<TicketSQL> string.
+The code reference will be called as a function with a single named parameter,
+C<Age>.
-=== CallbackPre and CallbackPost
+=head3 CallbackPre and CallbackPost
-Two code references that could be used to set up properties of the collection
+These two code references can be used to set up properties of the collection
object. CallbackPre is called before any action is applied to collection
-(even before it's limit by search condition) and CallbackPost is called
-just before actual walking throught collection.
+(even before it is limited by search conditions) and CallbackPost is called
+just before the system iterates through the collection.
-Functions are called with two named arguments: Age and Collection. Callbacks
-must return true on success or (undef, $error_message) otherwise.
+These functions are called with two named arguments: C<Age> and C<Collection>. Both
+callbacks must return true on success or a tuple of C<(undef, $error_message)> otherwise.
-=== Filter
+=head3 Filter
-Code reference can be used to filter tickets in collection.
-Takes Age, Collection and Object as named arguments and must
-return false if ticket should be skipped or true value otherwise.
+This code reference can be used to filter tickets in the collection.
+It takes C<Age>, C<Collection> and C<Object> as named arguments and must
+return false if the ticket C<Object> should be skipped or true if it should
+be included.
-=== Action
+=head3 Action
-Code reference that can be used to change ticket and it's properties
-just before setting new age value.
+This code reference can be used to change a ticket and its properties
+just before changing its age to a new value..
-== Other config options
+=head2 Other config options
-=== TicketAgingFilenameTemplate
+=head3 TicketAgingFilenameTemplate
-Use it to setup template of file names used for backups while
-tickets deletion.
+This scalar value should be an alternate template for ticket aging files.
+The string C<XXXX> in your template will be replaced with an integer serial
+number for each backup. If the template is a relative path, it will be treated
+as relative to the RT::Shredder storage path.
+=cut
More information about the Rt-commit
mailing list