How to use keywords

RT2 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.

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:

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

This tutorial will teach you 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.

Step 1: Create 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:

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.

Step 2: Add 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:

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.)

Hopefully this tutorial will help you get the most out of keywords in RT. Keywords can be an enormous help in adding order and searchability to a large set of tickets. If you come up with creative uses for keywords, send them in to <rt-users@lists.fsck.com> and let us know what they are!