Extension:RT

Purpose
The RT extension allows you to display information from your RT (RequestTracker) database on your wiki by using    tags. It was written by Greg Sabino Mullane at End Point Corporation (which uses it internally). Both individual tickets and lists of tickets can be generated.

Download
Download the latest tarball. Untar it to your extensions directory.

tar xvfz MediaWiki.RT.extension.tar.gz

Install balloons
The RT extension uses the excellent Balloons extension by default. While balloons can be turned off, installing the Balloons extension is highly recommended.

Update LocalSettings.php
Add the following three lines to your LocalSettings.php:

Change the URL in the first variable to your RT site, and change the connection parameters in the second variable so you can connect to RT database. There are more variables available (see below), but the above two are the only required ones to make the extension work.

Basic usage
This extension adds a new    tag. To make a link to a specific ticket, enter the ticket number like so: 1234 This will create a link to the ticket, with the text "RT #1234". Hovering over the link will provide a balloon showing detailed information about the ticket. If the ticket does not exist, the bare text "RT #1234" will be shown.

A list of tickets can be shown as well, by leaving the area between the tags blank, and using arguments to control what is shown. A quick example:  This will produce a table of all new and open sales tickets, sorted by last updated, showing a link to each ticket, its subject, owner, and last updated time. There are many options to control what is shown in the table. Some more advanced examples:  This will show the 20 newest tickets owned by Greg and in the MediaWiki or Postgres queue, and add in a column showing the age of the ticket, but hide the "Status" column.

Warnings
This extension will query the RT database every time a page is viewed (or previewed in edit mode). This can drive a lot of traffic to your RT database, so keep that in mind. View the section for help with this. Ideally someone would implement some kind of caching mechanism for the extension at this point.

Enabling this extension allows full access to your RT database for anyone who can edit wiki pages, so do not grant edit permissions to anyone who you don't want to have access to your RT information.

Switching it off
There are times when you want to turn this extension off, such as if the connection to your RT database has been lost. Rather than uninstalling the extension and leaving a bunch of ugly raw  tags lying around, you can simply add this line to your LocalSettings.php file: $wgRequestTracker_Active = 0; If this is set to false, then the database will not be queried, and rt tags will simply show a plain message such as "RT #1234". Any tables will show a short message (set by the 'rt-inactive' system variable)

Showing individual tickets
If a number is enclosed by    tags, a link to that ticket in RT will be created.

1234

The default text shown is RT #1234. If the ticket does not exist, the tag will not print the link.

The rt tag takes several arguments, which will control what information of a ticket is shown in the resulting template output.

1234

You can specify one to multiple of the following arguments. Specify them in the order they should appear:


 * subject
 * status
 * priority
 * queue
 * username
 * owner
 * creator
 * age
 * lastupdated
 * created
 * resolved

You can also add any 'format' names defined by $wgRequestTracker_Formats. This is usually a better option, as it allows more flexibility in what to display. It also allows you to standardize formats across your wiki.

The balloon tips can be turned off by adding a noballoon argument.

Examples:

3412 3412</rt> 3412</rt>

Showing lists of tickets
If no number is given between the    tags, a list of tickets is generated and put into a HTML table. By default, all 'open' and 'new' tickets are shown, ordered by the 'last updated' field in descending order.

List arguments
Arguments added to the opening rt tag control what is show in the table. The following arguments are available:

l: limit
Limits the number of results returned to a certain number. Handy for making "top 10" lists.

q: queue
A list of one or more queues which should be shown. The queue names are case-insensitive. Multiple queue names should be comma separated. If only a single q name is given, the Queue column will not be shown by default (use a queue argument to override this behavior).

s: status
Controls which tickets to show based in their status. The default value is 'open,new'. The statuses are case-insensitive, and multiple statuses should be comma-separated. If the s argument contains a single name, the Status column will not be shown (use a status argument to override this).

o: owner
Only show tickets belonging to the owners listed. The names are case-insensitive, and multiple names should be comma separated. If only a single o name is given, the Owner column will not be shown by default (use a owner argument to override this behavior).

ob: order by
This option controls the sorting of the list. Any valid column name can be used. Multiple entries should be separated by commas. The sort order is ascending by default. To make a column sort in descending order, prefix the name with an exclamation point.

List columns
The list of columns that appears depends on what arguments are used, but follows some general rules. A column can always be forced to show by adding its name to the argument list in the opening rt tag, and can always be forced off by adding 'no'+name. The columns as they appear from left to right are:


 * ticket - always shown, except if 'noticket' is given
 * queue - name of the queue. On by default unless viewing a single queue.
 * subject - always shown, unless 'nosubject' is given
 * status - ticket status. On by default unless viewing a single status type.
 * priority - numeric priority. Off by default.
 * owner - the name of the owner of the ticket. If their "real name" is available, that will be shown. On by default.
 * updated - date the ticket was last updated. On by default. Format controlled by $wgRequestTracker_TIMEFORMAT_LASTUPDATED
 * updated2 - date the ticket was last updated. Off by default. Format controlled by $wgRequestTracker_TIMEFORMAT_LASTUPDATED2
 * created - date the ticket was created. Off by default. Format controlled by $wgRequestTracker_TIMEFORMAT_CREATED
 * created2 - date the ticket was created. Off by default. Format controlled by $wgRequestTracker_TIMEFORMAT_CREATED2
 * resolved - date the ticket was resolved. Off by default. Format controlled by $wgRequestTracker_TIMEFORMAT_RESOLVED
 * resolved2 - date the ticket was resolved. Off by default. Format controlled by $wgRequestTracker_TIMEFORMAT_RESOLVED2
 * age - the age of the ticket, for example "4 days". Off by default.

If you want to write custom column headers, you can add the tablerows argument, which will prevent the table and table column tags from being output: it simply outputs the table rows, so you will need to create the rest of the table yourself.

If you want to disable all balloon tips within the table, use the noballoon argument.

Global variables
The following global variables are available and should be added to your LocalSettings.php file. Only the first two are mandatory.

$wgRequestTracker_URL
This is a link to your RT web interface, and is used to build the external links to specific RT tickets. It should looks something like this:

$wgRequestTracker_URL = 'https://rt.example.com/Ticket/Display.html?id';

$wgRequestTracker_DBconn
This is the connection string that allows the extension to talk to the RT database. This string is passed to the pg_connect function, see the documentation for that function. Example:

$wgRequestTracker_DBconn = 'user=rt_user host=slonik dbname=rt';

$wgRequestTracker_Active
(Default: 1) This controls whether a connection to the RT database is available. It is handy for times when the connection is unavailable, but you don't want to uninstall the extension. If this variable is set to false (0), then tags are simply changed to a text format: <tt> 1234 </tt> becomes <tt>RT #1234</tt> with no links. Example:

$wgRequestTracker_Active = 0;

$wgRequestTracker_Useballoons
(Default: 1) Controls whether to use balloon popups or not, giving detailed information about each ticket. You can set this to 0 if you do not have the Balloons extension installed. Example:

$wgRequestTracker_Useballoons = 0;

$wgRequestTracker_Cachepage
(Default: 0) If this is off, then caching on the page containing rt tags is disabled. Example:

$wgRequestTracker_Cachepage = 0;

$wgRequestTracker_Formats
(Default: array('normal' => "Subject: ?subject? Status:?status?"); ) This is a list of formats that can be used as arguments to the rt tag to control the display of individual tickets. Placeholders to be replaced are indicted by surrounding one of the available columns with question marks. Example:

$wgRequestTracker_Formats = array (  'normal' => 'Subject: ?subject? Status:?status?',    'nameonly' => '?owner?',   'statupdate' => 'Status is ?status?, updated on ?updated?',   );

Note that you should not use the direct names of any available columns (e.g. 'status') as the keys of the array, because these are already used.

Database optimization
While the RT database performs well "out of the box", there are some additional things you can do to make it run better when used with this extension. First, create the following indexes:

CREATE INDEX users_lower_name ON users(lower(name)); CREATE INDEX queues_lower_name ON queues(lower(name)); CREATE INDEX tickets_status ON tickets(status);

Now, make sure each of the tables used in the queries are analyzed:

ANALYZE tickets; ANALYZE users; ANALYZE queues;

You might want to make sure the indexes are being used by running an explain:

EXPLAIN SELECT 1 FROM tickets t JOIN users u ON t.creator=u.id  JOIN queues q ON t.queue=q.id  AND lower(u.name) = 'test' AND lower(q.name) = 'test' AND t.status = 'test';

The resulting query plan should have three "Index Scan" items. If not, consider lowering the random_page_cost parameter, or consult your local Postgres expert.

Time formatting
The timestamps returned by the RT extension can be changed by using global variables. The format is $wgRequestTracker_TIMEFORMAT_ plus the name of the column's format. This is passed to the TO_CHAR function to create a string: for a full discussion of how to use this, see the Postgres documentation. The default settings are as follows:

$wgRequestTracker_TIMEFORMAT_LASTUPDATED = 'FMHH:MI AM FMMonth DD, YYYY'; $wgRequestTracker_TIMEFORMAT_LASTUPDATED2 = 'FMMonth DD, YYYY'; $wgRequestTracker_TIMEFORMAT_CREATED     = 'FMHH:MI AM FMMonth DD, YYYY'; $wgRequestTracker_TIMEFORMAT_CREATED2    = 'FMMonth DD, YYYY'; $wgRequestTracker_TIMEFORMAT_RESOLVED    = 'FMHH:MI AM FMMonth DD, YYYY'; $wgRequestTracker_TIMEFORMAT_RESOLVED2   = 'FMMonth DD, YYYY'; $wgRequestTracker_TIMEFORMAT_NOW         = 'FMHH:MI AM FMMonth DD, YYYY';

To override any of the above, just put them in your LocalSettings.php file.

All times shown are adjusted for the local MediaWiki user, as long as they have set their Time Zone in the MediaWiki user preferences.

Custom fields
RT supports the use of custom fields. To use these in this extension, just add the custom=xxx argument like so:

</rt>

This will display all tickets in which the custom field named "Postgres" has been set.