In this chapter, we’ll give you a basic overview of how to use RT’s web interface. This is the primary interface to RT for both users and administrators—you can access all of RT’s features and configuration options through it. Once you’ve read this chapter you should be able to log into RT and find, modify, and resolve tickets. We’ll also touch on what you can use email for and how it integrates with RT. The RT command-line tool, covered in Chapter 4, also performs many of the same tasks you’ll learn in this chapter.
This chapter assumes that you are running your own RT installation. If you are using an existing installation to learn about RT, be careful about creating new tickets. You don’t want to broadcast your test tickets inadvertently to the entire user base. For experimenting, you might be interested in the standalone server that ships with RT. The standalone server is a small web server written in Perl. Because it can handle only a limited number of concurrent web clients, it is not really suitable for anything other than testing. However, it is very useful for that, because it requires no other web server to be installed. See Standalone Server Mode in Chapter 2 for instructions on how to start the standalone server.
If you are working in an environment where there is an existing RT installation, your RT administrator most likely will give you a username and password as well as instructions on where the RT login URL is. When you first connect, you will see a login box, something like the one in Figure 3-1.
If you have a brand new RT instance, you can log in with the default username root and password password. You should change this password immediately by clicking on the Preferences link, especially if your RT instance is accessible from the Internet.
Once you’ve successfully authenticated yourself to RT, you will see the home page with the title “RT at a glance.” This page, shown in Figure 3-2, displays a snapshot
of RT as it applies to you. It gives you easy access to the tickets you own, tickets you’ve requested, tickets in the queues you watch, and interfaces for finding existing tickets and creating new ones. Many items on this page are clickable—such as ticket numbers, ticket summaries, and queues—and take you to ticket displays or queue listings.
The display is easy to customize and extend, so don’t be too alarmed if what you see is not exactly the same as what these screenshots show. Since this home page is intended to be a clearinghouse of information, administrators may add extra queue displays or links to documentation, internal policies, and canned searches. The next major release of RT should make this sort of configuration.
Along the left side of the page is the main site menu. This menu has links to all of the major things you can do with RT: search for tickets, configure RT, change your preferences, and so on. Configuration is covered in more depth in Chapter 5, and customizing your preferences will be covered in Chapter 6. The rest of this chapter concentrates on the Tickets menu item.
You can create a ticket from anywhere in RT; the top of every page has a small form with a button labeled New Ticket in and a drop-down menu listing the queues you can access. Select the queue in which you want to create a new ticket, and click the New Ticket in button. It will take you to the new ticket form shown in Figure 3-3.
The two most important fields in this basic form are the subject of the ticket and an entry box for a description; these are the first items that people see when they look at your ticket. The subject is displayed on the main page with no context, so you should make sure that it is clear and concise. The description field is the primary explanation for what the ticket is about, so you should take care to include all the relevant information. Also keep in mind how the description will be used. For example, tickets created in an Emergency queue outside of business hours might send a message to the on-call operator’s SMS device. A ticket that does not get to the point within the SMS character limit will be pretty frustrating for everyone involved.
Fill in all the appropriate details, click the Create button, and you’ll have a new ticket. Congratulations!
There is a quick ticket creation box at the bottom of the home page that instantly creates a new ticket with an empty description.
Tickets are identified by number. On a fresh install, the first ticket you create is numbered 1. Every new ticket after that gets a number one higher than the previous ticket. If your RT instance is configured to send mail when a ticket is created (as it is by default), then you should get an email message shortly with a summary of the ticket you created. This message tells you the number that was assigned to the new ticket and provides a URL to the ticket display form. Keep this URL, as you’ll need it shortly.
When a new ticket is created, RT may run some user-defined actions—called scrips. These scrips can do almost anything, but the most common type of scrip sends mail to the queue’s watchers informing them of the new ticket. Other scrips might send a notification to an alphanumeric pager, post a message to an IRC channel, or even print the ticket’s info to a local line printer. You can read more about scrips in Chapter 5.
The important part of handling a request is doing the work, but once you’ve completed the task, you need to update the ticket to reflect your work. So how do you update a ticket? First, you need to go the main display page for that ticket. Clicking on a ticket’s ID or Subject from the home page (Figure 3-2) is one way to get there. If you click on the name of a queue in the Quick Search box on the right of the home page, you can preview all the tickets in that queue and select your ticket from the list. You also can enter a ticket number in the search box on the top right of every page, and click Search to get there.
A fourth way to get to the ticket display page is with a direct link in the browser. The URL to display a ticket always will be in the format http://<
RTSERVER
>/Ticket/Display.html?id=<
NUMBER
>, where RTSERVER is the root of your RT instance, and NUMBER is the ID of the ticket. The notification emails RT sends when a new ticket is created will contain this URL unless your administrator has removed it from the template. If none of these help you, and you don’t know the ticket number, you can use the search interface to find your ticket. RT’s search UI lets you build complex queries with relative ease; see Searching for Tickets later in this chapter.
Once you get to the ticket’s display page, you are confronted with a colorful interface, which shows the major groups of ticket attributes. The metadata associated with a ticket is divided into four main categories—Basics, Dates, People, and Links—each of which tracks a different aspect of the ticket, as in Figure 3-4. You can edit each category individually by clicking on the category name in the main display area or by clicking on the category link in the sidebar on the left. The Jumbo form linked from the sidebar edits all attributes at once. The Jumbo form is quite busy compared to the other pages, but it has the advantage of allowing many different types of updates all at once.
The Basics category includes obvious things, like the subject, status, priority, and queue of a ticket. It also includes elements like the estimated amount of time to complete the work, the amount of time worked on the ticket—which can be very useful for tracking the scale of requests—and the amount of time left before the initial estimated completion date passes. This area displays any custom fields attached to the ticket as well.
The Dates category includes the start date of the ticket, the date the actual work started, when the requestor was last contacted about the request, and the date by which the work must be completed. If you and other users maintain these dates accurately, they can be used to generate reports on how long requests take to be fulfilled. Dates can be entered in a variety of formats, and, as long as the format is unambiguous, RT will figure it out.
The People category lists watchers, requestors, and the ticket’s owner. Long-lived tickets have a tendency to accumulate many watchers over time, as more man-power is added to fulfilling a request and managers of various sorts start getting interested in why the request is taking so long to be finished. The form to edit a ticket’s People data functions as a search form as well as a modification form. It can find users and groups in RT based on simple searches, remove watchers from the ticket, and change the owner of the ticket by changing the value in the Owner drop-down menu.
The Links category contains all the links between the current ticket, other tickets, and the outside world. You can merge tickets and link them with other tickets through this form. See Merging Duplicate Tickets and Associating Related Tickets later in this chapter for more details.
Beneath the blocks of metadata on the ticket display page is the ticket’s history. This is an audit trail—each ticket update (transaction) has its own place in this list, from the initial creation to every attribute change, reply, or comment.
Many of these transactions record outgoing email. These emails are individually viewable in their entirety, including all of RT’s special headers and headers that are not normally passed on to mail clients, such as Bcc.
RT records two main types of transactions: attribute changes and correspondence. Correspondence and comments are what adds content to a ticket and covers all the replies and user feedback that RT collects. While you can change many different types of attributes, most of the interesting content in your RT installation will come from correspondence. Comments are generally intended as private or internal correspondence about a ticket. RT is very flexible and the exact mechanics will depend on how your administrator has configured RT, but usually correspondence is visible to end-users and comments are not.
You reply to a ticket by clicking the Reply link at the top right of the ticket display page or beside an individual item in the ticket’s history. Figure 3-5 shows the form for responding to tickets. The same form creates either replies or comments, depending on what you select for Update Type. From this form, it’s simple to reply to an end user, mark down how much time you spent composing your response, and close the ticket.
Each ticket has a priority. Priority is a way to indicate relative importance. It can be any integer. Most organizations use the range 0-100. Every queue has a default priority for new tickets if you don’t explicitly set one. To escalate the priority of a ticket, set the priority of a ticket to a higher number. The priority field is in the Basics category, shown in Figure 3-6.
Queues can be configured to automatically adjust the priority of tickets over time. Based on the current priority of the ticket, the priority escalates every day so that it reaches its final priority on a given due date.[6]
Tickets can have an owner—the user responsible for working on the ticket or for coordinating the work. To assign a ticket to someone, go to the People form from the ticket display page, and select the user from the Owner drop-down list, as shown in Figure 3-7. This list contains the usernames of all the users allowed to own tickets in the ticket’s current queue.
You can assign only tickets that you own or that are unowned. If you need to reassign a ticket that you do not own, you can steal the ticket and then assign it to someone else. Tickets you can steal will display a Steal link next to Reply and Comment in the upper right corner of the ticket display page. Not all users have access to steal tickets, see ACL in Chapter 8.
When you are satisfied that the ticket you are working on is finished, you can change its status to resolved, so other users know it doesn’t need any more work. This process is known as resolving the ticket. To modify a ticket’s status, just click Resolve in the upper right hand corner of any ticket page, as shown in Figure 3-8.
The form used for resolving a ticket allows you to send a reply to the ticket’s requestor and watchers.
Certain scrips run when a ticket is resolved. The default scrips send mail to the ticket’s watchers.
Sometimes, multiple people submit reports for the same problem. This is especially likely if you’ve got a big problem in a busy environment. When it happens, you need a way to tell RT that the multiple tickets are actually the same request. RT lets you collapse tickets together in a process called Merging.
Go to the Links form for the ticket you want to merge. This form has two major sections, Current Links and New Links, as shown in Figure 3-9. The Current Links section describes any existing relationships that the ticket has and provides a simple editing interface. The New Links section allows you to define new relationships.
To merge one ticket into another, enter the number of the target ticket in the Merge Into Field, and submit the form. You can merge any number of tickets this way, although you need to merge them one at a time.
Once the tickets are merged, displaying either ticket number will display the metadata and history for all the merged tickets. Any further changes to any of the merged tickets also will show up on all the merged tickets. Figure 3-10 shows the merge transaction in the status listing of a merged ticket.
Sometimes a ticket represents a complex issue or difficult request, and you may need to break it down into smaller, more manageable pieces. When this happens, it makes sense to create tickets for these smaller tasks, and associate them with the original ticket. RT provides a Depends On/Depended On By relationship for these cases. From the Links form of the new ticket, shown in Figure 3-8, enter the original ticket’s number in the Depended On By field, and save your changes.
You can create this relationship from the other direction as well: on the Links form for the original ticket you can enter the new ticket’s number in the Depends On field. Once this relationship is established, the parent ticket cannot be resolved until the child ticket is resolved. A ticket can have multiple parents and multiple children, which can be used to create arbitrarily complex and interdependent workflows.
The Depends On/Depended On By relationships are similar to the parent and child relationships. The practical difference is that RT doesn’t enforce the relationships. With parent/child relationships, the parent ticket cannot be resolved until all the child tickets are resolved, but with Depends On/Depended On By relationships, either ticket can be resolved without the other.
Sometimes tickets are not directly related, but mention other tickets. For example, a ticket about email slowness might mention a ticket from earlier that morning about the Exchange server spontaneously rebooting itself. This is where the Refers to and Referred to by relationships come into play—the email ticket would reference the earlier ticket. These relationships are bi-directional: when ticket A has a referred to relationship with ticket B, ticket B necessarily has a referred to by relationship with ticket A. RT maintains these relationships automatically, although it doesn’t try to discover them for you. Figure 3-11 shows the Refers to relationship in the Links box on the main ticket page.
In an active RT instance, with thousands of tickets, finding the ones you are interested in can quickly become a chore. Luckily, all of the ticket metadata we’ve been harping about is searchable. To start a new search, click on the Tickets link in the main menu. This takes you to an empty ticket search form, as shown in Figure 3-12, a very flexible and powerful search tool.
The Add Criteria section is less complicated than it looks. Each criterion you want to add is represented by a row of form elements. For example, the selected options in Figure 3-13 search for tickets where the queue is General, the status is open, the owner is Nobody, and the priority is greater than 90.
When you click the Add button, it adds all the criteria in Figure 3-13 to the query at once. The next screen clears the Add Criteria section, but it lists the criteria in the Query section toward the upper right of the page, as shown in Figure 3-14.
The query builder also allows you to choose the fields you want to display when listing your search results. The default display shows many fields, but you can limit the display to only those fields you want in the Display Columns box at the bottom of the search form page, shown in Figure 3-15.
Under Show Columns you can remove unwanted fields from the display or move a field forward “^” or back “^” in the display order. Under Add Columns you can
select a new column to add to the display, set a link target, title text, and text style for it under Format, then add it to the display with the “->” button. At Order by, select which column to sort the results and whether to sort them ascending or descending. At Rows per page, select how many results to display at a time.
Once you’ve created your query and chosen the fields you want to display, execute the search by clicking the Search button at the bottom of the form.
Ticket searches in RT use a special-purpose query language called TicketSQL. The graphical query builder above generates TicketSQL for the search you want to perform. The Advanced link in the Tickets menu lets you write your own TicketSQL query from scratch.
If you generate a query with the query builder, and then click Advanced, the text area will be populated with your query. This is useful for learning TicketSQL.
TicketSQL is a simple language geared toward selecting tickets from RT’s database. It’s a variation on SQL—the Structured Query Language—which is a standard language used to query relational databases. To understand how to create effective searches, you’ll need to understand a little bit about how TicketSQL works. With TicketSQL, as with SQL, you create a series of zero or more name = value conditions (they are called predicates in SQL), and apply these limits to the data set. The set of items that match these limits is the result.
Here is a concrete example: to find all the tickets with a status of new, you would use the following TicketSQL:
status = 'new'
Simple enough. This limits the result set to only tickets with a status of new. Multiple clauses are joined with either AND or OR to indicate whether both conditions must be true or either one can be true. A search for all tickets with a status of new that live in the General queue would look like:
status = 'new' AND queue = 'General'
A ticket must match both of these conditions to be returned by the search. However, consider a search for tickets with a status of either new or open:
status = 'new' OR status = 'open'
This time, because OR is used, a ticket may match either one of the two conditions in order to be returned from the search. A ticket will be returned if it is new or if it is open.
You can have as many limits as you want. Use parentheses to group the conditions whenever they get a little hairy. Here is a search for tickets in either the General or Customer Support queues with a status of new or open that are owned by the user aml:
(status = 'new' OR status = 'open')
AND
(queue = 'General' OR queue = 'Customer Support')
AND
owner = 'aml'You can search for custom field values in the same way as standard ticket attributes.[7] Simply prefix the name of the custom field with CF. to indicate to the TicketSQL parser that you are searching over a custom field:
(status = 'open' OR status = 'new')
AND CF.Visibility != 'private'From the search results page, you have several display options. The most obvious is to choose the specific ticket you were looking for, and display that one. However, there are times when you might want to manipulate the tickets in an external program, so RT defines the standard export formats spreadsheet and RSS. The links to these exports are in the lower right corner of the search results page.
The RSS version of the search is useful for maintaining a list of tickets in a format usable by an RSS aggregator.[8] The spreadsheet version is really tab-separated values that most spreadsheet programs—Excel or Gnumeric, for example—can import. Many of these programs can be configured to retrieve results directly from the web, which may be even more convenient.
Sometimes, you need to perform the same operation on a bunch of tickets at once. For example, when an employee leaves, you might need to reassign all of his tickets to someone else. Whenever a search returns multiple tickets, you can use the bulk update form to modify all of them. The lower right of the search results page has a link titled Update multiple tickets. This brings you to a new form, shown in Figure 3-16.
This form has many of the same sections as the Jumbo form, and any changes you make here apply to all the selected tickets. By default, all tickets that match the search are selected, but you can exclude tickets from the bulk update by unchecking their Update checkbox on the ticket list at the top of the form.
The earliest versions of RT worked almost exclusively by email, and it is still possible to interact with RT almost entirely by email. By default, RT has scrips that send mail when interesting things happen. Whenever correspondence comes in for a ticket, that correspondence is sent to each Watcher by email. This behavior is controlled by a scrip that can be disabled or extended by the RT administrator. Simply responding to this email will record the response in RT, attached to the same ticket. This makes it easy to stay in the conversation about a ticket without having to continually go back to the browser. This also allows people external to the organization to access RT, without the need to open holes in the corporate firewall.
The mail administrator can set up specific email aliases for creating tickets.[9] By sending an email to such an alias, you create a ticket directly in RT. Such email aliases can be very convenient for non-interactive processes that know how to send mail, such as cron, or as destinations for web forms. Many users also find it easier to create tickets by mail, especially when they are outside the corporate firewall.
The format of the messages that RT sends out is completely customizable by the RT administrator and varies based on the type of transaction. For example, when you create a new ticket, the default message looks like this:
Greetings,
This message has been automatically generated in response to the
creation of a trouble ticket regarding:
"My frobnitz is broken... again",
a summary of which appears below.
There is no need to reply to this message right now. Your ticket has been
assigned an ID of [RT Essentials #5].
Please include the string:
[RT Essentials #5]
in the subject line of all future correspondence about this issue. To do so,
you may reply to this message.
Thank you,
-------------------------------------------------------------------------
My frobnitz appears to be broken again. This is the third time
this week, is there something that can be done about this? Thanks!Mail triggered by correspondence looks slightly different, and it contains information about the ticket and about the type of action that was taken.
To add correspondence to a ticket, reply to one of the messages that RT sends out. Your response will be recorded automatically as part of the ticket history and possibly remailed out to the other watchers, depending on how RT is configured.
Out of the box, RT limits what can be done by email, since reliably establishing identity with email is difficult and generally involves using cryptography (with PGP or S/MIME certificates). Most organizations don’t have the necessary infrastructure for this, so ticket attribute changes are not allowed via email. Enhanced versions of the RT mail gateway that allow attribute changes are available as add-ons to RT.