 
|
Administering RT - Class Guide
Introduction
Request Tracker is a highly customizable system - as a queue administrator you can tailor RT's behavior in many ways to suit your needs. This powerful flexibility though, comes with a cost: complexity. Understanding how RT behaves and knowing what features it offers are not always obvious. The purpose of this class guide is to introduce you to some of the common ways RT can be customized and to help you get started with administering your RT fiefdom.
The major topics covered here are:
The Queue
Each queue defines a 'domain' or a 'work area' in RT. Many of the customization features RT provides are made to the queue; email behavior, canned-email formats, access control, additional ticket fields can all be changed for your queue by you, the queue administrator.
Most of the customization discussed here is done by starting at the Configuration link in the left-hand menu bar. To look at your queue's configuration, go to Configuration->Queues->your-queue-name.
This will show you the queue's 'Basics' configuration screen. Here you will find fundamental queue attributes such as the queue name and the email addresses used in replies and comments sent in email by RT. In our setup, the 'reply address' also defines the address used to direct incoming mail to your queue.
The basics screen also shows queue preferences such as Spam Threshold.
The full list of queue configuration screens, which display in the context-sensitive left-hand menu bar are:
- Basics
- Watchers (people, groups, or email-addresses that should receive notifications of activity in your queue's tickets)
- Scrips (define the email notification behavior - who should receive email when)
- Templates (define the format and text of your 'canned' outgoing email messages)
- Ticket Custom Fields (additional fields you can attach to tickets)
- Transaction Custom Fields (additional fields you can attach to ticket transactions)
- Group Rights (defines RT groups' access to your queues)
- User Rights (defines RT users' access to your queues)
Access Control and Groups
RT offers very fine-grained access control which can be useful but may be hard to understand and configure. For ease of use, when a new queue is set up, we (the Tooltime team) define a default access control model for you which you can then modify if you need to.
We typically grant access to groups and not individual users. For this reason, you will probably not use the 'User Rights' screen under your queue configuration.
An RT group is a named list of people and/or other groups. As part of your initial queue setup, we typically create two groups for you - the 'consultant' group which represents people working on tickets in your queue, and the 'admin' group which defines the people who are allowed to administer your area of RT as well as work on tickets. We also make the admin group a member of your consultant group so that you don't have to specify administrator users in both groups. So for example, this might be the setup for the 'Telephone Repair' queue:
Admin group: telephone-repair-admin
- Ron PhoneBoss
- Joan PhoneBoss
Consultant group: telephone-repair
- Joe PhoneWorker
- Sandra PhoneWorker
- telephone-repair-admin
On our initial setup, we grant all the administrative rights for the queue to the telephone-repair-admin group and all the consultant rights for the queue to the telephone-repair group.
You can see the groups with access to your queue by going to Configuration->Queues->your-queue-name->Group Rights.
Changing your group's membership list
If you hire a new consultant, you can give them access to your RT queue by adding them as a user to your consultant group. To do this, go to Configuration->Groups->your-group-name.
This will take you to the group's 'Basics' screen, which shows you the group name, description and group preference settings.
Select the 'Members' link underneath the group name in the left-hand menu bar and you will see the current members (both users and groups) of your group listed on the left side of the screen.
- To add user members: either select the users' kerberos names from the list and/or type in the kerberos names in the text box to the right (one per line).
- To add group members: select the groups from the list.
- To remove members: check the box next to the user or group entry.
Understanding RT behavior
Replies and Comments
It is important to understand the difference in RT between a reply (aka correspondence) and a comment. Both are message entries that are added to the ticket's history and both can be added either by email or in the web interface.
Replies - are typically sent to the ticket's requestor (unless the requestor sent the reply) and are visible to the requestor if they look at the ticket in the web interface.
Comments - are typically not sent to the requestor and are not visible to the requestor in the web interface.They are private in the sense that the client never sees them.
So if you need to send a message to the customer and append it to a ticket, enter a reply. If you just want to comment on a ticket and not send it to the customer, use a comment.
Watchers
A watcher is a user, group or email address that needs to be notified whenever a new ticket is created or when reply or comment is added to a ticket. Watchers can be defined for the queue (they will see traffic on all tickets in the queue) or for individual tickets. There are different types of watchers in RT:
- Administrative Cc watcher (AdminCc). Will typically receive notifications of new tickets and copies of all replies and commments added to tickets.
- Cc watcher (Cc). Will typically receive copies of replies added to tickets, but not comments.
- Requestor. The requestor can be thought of as a watcher and will typically receive copies of replies to tickets. The requestor may also receive a notification when they generate a new ticket.
Email and scrips
What email will RT send to whom and when? Without knowing where to look and how to interpret the information on the screen, this can be a hard question to answer. Understanding the queue's Scrips configuration page holds the key to answering this question. Go to Configuration->Queues->your-queue-name->Scrips to see the scrips defined for your queue.
A scrip is an entity that defines an action (usually sending email) that will take place when a certain event takes place on a ticket in your queue. A template (canned email message) is usually associated with a scrip.
So a scrip has three components:
- The system event that will trigger the scrip (the condition)
- What the scrip will do when it is triggered (the action)
- The canned email message the scrip will send (the template)
The default scrips are:
- On Create, Autoreply to Requestors with template Autoreply: When a ticket is created, email notification is sent to the Requestor using the global 'AutoReply' template.
- On Create, Notify AdminCcs with template Transaction: When a ticket is created, email notification goes to the Admin Ccs, using the global 'Transaction' template.
- On Correspond, Notify AdminCcs with template Admin Correspondence: When a reply (aka correspondence) is added to a ticket, Admin Ccs are notified, using the global 'Admin Correspondence' template.
- On Correspond, Notify Requestors and Ccs with template Correspondence: When a reply (aka correspondence) is added to a ticket, the Requestor and Cc watchers receive email notification, using the global 'Correspondence' template.
- On Correspond, Notify Other Recipients with template Correspondence: When a reply (aka correspondence) is added to a ticket, any additional To, Cc, or Bcc recipients specified for the transaction will receive email notification, using the global 'Correspondence' template.
- On Comment, Notify AdminCcs as Comment with template Admin Comment: When a comment is added to the ticket, Admin Ccs are notified, using the global 'Admin Comment' template. The 'from' address is set to the queue's comment address so that any replies to this mail will be added to the ticket as comments, not replies.
- On Comment, Notify Other Recipients as Comment with template Correspondence: When a comment is added to the ticket, any additional To, Cc, or Bcc recipients specified for the transaction will receive email notification, using the global 'Correspondence' template. The 'from' address is set to the queue's comment address so that any replies to this mail will be added to the ticket as comments, not replies.
You can determine who will actually get the email by checking your queue's Watcher configuration screen - for example if you have your RT admin group defined as an AdminCC watcher for your queue, then all members of this group will get the notifications outlined for AdminCcs above - i.e. new ticket notifications and all copies of replies and comments.
Customizing RT
Doing more with Scrips
Beyond the default setup outlined above, you can add new scrips to your queue to extend RT's functionality. Scrips involve Perl programming and a knowledge of the RT API. The latter is not well documented, but we are planning to provide some training and documentation in how to work with scrips along with a library of useful code that people can copy for their own use.
Here are some of the things you can do with scrips:
- Automatically populate custom field values from incoming email messages.
- Instantly resolve tickets coming from certain email addresses.
- Automatically change the status of a ticket if it is moved into your queue from another queue.
- When a custom field value is changed to a certain value, create a new ticket in another queue.
- Use an SAP Req Number extracted from an incoming email message to create a clickable link from the ticket to the SAP web requisition display page.
Custom Fields
RT provides a set of common ticket fields - subject, status, date created etc. You may also want to have your own fields on tickets in your queue - for example IP Address, Operating System. RT allows you to do this by creating custom fields for your own queue.
Custom fields can be of different types, for example 'Enter one value' which is a simple text field and 'Select one value' which appears as a single-select drop-down list, containing values that you define.
You can either use a custom field that has already been defined in the system or you can create your own.
To see your queue's custom fields and all of the custom fields in the system, go to Configuration->Queues->your-queue-name->Ticket Custom Fields. You will see three headings with lists of fields under one or all of them:
- Global Custom Fields. These are system-wide custom fields that appear in every ticket in every queue. We currently have no global custom fields defined. As a queue administrator, you cannot create global custom fields.
- Selected Custom Fields. These are the custom fields set up for your queue. Clicking on the field name will take you to the field's maintenance screen where you can modify the field name, type and if applicable, set of allowed values.
- Unselected Custom Fields. These are other custom fields in the system set up for queues other than your own. Some fields have been created for shared use - they are indicated by the text 'for common use' in the field description. You can use these shared fields for your queue by checking them on this screen and submitting. Note that on the shared 'Select one value' or 'Select Multiple values' fields, you will not be able to modify the list of allowed values - because of the shared nature of the fields, this must be done centrally.
Transaction Custom Fields will appear by each transaction, or history entry, on a ticket. You may wish to categorize transaction entries (for example a comment might be a result of a client's phone call, walk-in visit, or your phone call to the client abnd you may want to keep track of that). Transaction custom fields are currently rarely used.
Preferences
Several RT features that used to be system-wide are now customizable through preference settings. There are preferences available by:
- User (mostly affecting web interface appearance and behavior)
- Queue (mostly concerned with queue-specific functionality)
- Group (web interface apearance - apply to all of group's members)
See the document New Features in RT - November 2005 for more details on preferences.
Saved Searches
Saved Searches are named, saved search specifications that can be thought of as bookmarked searches. They appear on the RT home page in the center section titled 'Saved Searches'. Searches can be saved for an individual user or an RT group.
Saved searches are created, modified and can be loaded through the Query Builder screen, under the Ticket Search link on the left-hand menu bar.
For more information on searching, see the document Searching in RT Using Query Builder.
Custom Email Messages (Templates)
Templates define the content and format of email messages sent by RT when tickets are created, replied to etc. By default, your queue uses common 'global' templates which define a basic format for the messages. These templates are referred to in the section on scrips above.
If you want to tailor the content of messages being sent for your queue you can easily do this by creating your own templates and then modifying your scrips to use your templates rather than the global templates.
For example, you might want to improve on the message sent to clients when they generate a new ticket via email. This might be easier if you copy the content of the global template and then tweak it. To do this:
- From your scrips config page, note that the client gets mail when a new ticket is created based on the global AutoReply template (On Create, Autoreply to Requestors with template Autoreply).
- Find the Global Autoreply template: On Create, Autoreply to Requestors with template Autoreply
- Copy the global template's content.
- Create a new template for your queue: Configuration->Queues->your-queue-name->Templates->New Template.
- Give your new template a name, paste in the global template content, make any changes you need to and Submit.
- Tell your scrip to use your new template rather than the global one: Configuration->Queues->your-queue-name->Scrips and select the On Create, Autoreply to Requestors with template Autoreply scrip. On the scrip's config screen, change the entry in the Template drop-down list to the new template you juts created and Submit.
Finding Your Tickets
There are several ways in RT to locate tickets.
Search Box
This is the text box that appears in the top-right corner of every RT screen. You can do these searches from this box:
- Enter a number to find a single ticket.
- Enter a queue name to find all tickets in a queue.
- Enter a full email address to find all the tickets for a requestor.
- Enter a text string to find all tickets whose subject matchesthe string.
- Enter 'email:aaaa' to search for tickets where requestor's email address or kerberos name contains 'aaaa'.
- Enter 'phone:nnnn' to search for tickets where requestor's phone number contains 'nnnn'.
- Enter 'name:aaaa' to search for tickets where requestor's name contains 'aaaa'.
- Enter 'address:aaaa' to search for tickets where requestor's office address contains 'aaaa'.
Quick Search
This name is given to the list of queues appearing on the right-hand side of the RT home page. By each queue is shown the number of open and new tickets. These actions are available:
- Click on queue name: searches for all new and open tickets in the queue.
- Click on number under 'New': searches for all new tickets in the queue.
- Click on number under 'Open': searches for all open tickets in the queue.
Query Builder
This is the name given to RT's default search screen. It is what you get when you click on 'Ticket Search' unless you set the 'Simple Search' as your default search screen in Preferences.
This screen lets you build up simple or complex queries - you can define the search criteria, the columns appearing in the search results, the sort sequence. The screen also provides the interface for manipulating saved searches.
Refer to the document Searching in RT Using Query Builder for fuller details on using this screen.
Advanced
If the Query Builder screen is not scary enough for you, there's an Advanced search screen. This allows you to type in and edit queries directly in text boxes. Its main use is in tweaking already-loaded queries. The Query Builder screen provides controls for adding parentheses and AND/OR operators to queries, but they are hard to understand and don't always work reliably. The Advanced screen makes this a little easier.
For example, say you want to show tickets from two queues, Queue1 and Queue2. Using the Query Builder screen you can add each queue to the query by selecting the queue in the criteria section and hitting the Add button. This will result in a search where
queue = 'Queue1' AND queue = 'Queue2'
What you really want is for that AND to be an OR. If you go to the Advanced screen, the query appears in a text box and you can easily change the AND to OR - and add parentheses if you need to.
Simple Search
This screen was created to provide a limited but easier search interface. Many common searches can be done with this screen, and if your needs are occasionally more complex, the Query Builder is still available.
You can make the Simple Search your default search screen by setting a user preference.
(last modified: 11/9/05)
