----------------------------------------------------------------------------
Request Tracker Achievements - installation instructions
----------------------------------------------------------------------------

NB: Only tested on RT 3.6.6

These files implement "achievements" in RT. Extract them so that they end up
in your local RT updates area, e.g. /usr/local/rt3/html.

You will also need to create a scrip with the following settings (as the
admin user, go to Configuration -> Global -> Scrips and create new):

  Description: Achievements
    Condition: On Transaction
       Action: User Defined
     Template: Global template: Blank
        Stage: TransactionCreate

  Custom condition:
  return 1 if ($session{'CurrentUser'} && $session{'CurrentUser'}->Privileged);
  return 0;

  Custom action preparation code:
  return 1;

  Custom action cleanup code:
  (see "Achievements-scrip.txt")

Cut and paste the contents of "Achievements-scrip.txt" into the action
cleanup code.

Once the above has been done, you will need to create the achievements
tables in the same database that RT lives in. The tables are defined in
"Achievements-tables.mysql".

Finally, you'll need to edit the achievements definition table. You can go
back and add more achievements whenever you want. As the admin user, go to
Configuration -> Achievements in RT.

Add new achievements in the top row. Edit ones you've already added in their
own boxes. Click on "Store Changes" to save changes.

Fields are:

        Order: The sort order for displaying (numeric). Lowest first.
         Name: The name of the achievement.
  Description: A short description of the achievement.
       Target: Number of triggers before the achievement is earned.
        Clear: When to clear progress towards the target.
         Icon: A 64x64 pixel PNG.
    Perl code: Perl snippet to determine whether to trigger.

The Perl snippet should result in true (1) or false (0 or undef); if it is
true, the achievement is triggered and progress is made. If the progress
counter reaches the target the achievement is earned.

Perl variables you can use:

         $Type: The transaction type.
      $Subject: The ticket subject.
     $OldValue: The old value of the field being changed.
     $NewValue: The new value of the field being changed.
       $UserId: The current user's ID.
  $AllComments: All comments in the ticket, as a string (*).
      $AllText: All text in the ticket, as a string (*).
         $self: The scrip transaction object.

(*) This is blank unless the $Type is 'Status' and $NewValue is 'resolved',
    i.e. the ticket is being resolved. This avoids having to scan all
    transactions in a ticket for every type of update.

A working knowlege of RT internals would be useful when creating new
achievements.

Some sample achievement definitions:

  Name: Service Oriented
  Description: 10 resolutions in a day
  Target: 10
  Clear: Daily
  Code: $Type eq 'Status' && $NewValue eq 'resolved'

  Name: Service Provider
  Description: 20 resolutions in a day
  Target: 20
  Clear: Daily
  Code: $Type eq 'Status' && $NewValue eq 'resolved'

  Name: Service Mad
  Description: 100 resolutions in a day
  Target: 100
  Clear: Daily
  Code: $Type eq 'Status' && $NewValue eq 'resolved'

  Name: Backup Executive
  Description: Changed 100 backup tapes
  Target: 100
  Clear: Never
  Code: $Type eq 'Status' && $NewValue eq 'resolved' && $Subject =~ /Change Backup Tapes/

  Name: Night Owl
  Description: 10 tickets resolved outside 8am-7pm
  Target: 10
  Clear: Never
  Code: my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime(time); $Type eq 'Status' && $NewValue eq 'resolved' && ($hour < 8 || $hour > 18)

  Name: Thief
  Description: 10 tickets stolen in a day
  Target: 10
  Clear: Daily
  Code: $Type eq 'Steal'

  Name: Do the needful
  Description: Please do the needful
  Target: 1
  Clear: Never
  Code: $Type eq 'Status' && $NewValue eq 'resolved' && $AllText =~ /\bdo\s+the\s+needful\b/is

You get the idea.

*** NOTE: This is OPT IN. Each user must go to Preferences -> Achievements
***       and enable them.

Home page:
http://www.ivarch.com/programs/rt-achievements.shtml

Inspired by:
http://forums.somethingawful.com/showthread.php?threadid=3355600

Go here for some icons:
http://teamfortress2.fr/achievements.php

----------------------------------------------------------------------------
