Extension:RequestTracker

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manualManual:Extensions
Crystal Clear action run.png
RequestTracker

Release status:Extension status stable

Mediawiki.RT.extension2.png
ImplementationTemplate:Extension#type Tag
DescriptionTemplate:Extension#description Interface to a Request Tracker instance
Author(s)Template:Extension#username Greg Sabino Mullane (turnsteptalk)
Latest versionTemplate:Extension#version 2.1 (October 7, 2015)
MediaWikiTemplate:Extension#mediawiki 1.25+
LicenseTemplate:Extension#license PostgreSQL
Download http://gtsm.com/Mediawiki.extension.RequestTracker.2.1.tar.gz
ParametersTemplate:Extension#parameters

$wgRequestTracker_URL $wgRequestTracker_DBconn $wgRequestTracker_Formats $wgRequestTracker_Cachepage $wgRequestTracker_Useballoons $wgRequestTracker_Active

TagsTemplate:Extension#tags
<RT>
Hooks usedTemplate:Extension#hook
ParserFirstCallInitManual:Hooks/ParserFirstCallInit

Translate the RequestTracker extension if it is available at translatewiki.net

Check usage and version matrix.


Purpose[edit]

The RequestTracker extension allows you to display information from your RequestTracker (RT) database on your wiki by using <rt></rt> 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. This version only runs on MediaWiki 1.25 or better, and is meant to replace the old "RT" extension.

Installation[edit]

Download[edit]

Download from Special:ExtensionDistributor. Untar it to your extensions directory.

 tar xvfz MediaWiki.RequestTracker.extension.tar.gz

Install balloons[edit]

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[edit]

Add the following three lines to your LocalSettings.php:

wfLoadExtension( 'RequestTracker' );
require_once("$IP/extensions/RT/RT.php");
$wgRequestTracker_URL = 'https://rt.example.com/Ticket/Display.html?id';
$wgRequestTracker_DBconn = 'user=rt dbname=rt';

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

Basic usage[edit]

This extension adds a new <rt> tag. To make a link to a specific ticket, enter the ticket number like so:

 <rt>1234</rt>

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.

If the string between the tags is not a number, it is assumed to be a queue name.

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:

 <rt q="Sales"></rt>

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:

<rt o=Greg q=MediaWiki,Postgres ob=!created l=20 age !status></rt>

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[edit]

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

Enabling this extension allows full access to your RequestTracker 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 RequestTracker information.

Switching it off[edit]

There are times when you want to turn this extension off, such as if the connection to your RequestTracker database has been lost. Rather than uninstalling the extension and leaving a bunch of ugly raw <rt> 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[edit]

If a number is enclosed by <rt> tags, a link to that ticket in RequestTracker will be created.

<rt>1234</rt>

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.

<rt status>1234</rt>

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:

 <rt>3412</rt>
 <rt subject priority>3412</rt>
 <rt normal noballoon>3412</rt>

Showing lists of tickets[edit]

If no number is given between the <rt> 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. If anything but a number appears between the tags, it is considered a queue name.

List arguments[edit]

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

l: limit[edit]

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

q: queue[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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

$wgRequestTracker_URL[edit]

This is a link to your RequestTracker 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[edit]

This is the connection string that allows the extension to talk to the RequestTracker 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[edit]

(Default: 1) This controls whether a connection to the RequestTracker 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: <rt>1234</tr> becomes RT #1234 with no links. Example:

 $wgRequestTracker_Active = 0;

$wgRequestTracker_Useballoons[edit]

(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[edit]

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

 $wgRequestTracker_Cachepage = 0;

$wgRequestTracker_Formats[edit]

(Default: array('normal' => "Subject: <b>?subject?</b> 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: <b>?subject?</b> 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[edit]

While the RequestTracker 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. (note: these hints are for Postgres only). 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[edit]

The timestamps returned by the RequestTracker 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[edit]

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

 <rt custom=Postgres></rt>

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