WebRT Administration

Guide

Table of Contents

Introduction

Administration Guide - Concepts - Terminology

- Ticket - Links - Requestor - Status - Users - Attributes - Privileged Users - Nonprivileged Users - Queue - Groups

- Normal Groups - Pseudogroups

- Watchers - Types of Watchers

- Requestors - Ccs - AdminCc

- Watcher Scopes - Queue - Ticket

- Keywords - Access Control (ACLs)

- Description of Rights - Scrips - Conditions - Actions - Templates - Relationships

- Backup and Restoration - Email - Administrative Procedures

- Creating a user - with the CLI - with the web interface

- Creating a queue - Granting users rights to access a queue - Using scrips to notify users of changes to tickets in a queue

- Keywords - Creating a Set of Keywords - Adding a keyword selection to a queue - Sample Keyword Tree for IT Support

- Performance Tuning - Database Optimisation - Operating System and Environment - Hardware aspects

- Extending and Customizing RT

- Scrip Actions - Scrip Conditions - Plugging in your own user metadata - Plugging in your own authentication system

- Tool Reference - Email Gateway

FAQ - Administration

- Are there any default templates with RT? - What is the purpose of keywords? - Why can't users change their password? - Is there a default password for auto-created users to view their ticket? - How do I delete users and groups - Why aren't emails being sent to watchers? - Can I send emailed reminders to ticket owners? - Email

- What's that Sender: header, and how do I make it go away? - sendmail and sender

- Sendmail won't let me run rt-mailgate - Why is RT so slow? - Why are there two Mason Component directories? - Why is the owner of a new ticket nobody and not the requestor? - How do I delete and re-create my RT database?

Introduction

Request Tracker is a trouble ticketing system. It lets a group of people intelligently and efficiently manage requests from a community of users. RT is used by systems administrators, customer support teams, network operation centres, developers and even marketing departments.

The basic model works something like this:

- A user makes a request via email or a web interface - RT emails the user an automatic reply containing an electronic ticket stub for reference in further correspondence - RT creates a new ticket in a queue containing the user's request. The ticket is now visible via the web interface to queue members, who are generally experts of some kind who can answer the request - If configured to do so, RT also emails the contents of the request to a list of queue members who have opted for such notification, or other people for whom the queue administrators have added an email address - A queue member takes ownership of a request (normally via the web interface) and drafts a reply to the user, which RT records and forwards to the user - The queue member resolves the ticket and moves onto the next new ticket

RT can be configured to suit specific site requirements, but the basic concepts and usage remains the same.

Administration Guide

Concepts

RT is a complex application. You need to understand the concepts behind RT and the terminology describing these concepts if you are going to deploy it to the best effect in your organisation.

Terminology

Ticket A Ticket contains all the information regarding a request, including who requested it, what action has been taken, its current status, and the details of the request. Each ticket is identified by a unique ticket number. The terms ticket and request are used interchangably. Users with a background with the commercial Clarify helpdesk system will be used to the term Case, which also means the same thing.

Links Tickets can be linked to each other with these relationships:

- MemberOf- RelatedTo- DependsOn- MergedInto

These links are informative for RT users viewing tickets, and are also used in a variety of ways by RT such as in searches.

Requestor The user who created the request. He may or may not be a user on the local Unix system. Depending on how RT is configured, he might instead be someone sending an email whose identity cannot be verified.

Status A ticket will always have a status which may be one of: - New: The ticket has never been viewed or acted upon. - Open: The ticket has been viewed, and is being dealt with.

- Stalled: The ticket has been put on hold as it cannot presently be resolved. If there is any further correspondance, the ticket will automatically be reopened.

- Resolved: The ticket has been dealt with, and is no longer an issue.- Dead: This indicates that the ticket was deleted. Usually tickets are only deleted in the case of duplicate requests or spam email. For technical reasons a ticket is never erased from the database, it just has the Dead status.

Sites will sometimes have their own interpretation of each status.

Users Every person or program that interacts with RT has a username and is therefore a user. A user has attributes stored against their username. There is only one type of user, but the attributes means that users have very different capabilities within the RT system. Examples of attributes used to differentiate users are:

- Ticket privileges, where a user has the ability to perform a certain action to tickets such as create or delete- Group memberships, where a user shares attributes with other users- Unix username, which gives the user the right to use RT from the Unix commandline interface

Sometimes it looks like someone can interact with RT without having a username. As you'll find out elsewhere in this documentation, this is not correct.

Attributes Some attribute information is stored for every user.

- Name. This is the username that all activity is logged by. It need not correspond to a username in any other system at all, although it can do either via the external authentication scheme or via the Gecos Unix Username attribute.

- Password. This can be null, although of course it is normally bad policy to do so.- Gecos (Unix Username). If this is not set then the user cannot log in via RT's commandline tool, which uses the unix username for authentication.

Privileged Users Privileged users are users who can be granted rights and responsibilities. Typically they are the staff of the organisation using RT but that entirely depends how your organisation is structured. For example, you can easily create privileged users with minimal privileges to allow your customers to contribute to tickets about a certain topic.

Nonprivileged Users These users can not be granted rights or responsibilites (except as members of pseudogroups. These users can not access the normal RT web interface. When they access the web interface, they are immediately shunted to RT's "SelfService" interface for requestors. When email is submitted to RT's email gateway from an unknown email address, RT will automatically create a Nonprivileged user with a name derived from the email address. RT will assign the ticket to the special nonprivileged user nobody. The newly-created Nonprivileged user is required in order for RT to function (e.g. to track correspondance) and has nothing to do with ticket ownership, queue privileges or anything else. It is a very good idea to put RT behind a spam filter such as Spamassasian. It is not currently possible to force tickets that are automatically created like this to be owned by a particular user.

Queue A queue contains tickets generally of a similar nature, for example, a technical support queue. Queues are an administrative unit with their own privileges, scrip actions, templates and keywords. Each ticket can only be associated with one queue. Multiple queues may be set up, and each will have its own email address. So you might have a queue called noc@example.com which is monitored by technical staff, and billing@example.com which is used by accounts staff. Tickets may be moved between queues, so a tech could pass a ticket onto the accounts department once work has completed.

Queues can be configured differently, so the noc queue may issue an autoresponse when a ticket is created, whereas the accounts queue might be configured to prevent internal correspondance being sent to the requestor.

Groups Groups are logical collections of usernames. In general, if an RT operation can be performed on a single user it can be performed on a group as well. This is particularly useful when dealing with permissions and ACLs. So for example it often makes sense to give a particular group read-only access to a certain queue rather than the many members of that group. Removing a username from the group causes all privileges granted via that group membership to be revoked.

Normal Groups These consists of collections of usernames.

Pseudogroups These are special collections of usernames, and contain some special usernames. These come configured by default. Pseudogroups cannot be created by an Administrator, they are built in to RT. Some memberships in pseudogroups can be changed, however. A list of the pseudogroups is:

- AdminCc- Cc- Everyone- Owner- Requestor

Watchers Watchers are (essentially) people that get email about tickets. Watchers can be added globally (all queues), per-queue, or per-ticket. Right now, watchers can only be individual users, not groups. I expectthis to change.

Types of Watchers

There are three types of watchers.

Requestors Requestors are people making the request which ended up in a particular queue by some means. The requestor does not own a ticket because they made the request (and in most installations the requestor cannot own a ticket), but the requestor usually does get at least some correspondance via email, for example an automated reply via the AutoReply scrip. Requestors traditionally see only correspondence, however since RT knows about some kinds of users (either because they are RT users, or because RT does a matching between email address and RT username) a requestor may also be someone with privileges to do things to the ticket.

Ccs Ccs are people other than the Requestor who need to see email traffic relating to the ticket (exactly what traffic depends on the scripactions that have been set up.) The thing distinguishing a Cc is that while they receive this email they do not necessarily have privileges to do anything in the RT system. Any email address anywhere on the Internet can be in the Cc list.

AdminCc

An AdminCc is just like a Cc, except that the recipient is someone with privileges to do things in RT. Often this may be used so that AdminCcs get to see more details about ticket activity, however this is not necessarily so (for example, some queue administrators might not wish to be burdened with a lot of email.) The only people that can be added as a AdminCcs for a queue are those with permissions to administer tickets in that queue.

Watcher Scopes Queue A watcher can be set for a queue. This person will e.g. be notified of all activities in said, in accordance with the scrips set up for that queue. This will typically be a person who will reassign tickets arriving in the queue or someone who needs to keep an eye on the activities in a section of a company. Ticket As above, but only for one ticket.

Keywords Keywords are tags specific to your organisation that are presented to queue administrators for their use in classifying tickets. The definition and use of keywords is entirely site-specific. Keywords are definied in a hierachical tree. Keywords can be used for searching and reporting, and as trigger values in Scrips. This Administration Guide has an extensive section on keywords which includes a tutorial.

Access Control (ACLs)

RT includes a rich ACL scheme which supports granting rights to users and groups for a given queue or for the entire RT instance.

Rights can be granted to:- a specific user who has the privileged flag set and doesn't have the disabled flag set- a specific locally defined group- one of several 'pseudogroups': everyone, requestor, cc, admincc, owner

Rights granted to an individual user are granted to that user and only that user

Rights granted to a locally defined group will be made available to all members of that group, so long as they remain members of the group.

Rights granted to the pseudo-group 'everyone' will be granted to all users.

Rights granted to any of the following pseudo-groups will be dynamically granted to users based on the current ticket being dealt with: requestor, cc, admincc, owner.

Description of Rights

Rights can be granted to users and groups to define what the user is allowed to do and change in RT. Rights can apply to the whole of RT and all the queues (global) or can apply to a single specific queue. Rights can be granted to individual users and to defined groups of users.

Rights can also be assigned to pseudogroups that define users in a context. The pseudogroups are "Everyone" (all the users on the system), "Requestor" (users that are requestor in the context of the current ticket), "Cc" (users that are Cc , either direct by the ticket or defined in the queue, of the selected ticket) and "AdminCc" (users that are Administrative Cc to the ticket or the ticket's queue).

The effective rights of a user are the combination of the global personal right, the combined global rights of the groups the user is in, the rights of the user and all the groups that the user is in to the currently selected queue and the rights the user gets through the pseudogroups.

A description of all the rights that users and groups can be assigned in RT follows: AdminGroups (global only) Users with this right are allowed to create new groups, modify the name and description of the group and add and remove registered users to and from the group.

AdminKeywordSelects (global and queue) Users with the AdminKeywordSelects should be able to add, delete and modify keyword selections for a specific queue (or all queues if this right is setglobally).

AdminKeywords (global only) Users with the AdminKeywords rights can add, modify and delete keywords. Keywords are global to RT.

AdminQueue (global and queue) Users with the AdminQueue right can change can change anything on the queue 'basics' screen. They can create queues (if granted the right globally). They can "disable" a queue. Which means that no new tickets can be created in the queue.

AdminUsers (global only) Users with this right are allowed to add and modify users. All privileged users are allowed to browse all the registered users.

CommentOnTicket (global and queue) Users with the CommentOnTicket right are allowed to add comments to tickets. When this right is global a user can add comments to all the tickets in RT otherwise the user is only allowed to comment on tickets in the specified queue.

CreateTicket (global and queue) Users with the CreateTicket right can create requests in the specified queue or in all the queues if global is selected.

ModifyACL (global and queue) If a user has the ModifyACL right he/she can change the rights different users and groups can be assigned regarding queues. If the ModifyACL right was granted globally the user can change all the ACLs in RT, including the global ones (including granting him/herself SuperUser privileges). ModifyACL does strange things without ShowACL.

ModifyQueueWatchers (global and queue) This rights enables a user to register and remove other users as watchers (Cc and AdminCc) to a queue. If this right is assigned globally the user can modify watcher settings of all the queues.

ModifyScrips (global and queue) This right allows a user to add and delete scrips from a queue of, if the right is granted globally, change the global default scrips.

ModifySelf (global only) This allows the user to change his/her personal settings. The following fields are now only modifiable by folks with "AdminUsers" permission:

Organization, Disabled, Privileged, Name, ExternalContactInfoId, ContactInfoSystem, ExternalAuthId, AuthSystem, Gecos

The basic philosophy behind the decision about what to limit editing to is that the user should be free to modify their own contact info, but should not be able to modify RT username or fields that could effect ACLs.

ModifyTemplate (global and queue) The user is allowed to modify the templates. If this right is granted globally the user may modify the global templates and the templates for all the queues.

ModifyTicket (global and queue) The user is allowed to modify the ticket. Modifying the ticket includes changing the subject, status, time worked, time left, priorities. ticket dates, keyword values, owner (to users that are allowed to own the ticket?), requestor and watchers and relationships with other tickets. The user can also comment and correspond on tickets.

OwnTicket (global and queue) Only users that have the OwnTicket right can be owners of a ticket. This right can be granted globally or per queue.

ReplyToTicket (global and queue) User with a ReplyToTicket right can add replies to a ticket.

SeeQueue (global and queue) This right right allows the user to see that a given queue (or all queues) exists

ShowACL (global and queue) This allows the user to view the currently active ACLs (rights granted to users and groups). When this rights is applies globally the user is allowed to view all system ACLS

ShowScrips (global and queue) Users with this right are allowed to view scrips.

ShowTemplate (global and queue) Users with this right are allowed to view the mail templates.

ShowTicket (global and queue) Users with this right are allowed to display the ticket.

ShowTicketComments (global and queue) Users are allowed to view the comments entered with tickets.

SuperUser (global only) A SuperUser is allowed to do anything.

Watch (global and queue) The user is allowed to sign up to "watch" this queue or tickets in this queue as a cc or a requestor. The user is also allowed to stop watching tickets in this queue. Think of this as AdminWatchers, but only for oneself as requestor or CC.

WatchAsAdminCc (global and queue) Like Watch, but only as an Admin

Scrips

RT includes a powerful system for implementing local business logic, called 'Scrips'. (The 'Scrips' system is a combination of a 'script' system and a 'subscription' system).

RT allows each site to control this and many other behaviors at the queue level. Through the scrips mechanism, RT allows local administrators to define what actions should be taken on each transaction.

Scrips can be defined per-queue and system-wide. Each scrip is composed of a Condition, an Action and a Template.

Conditions

Conditions are things like:

- OnCorrespond - OnComment - OnCreate - OnStall - OnResolve - OnTransaction

Actions

Actions include things like:

- NotifyRequestorsAsCorrespondence - NotifyCcsAsCorrespondence - NotifyAdminCcsAsCorrespondence - NotifyAllWatchersAsCorrespondence - NotifyRequestorsAsComment - NotifyCcsAsComment - NotifyAdminCcsAsComment - NotifyAllWatchersAsComment

Note: Notify scrips do not send mail to the user performing the action.

Templates

There are a bunch of predefined system-wide templates like:

- Autoreply - Transaction - Correspondence - Comment

Additionally, RT allows local RT administrators to define new system-wide tempaltes and allows queue administrators to define per-queue templates.

Templates can optionally have RFC822 headers which will be appended to an outgoing mail message. If a template has such headers, it MUST contain 2 newlines seperating the message body from the headers.

Relationships

RT has the concept of arbitary relationships that link two (or more) tickets together. A ticket can have multiple relationships with multiple tickets.

Depends on / Depended on By A ticket can depend on another ticket. The normal usage is when a given project (ticket) cannot be completed until another project (ticket) has been completed. Parent / Child, Children A given project (ticket) can be a sub-project of another, larger project (ticket). This also has some of the implications of Depends on/Depended on by, but the focus is on a vertical, rather than horizontal dependency. Refers to / Referred to by This is primarily for documentation purposes. A given ticket can contain the interesting/useful information that doesn't need to be repeated in another ticket.

Backup and Restoration

The RT system is primarily database driven. To backup your working RT installation, it is suggested that you first understand the pitfalls behind backup and restoration of a relational database. The MySQL chaps have written an excellent guide, with specifics:http://www.mysql.com/doc/B/a/Backing_up.htmlhttp://www.mysql.com/doc/B/a/Backup.html

This states in parts:

The key to safe database management is taking regular backups. To take a 'binary' backup of your database you have to do the following:

* Shut down your MySQL database and make sure it shuts down without errors. * Copy all your data files into a safe place. * Copy all your log files to a safe place. * Copy your `my.cnf' configuration file(s) to a safe place. * Copy all the `.frm' files for your InnoDB tables into a safe place.

Email

Administrative Procedures

Creating a user

with the CLI

with the web interface

Creating a queue

Granting users rights to access a queue

- To allow any user to create a ticket in any queue, grant the right 'CreateTicket' to the Pseudogroup 'Everyone' globally. - To allow any user to create a ticket in the queue 'general', grant the right 'CreateTicket' to the pseudogroup 'Everyone' for the queue 'general' - To allow anyone to send in an email update to a ticket in the queue 'general', grant the rights 'ReplyToTicket' and 'CommentOnTicket' to the pseudogroup 'Everyone for the queue 'general'

Using scrips to notify users of changes to tickets in a queue

Keywords

RT has a very useful new feature, called keywords, for tracking characteristics of tickets. Keywords allow you to assign any sort of tracking metrics you want to tickets in your queues. For instance, you could track job applications by geographic region in order to determine where you should locate new offices; or you could add a "severity" level to tickets in order to help you prioritize your work.

Once keywords are added, they become part of the ticket display, and you can use them as restrictions in a ticket search.

Another important use for keywords is reporting. A common requirement is a regular report that includes a brief summary of the tickets that have been closed recently. Keywords can save a lot of time in doing this without requiring the workers to write detailed explanations. Just assign a keyword category such as "Reason for Closure" and the report can be mostly constructed from a normal RT search screen.

Keywords are very easy to add to your RT installation -- they can be added completely through the Web interface. There are two basic steps to adding keywords to RT:

- Create a set of keywords that you want to track; and- Add your keywords to all queues, or to one or more individual queues.

This manual covers how to add a "Progress" keyword selection to a job application tracking queue. This keyword will allow you to track how far along each candidate is in the review process. Using this example you can add any keywords appropriate for your uses to your site's RT configuration.

Creating a Set of Keywords

The first step in using keyword selections is to set up a set of keywords that will be useful to you. A "keyword" is either any individual ticket characteristic (such as an urgency level like "Critical"), or a category

of individual keywords (such as "Urgency"). In planning your keywords, take a look at the example job-applicant keyword selection to the right, and use it as a model. This example shows one keyword selection, with a category named "Progress," and six individual keywords in that category (of which five are shown in the graphic) named "1. Requested interview," "2. Interviewed once," and so on.

Internally, RT does not make a distinction between categories and individual keywords -- all keywords are stored in one "tree" structure (just like a filesystem with a root directory and subdirectories). Any keyword can contain other keywords. This fact can be helpful in organizing keywords for easy administration.

In our example, we want to create a keyword selection to track candidate review progress for a queue named 'jobs'. Since this keyword selection applies only to the jobs queue, and no other queue on our system, we'll create a top-level keyword called Jobs. This is not required -- you could put the Progress keyword at the top level -- but doing this will allow us to keep ourselves organized by grouping any keywords specific to the 'jobs' queue together. Inside Jobs, we'll create a subcategory called Progress, which is our category keyword. Then, inside Progress, we will create one keyword for each of the selections we want to appear in the form. Our plan, then, is to create the following keyword structure:

- Jobs - Progress - 1: Requested interview - 2: Interviewed once - 3: Interviewed more than once - 4: Offer made - 5: Hired - 6: Offer rejected

One thing to note is that when RT displays keyword selections on a ticket, it sorts them alphabetically. If you would like to have your selections appear in a specified, non-alphabetic order, it is helpful to add a sequential number or letter to the front of each individual keyword. In our example, our interviewing process has several steps that need to follow each other, so we've added "1:", "2:", etc. to the beginning of each step.

Now that we've planned out our keywords, we can add them to RT. While logged into our RT system as a SuperUser (for instance, using the "Administrator" account), first select [Configuration], and then within configuration, select [Keywords]. The keywords administration page shows a list of existing top-level keywords (probably empty at this point), and then a field for adding a new keyword. Following our plan above, type "Jobs" into the entry field and hit the "Add" button. The result should look like this:

Once this is done, we then want to create keywords within the Jobs keyword. To do this, first click on the word "Jobs" (not the "edit" next to "Jobs" -- edit only changes the name of the "Jobs" keyword -- but instead the word "Jobs" itself), and then use the text field to add the "Progress" keyword. Then click on "Progress" and add each of the individual keywords planned out above. When all of the keywords have been added, the result appears as follows:

(In the image above, the numbers "16", "17" and so on may be different on your system -- don't worry about that. These numbers are RT's internal id's for each keyword, and they do not affect your configuration.)

We have now added all the keywords we need to the system. As of right now, these keywords do not appear in any of our tickets, because they have not been added to the queue configuration. What we have done so far is make RT aware of the keywords -- now we need to associate our keywords with our "jobs" queue.

Adding a keyword selection to a queue

Once we have entered keywords into RT, we then need to specify Keyword Selections, which are sets of keywords available for selection on a ticket. To do this, we need to choose a selection model (single or multiple), a selection depth, and which queue or queues will use the keyword selection. Each choice is described below.

A keyword selection is represented in the RT interface as one form selection field -- a list of items that a user may select. Our example keyword selection is pictured at right. There are two varities of keyword selection: Single selection and Multiple selection. In single selection, a user may select any one keyword in the list, but not more than one. In our example, we use a single selection since each step in the interview process is distinct. In a multiple selection, a user may choose one or more keywords in the selection list (usually by holding down the "Control" key while selecting each keyword). For instance, if you had a keyword category called "Ways to contact" containing the individual keywords "Email," "Phone," "Fax," and "Pager," you might want to allow multiple selection to include several contact methods.

A keyword selection's depth represents how many levels down in the keyword tree the selection should include. A keyword selection starts at what we've been calling the category keyword -- in our example, "Progress." This keyword can contain other keywords, which themselves might contain keywords. As an example, let's say you wanted to change our keyword tree to look like this:

- Jobs - Progress - 1: Requested interview - 2: Interviewed once - 3: Interviewed more than once - 3a: Manager interviewed - 3b: Peer interviewed - 3c: CEO interviewed - 4: Offer made - 5: Hired - 6: Offer rejected

In this case, if we used "Progress" as our category keyword, and set a depth of "1," the 3a, 3b, and 3c steps would not be included in the selection field -- they are two levels deep, so they would not meet the depth requirement. If instead we used a depth of "2" or more, steps 3a, 3b, and 3c would be included in the selection field. Another way to include these steps would be to use a depth "0," which includes all keywords under "Progress," no matter how deep they are.

Next, we can use the keyword selection in two ways: either we can add a keyword selection to a single queue, or we can add a keyword selection to all queues at once. For our example, our keyword selection is specific to the 'jobs' queue, so we will add it to that queue's configuration only. To do this, we first choose [Configuration], then [Queues], and then select the 'jobs' queue. If we had a general keyword selection we wanted to apply to all of our queues (for instance, "Requestor satisfaction: Happy, Okay, Unhappy, Unknown") we would instead choose [Configuration] and then [Global].

Once we have selected the queue to modify (or chosen "Global"), the next step is to click [Keyword Selections]. Doing this will bring up a form with which we can add a keyword selection to a queue. The form uses four fields to configure the keyword selection. The first field is the label that will be put above the selection form field. In our example above, we used the label "Progress." (Note that the label does not need to be a keyword itself -- the label can be any text you want to use.) Next, choose between Single and Multiple selection models, as described above. We are using "Single" selection in our example. Next, choose your category keyword from the pop-up list of keywords. This is the keyword that contains the selections you want to appear in the form. For our example, we choose "Jobs/Progress". Finally, choose the selection depth for the keyword selection. We enter '0', which is interpreted as "unlimited depth beneath

the category keyword." Once these selections are made, hit the submit button, and the following form should appear:

Your keywords are now enabled. Go to the 'jobs' queue and open a ticket, then click on "Keyword Selections." You should see the "Progress" keyword selection, and it should contain the six progress steps entered above, plus the keyword "(empty)," which indicates that no keyword selection has been made for this ticket.

Once you have entered some keyword selections, go to the search form and search for the queue 'jobs'. At the bottom of your results page, you will see that the 'Progress' keyword is now included as a search restriction, so you can use the progress step as a term in searches. (If you associate a keyword with a queue, the keyword search form will only appear on searches within that queue. Global keyword selections will appear on all search forms.)

Keywords can be an enormous help in adding order and searchability to a large set of tickets.

Sample Keyword Tree for IT Support

Since many people use RT for IT support desks the following example is included to illustrate how keywords can be applied

Support staff are trained to always set the keywords on a ticket, even if they don't have time to write a lot in the notes. This way basic sorting and reporting can always be done, giving an idea how time has been spent and what kinds of requests are arising.

There are two main queues, sysadmin and support, with different keywords available to a ticket in each. Here are some highlights of this tree design:

- The keyword 'Closure reason' saves large amounts of time when compiling reports on RT activity. For summary purposes there is no longer any need to plough through the ticket notes. For example, doing a search on the Closure Reason keyword for 'Done - tranferred responsibility' gives an indication of how often problems are being fielded that actually belong to some other area.- The idea of reactive tickets(those that arose through the user getting a surprise, e.g. a hardware failure) and planned tickets (where the user is making contact because he wants somwething to change, e.g. buying a new computer.)- Knowledgebase. Articles that have this set to "required" will show up in a regular search, and something can then be written for the Knowledgebase from the ticket notes. This keyword can then be set to "article written", so it doesn't turn up again.

(root) global queue sysadmin closure reason Done Transferred responsibility elsewhere Won't do - not reasonably fixable Won't do - not our fault Won't do - can't reproduce ticket classification reactive System fault User problem planned New feature request

Purchase - software Purchase - hardware Inhouse app1 - user issue Inhouse app1 - hardware Inhouse app1 - software other support ticket classification bug handholding / user understanding documentation problem new feature request customization billing inquiry flat-rate account closure reason Done No support Inappropriate Bug raised Timeout Software-version 5.5, 6000R2 5.1.2 5.1.1, 6000R1 5.0 4.1.2 4.1 or prior taxonomy Server Hardware Hardware Internet connection DNS Installation - initial configuration Local networking Users - Groups - Directories Fileserver - I-Bays Mail Web server Proxy Printing Backup Remote Access Security Customization Housekeeping ServiceLink Partner Zone Sync Guaranteed Email DNS Hosting Virus Protection VPN Blades Updates Mp3 Jukebox knowledge base Article Written Needs Article

Performance Tuning

RT can be quite sensitive to bottlenecks and poor optimisation choices, particularly if the number queues is high (for example, greater than 50) or the total number of tickets is large (for example, greater than 100k). Exactly what is 'large' for you depends on many factors. (Someone reported to the rt-users mailing list that they had an installation of WebRT on a Pentium 100 running FreeBSD, so this site would have a very small value for 'large' :-)

A very simple thing to check is the version of RT you are running. If you are well out of date in the current stable series then you should consider upgrading. Upgrading is usually not too painful a job and there are regular improvements in RT's performance gained through better coding.

Database Optimisation

Database tuning is very important. If all your RT tables are indexed correctly, and if transactions are working properly, and whatever regular maintenance your database requires is being carried out then there is a much better chance that RT will run smoothly.

Operating System and Environment

The faster your Unix, the faster RT may run (see the other parts of the Performance Tuning section for other factors that contribute to RT speed.) So make sure that your Unix is running well. Use vmstat and iostat (or the equivalents for your OS) to keep an eye on system performance. You'll find a tool such as Netsaint at http://netsaint.org/ invaluable for keeping ongoing records of key system performance indicators at regular intervals. It even has pretty graphs.

RT needs a responsive Apache/Perl web server installation. This requires matching to your hardware requirements. If you have a small server, look at tuning Apache with the start servers and spare servers command. If you have large amounts of memory and you're getting lots of simultaneous incoming requests, increase the number of waiting servers.

Watch your logging. Apache and mod_perl can both do a lot of logging if you turn it on, enough to significantly affect performance. If many of your connections are from the Internet you may wish to turn off reverse DNS mapping in Apache.

If you think you are running tight on resources, have a look at what other services are running. Maybe you don't need them. If this is a critical server and it is heavily loaded, perhaps you need to split the web/perl server out from the database server, because they have different optimisation requirements.

Hardware aspects

Extending and Customizing RT

Scrip Actions

Scrip Conditions

Take a look at http://lists.fsck.com/pipermail/rt-users/2002-February/006509.html this post from the rt-users mailing list.

Plugging in your own user metadata

Plugging in your own authentication system

If you define $WebExternalAuth in your config.pm, then rt will trust whatever apache hands it in the REMOTE_USER variable.

Unsurprisingly, Apache is nice and powerful and can do just about any kind of auth your looking for. How to get apache to auth against foo is out of scope for this, but there's reasonable docs on google. Though you will need “require valid-user” somewhere in your httpd.conf

Tool Reference

Email Gateway

FAQ

Administration

Are there any default templates with RT?

The default templates are in Configuration / Global / Templates.

What is the purpose of keywords?

Imagine if you could define multiple area pulldowns per queue, optionally be able to select multiple values for some areas and could define areas that apply to all queues. That's Keywords. Elsewhere in these online documents is a better explanation of what they are and how best to work with them.

Why can't users change their password?

Grant the user the right 'ModifySelf'. Then they should be able to change their password from "preferences" via the web ui. Is there a default password for auto-created users to view their ticket?

As of now, RT doesn't automatically assign passwords to users on account creation. Down the line, the plan is to assign random passwords and optionally email them to the user. For now, you need to manually set them.

How do I delete users and groups

With groups, the lack of a 'delete' button is an oversight which will be corrected. With users, it's a bit more complex. For referential integrity reasons, you can't delete users, but you can 'disable'. Uncheck the "Let this user access RT" option in the WebUI. Email is still sent to disabled users by scrips (e.g. if the user created a ticket, he might get a copy of comments), so you may wish to catch this with an email alias to redirect traffic from departed users.

Why aren't emails being sent to watchers?

If the logs say "No recipients found", check that the relevant scrips are setup for the queue. Also make sure that the watchers are setup properly for the particular queue. The fact that they have the right to watch things doesn't mean that they _are_ watching them.

Can I send emailed reminders to ticket owners?

RT doesn't have this functionality by default, but it can be scripted up easily enough. With a combination of cron entries, scripting skill and the following command syntax: '/opt/rt2/bin/rt --summary --limit-status=open --limit-owner=Username'

where Username is replaced by an individual ticket owner's username of course. Check the contributed software directory at [http://www.fsck.com/pub/rt/contrib/] for scripts to do this.

Email

What's that Sender: header, and how do I make it go away?

The Sender header is probably being added by one of 2 things. The perl Mail::Internet module insists on adding it; and it's generally added by the MTA if the sender is setting a From. So if your apache and rt run as user www-data, you'll likely end up with headers something like this:

From: Queue <rt-queue@domain>Sender: <www-data@domain>

You can avoid Mail::Internet by using sendmailpipe as the delivery message (an option in config.pm). The next section have MTA-specific information.

sendmail and sender

Sendmail has a concept of trusted users. I don't have a sendmail machine to test on, but take a look at [http://www.sendmail.org/m4/tweakingoptions.html] for sendmail tweaking options The section about confTRUSTED_USERS should do the trick. Your sendmail may just use /etc/mail/trusted-users, redhat's does.

Sendmail won't let me run rt-mailgate

If you get an error like the following:

----- The following addresses had permanent fatal errors -----|”/usr/local/rt/bin/rt-mailgate general action”(expanded from: <RT-ACTION@MUSTANG.HIWAAY.NET>)

----- Transcript of session follows -----sh: rt-mailgate not available for sendmail programs554 |”/usr/local/rt/bin/rt-mailgate general action”... Service unavailable

then, the following information from Jesse should help:

Sendmail has a program called smrsh. smrsh restricts what binaries canbe run from sendmail aliases.

I think it keeps the programs in /etc/smrsh on redhat6. add a symlink from /usr/local/rt/bin/rt-mailgate to /etc/smrsh/rt-mailgate and things should work better.

Why is RT so slow?

Some possible reasons:

- you may have an old version of SearchBuilder. It got a lot faster at one point - your database may lack indexes or be using an old schema. If you're comfordable, you can try to update the schema or add diffs. otherwise you'll need to export and reimport data. - your installation of Apache::DBI may not be operating correctly.

Why are there two Mason Component directories?

RT defines two variables in config.pm for storing the Web files that HTML::Mason interprets, in MasonComponentDir and $MasonLocalComponentDir.

If a file exists in both of these locations, then the copy in the Local Component directory is the one presented to the user. However, the Local Component directory is only checked if the file and directory exists in the Main Component directory.

If you are creating new files (ie, files not in the RT base distribution) to go into the Local Component directory, remember to create matching dummy files and directories in the Main Component directory.

Why is the owner of a new ticket nobody and not the requestor?

The default is to assume that a given RT queue is open to anyone, thus the creator of the ticket (the requestor) is, quite likely, not the person who will be dealing with the ticket (a possible owner). This is true regardless of the means used to create the ticket. Tickets created via email from a previously-unknown email address cause a new unprivileged to be created based on the email address, but the owner is still nobody.

Assuming that you have an internal queue where the only people who can create tickets are also the people who can own tickets, then you could define a Scrip to change the ownership of a ticket to the requestor.

How do I delete and re-create my RT database?

Oh no! You've done something terrible and need to wipe the RT database and start again. Or you are changing what you use RT for, and don't like the fact that disabled queues and dead tickets from the previous use are still in the database even though not visible through the web front-end. However, you don't want to install RT again just to clear the database.

Go to the installation directory, perhaps something like /usr/src/rt2. Stop Apache (using a command such as /etc/init.d/apache-perl stop.) As root, enter these commands:

make dropdb # This destroys the database.make initialize.Pg # For Postgresql. MySQL users need “initialize.mysql”make insert # This populates DB with default users, templates etc Now restart apache-perl and RT should be running with an empty database. The RT root user's password will be whatever you set in the Makefile orlater in /path/to/rt/etc/config.pm.

UI

How do I list the due date in the home page or queue listing?

Take a look at etc/config.pm it has a hash which describes what the generic queue looks like. Add $Ticket->DueAsString to that.

End users

Why don't I receive an email when other watchers do?

Are you taking into account that RT should never mail the person performing the action? RT tries to be smart about this. E-mails are not sent to the people taking the actions. When you reply to the ticket, RT will not send you the reply since you are the one performing the action, and therefore know about it. It will only notify other users affected by that scrip.

Why doesn't the requestor receive my comments?

For the simple reason that comments are not intended for the requestor, and RT does it's best to avoid sending them. Comments are there to let you scream at everybody over how dumb the requestor is, without him getting a copy. If you want the requestor to receive the email, choose 'Reply' or 'Correspond'.

Can an unpriviledged user comment on/reply to the tickets he's requestor for?

Grant either 'Everyone' or (preferably) 'Requestor' the right to 'CommentOnTicket' and 'ReplyToTicket' respectively.

Can I change ticket status/attributes via email?

This functionality isn't in RT at present. You might want to take a look at enhanced mailgate in [http://www.fsck.com/pub/rt/contrib/2.0/rt-addons/]

What format do I use for date and time values?

RT uses a fairly sophisticated date-parser. Most absolute date formats should work.

A few possibilities include: - '6/21/2001' may or may not work depending on your regional settings - 'Tuesday' should work. - 'In 5 days' might work. - '13 July 2001 17:00' - '30 Nov 2001'

How do I send Attachments back to requestors (or to queue watchers) ?

The default Notify ScripActions that come supplied with RT do not have the ability to actually Attach anything in outgoing mails. text/plain works (to be Technical, text/plain is the type of RT::Attachment returned by RT::Transaction->Content() ).

To overcome this, you can do three things. One is to use the http://www.fsck.com/pub/rt/contrib/2.0/NotifyWithAttachment.tgz NotifyWithAttachment contrib ScripAction. This is the reliable method.

Another is to allow end-users to download attachments from RT itself, and provide links to the attachments from the RT Web Interface in the outgoing emails. ( this is an easy way out if you don't want to email attachments to users outside your site )

Finally, you could always generate the requisite MIME Attachment magic in the outgoing template, a non-trivial task.