[Rt-commit] rt branch, 4.4/query-builder-documentation, created. rt-4.2.12-357-g0f05208

[Dustin Graves]

The branch, 4.4/query-builder-documentation has been created
        at  0f052088359ef17698022a51e959112f2a5f47ab (commit)

- Log -----------------------------------------------------------------
commit 0f052088359ef17698022a51e959112f2a5f47ab
Author: Dustin Graves <dustin at bestpractical.com>
Date:   Tue Oct 27 20:45:50 2015 +0000

    Documentation for query builder

diff --git a/docs/dashboards_reporting.pod b/docs/dashboards_reporting.pod
new file mode 100644
index 0000000..314f5aa
--- /dev/null
+++ b/docs/dashboards_reporting.pod
@@ -0,0 +1,203 @@
+=pod
+
+For background on how to build searches in RT, please refer to the
+L<Query Builder Documentation|docs/query_builder>.
+
+=head1 Introduction
+
+Because the Query Builder is the place in RT that allows you to bring together
+collections of tickets based on set criteria, it is also the heart of reporting
+in RT, as you can set RT to put together a saved search that can appear in a
+dashboard. You can also be notified of its results on whatever time interval
+you choose.
+
+=head1 Example
+
+Let's dive into a example that hits close to home for us. At Best Practical,
+the project manager needs to know the status of customer projects and releases.
+Let's figure out the rate of bugs generated between minor releases in the 4.2
+series. Our users write about bugs they find in RT into Best Practical's RT
+instance, which creates a ticket. Thus, we'll be searching for Created tickets
+in the queue appropriately called "RT".
+
+First we need to build these searches, which draw upon the definitions and
+explanations listed in the
+L<Definitions of Ticket Metadata Documentation|docs/ticket_metadata.pod>.
+Thankfully, we already know that we're focusing on only one queue: RT. I can
+find the dates for each of the minor releases on the RT page at our website:
+L<https://bestpractical.com/rt/>. If you go to the bottom left and click on
+'Release Notes', you will get a list of each release, minor and major, of RT.
+Clicking on the 4.2.0 link, you will see that it was released 10/03/2013.
+4.2.1 was released on 11/13/2013. So, the first range that I'll be working
+with is 10/03/2013 through 11/13/2013.
+
+Press 'Add These Terms' to get what we have into the 'Current Search' box:
+
+=for html <img alt="Current Search"
+src="images/current-search.png">
+
+=for :text [Current Search F<docs/images/current-search.png>]
+
+=for :man [Current Search F<docs/images/current-search.png>]
+
+To get the upper limit into this search, you need to go back to the criteria
+and look for tickets that were created before 11/13/2013, and add this piece
+of information to the search by clicking 'Add these terms' again.
+
+The 'Current Search' box should now look like this:
+
+=for html <img alt="With Created Before"
+src="images/with-created-before.png">
+
+=for :text [With Created Before F<docs/images/with-created-before.png>]
+
+=for :man [With Created Before F<docs/images/with-created-before.png>]
+
+Huzzah! Before we tell RT to retrieve results, we first want to make sure that
+this search is saved. That way we can use it to build our dashboard later on.
+Right below the Current Search tab is the "Saved searches" panel. First you
+must choose what group is allowed access to this saved search. Most times
+you'll be able to put the search into My Saved Searches, but if you want other
+people to see it (maybe your manager or teammates), you should choose a group
+that you and whoever else should see this search have in common. How users are
+grouped in RT depends completely on the way your organization uses RT, so group
+names are unique to every RT instance. In this case, I'm going to use
+"RT hacker's Saved Searches", because I want our engineers to be able to use
+this search.
+
+Then you need to name your search. 'Bugs Created between 4.2.0 and 4.2.1' is
+straightforward enough.
+
+Hit the "Save" button, and then "Add these terms and search" so we can see what
+this search turns up.
+
+=for html <img alt="Search Results"
+src="images/dashboards-search-results.png">
+
+=for :text [Search Results F<docs/images/dashboards-search-results.png>]
+
+=for :man [Search Results F<docs/images/dashboards-search-results.png>]
+
+35 tickets were created between 10/3/13 and 11/13/13. We can set this search
+aside for now and retrieve it later on when we're building the dashboard.
+
+For the sake of this exercise, let's only do two more searches, even though
+there plenty more minor versions of 4.2. So, I'll also do a search between
+4.2.1 and 4.2.2, and 4.2.2 and 4.3.2, and save them like I did the one above.
+
+I'd also like to add a more general search for tickets in the RT queue that have
+been resolved in the past six months. For this search, let's say it's
+June 15th, 2015. Six months ago was December 15th, 2014. So, we need to tell RT
+to look for tickets in the RT queue that were resolved from
+December 15th of 2014 and onward:
+
+This search will get us what we need, but only for today. I want this search to
+always turn up tickets that have been resolved in the past 6 months any day that
+I choose to view this search. To adjust the search, I need to go to the
+"Advanced" tab at the top right of the Query Build page. You should get to a
+page that looks like this:
+
+=for html <img alt="Advanced Search"
+src="images/advanced-search.png">
+
+=for :text [Advanced Search F<docs/images/advanced-search.png>]
+
+=for :man [Advanced Search F<docs/images/advanced-search.png>]
+
+In the top 'Query' box, notice that we've instructed RT to search 'Resolved >
+'2014-12-15'. This means 'find tickets resolved after (dates greater than)
+December 15th, 2015'. To make this a moving range instead of a fixed date,
+replace '2014-12-15' with '180 days ago', and click 'Apply' in the lower
+right hand corner.
+
+Note that you can manipulate the content of searched for tickets using this
+form of mathematical notation. If I were to change the search to
+'Resolved < 2014-12-15', I would get all tickets in the RT queue that were
+resolved before December 15th, 2014, which would be a lot of tickets! using
+the =, I would get any tickets resolved on that day. When you combine < or >
+with an =, e.g. Resolved >= '2014-12-15, you get all tickets resolved after
+that day and tickets that were resolved that day, which means that only
+using < and > in searches is exclusive of the day that you choose.
+
+Another way to manipulate searches is to use the arrows underneath the
+Current Search box in the Query Builder:
+
+=for html <img alt="Search Arrows"
+src="images/search-arrows.png">
+
+=for :text [Search Arrows F<docs/images/search-arrows.png>]
+
+=for :man [Search Arrows F<docs/images/search-arrows.png>]
+
+These arrows are useful for relatively complicated searches that include
+clauses that are bracketed by parentheses. Take the below search:
+
+=for html <img alt="Complicated Search Arrows"
+src="images/complicated-search-arrows.png">
+
+=for :text [Complicated Search Arrows
+F<docs/images/complicated-search-arrows.png>]
+
+=for :man [Complicated Search Arrows
+F<docs/images/complicated-search-arrows.png>]
+
+This search will produce tickets in the Asset, RT, or RTIR queues that are
+also either open, new, or are owned by Shawn. This search yields 422 tickets.
+Now I want to find out what happens when I move 'Owner = Shawn' to the first
+clause. Highlight the line where the criterion appears that you want to move,
+and click the arrow that corresponds to the direction you want it to go, here
+up. Once 'Owner = Shawn' is above the AND, this search will now yield tickets
+in the three queues, or owned by Shawn, which could be in a queue other than
+either of those three, that meet either status criteria. This search yields
+362 tickets.
+
+Now that we have all of our searches and knowledge of how to adjust them, it's
+time to compose a dashboard that will show the results of each of these
+searches any time you navigate to it.
+
+First, we need to create the dashboard, then we will populate it with the
+searches we created. Hover over the 'Home' menu and select 'New Dashboard'.
+In the next screen, you'll be prompted for a name. I want to call this one
+'RT bug review'. In the drop down menu below the text field, make sure to
+select the appropriate level of accessibility (just like you did for your
+saved searches). In this instance, it's 'RT hacker's dashboards'.
+Hit 'Create'!
+
+=for html <img alt="Saved Dashboard"
+src="images/saved-dashboard.png">
+
+=for :text [Saved Dashboard F<docs/images/saved-dashboard.png>]
+
+=for :man [Saved Dashboard F<docs/images/saved-dashboard.png>]
+
+The next screen you'll see has four menus in the top right hand corner:
+Basics, Content, Subscription, and Show.
+
+=for html <img alt="Dashboard Content"
+src="images/dashboard-content.png">
+
+=for :text [Dashboard Content F<docs/images/dashboard-content.png>]
+
+=for :man [Dashboard Content F<docs/images/dashboard-content.png>]
+
+To populate the dashboard with the searches we created, click on 'Content'.
+You'll be brought to a screen that looks like this:
+
+Scroll through the Available searches. The searches we've created are all the
+way at the bottom. You can only add one search at a time, so highlight one
+search and click the arrow pointing to the right of the screen. After you've
+selected and added each search, the box to the right of the 'Body' box should
+look something like this, depending on the order you've added them.
+
+Now click 'Show' in the upper right hand corner. You'll see each search
+presented. There's your report!
+
+You can change the overall order of the searches. Click on Content in the upper
+right hand corner, same as we did to add the saved searches. In the right most
+Body content box, where the saved searches we included on the dashboard are
+listed, highlight any one of the searches, and use the up and down arrows to
+push the highlighted search either up or down in the order. You can also delete
+searches from the dashboard if you so choose.
+
+=cut
+
diff --git a/docs/images/added-terms.png b/docs/images/added-terms.png
new file mode 100644
index 0000000..a72b677
Binary files /dev/null and b/docs/images/added-terms.png differ
diff --git a/docs/images/advanced-search.png b/docs/images/advanced-search.png
new file mode 100644
index 0000000..017ddb3
Binary files /dev/null and b/docs/images/advanced-search.png differ
diff --git a/docs/images/complicated-search-arrows.png b/docs/images/complicated-search-arrows.png
new file mode 100644
index 0000000..6d2056a
Binary files /dev/null and b/docs/images/complicated-search-arrows.png differ
diff --git a/docs/images/current-search.png b/docs/images/current-search.png
new file mode 100644
index 0000000..68e3312
Binary files /dev/null and b/docs/images/current-search.png differ
diff --git a/docs/images/dashboard-content.png b/docs/images/dashboard-content.png
new file mode 100644
index 0000000..78ff011
Binary files /dev/null and b/docs/images/dashboard-content.png differ
diff --git a/docs/images/dashboards-search-results.png b/docs/images/dashboards-search-results.png
new file mode 100644
index 0000000..3cde400
Binary files /dev/null and b/docs/images/dashboards-search-results.png differ
diff --git a/docs/images/delete-term.png b/docs/images/delete-term.png
new file mode 100644
index 0000000..c997244
Binary files /dev/null and b/docs/images/delete-term.png differ
diff --git a/docs/images/deleted-term.png b/docs/images/deleted-term.png
new file mode 100644
index 0000000..e44d522
Binary files /dev/null and b/docs/images/deleted-term.png differ
diff --git a/docs/images/saved-dashboard.png b/docs/images/saved-dashboard.png
new file mode 100644
index 0000000..c6e2776
Binary files /dev/null and b/docs/images/saved-dashboard.png differ
diff --git a/docs/images/search-arrows.png b/docs/images/search-arrows.png
new file mode 100644
index 0000000..4dca777
Binary files /dev/null and b/docs/images/search-arrows.png differ
diff --git a/docs/images/search-criteria.png b/docs/images/search-criteria.png
new file mode 100644
index 0000000..1708910
Binary files /dev/null and b/docs/images/search-criteria.png differ
diff --git a/docs/images/search-results.png b/docs/images/search-results.png
new file mode 100644
index 0000000..cd83836
Binary files /dev/null and b/docs/images/search-results.png differ
diff --git a/docs/images/sorting-display-columns.png b/docs/images/sorting-display-columns.png
new file mode 100644
index 0000000..a6f4446
Binary files /dev/null and b/docs/images/sorting-display-columns.png differ
diff --git a/docs/images/subscriptions.png b/docs/images/subscriptions.png
new file mode 100644
index 0000000..a63cb30
Binary files /dev/null and b/docs/images/subscriptions.png differ
diff --git a/docs/images/with-created-before.png b/docs/images/with-created-before.png
new file mode 100644
index 0000000..ac66cca
Binary files /dev/null and b/docs/images/with-created-before.png differ
diff --git a/docs/images/with-newline.png b/docs/images/with-newline.png
new file mode 100644
index 0000000..d206862
Binary files /dev/null and b/docs/images/with-newline.png differ
diff --git a/docs/images/without-newline.png b/docs/images/without-newline.png
new file mode 100644
index 0000000..799da54
Binary files /dev/null and b/docs/images/without-newline.png differ
diff --git a/docs/query_builder.pod b/docs/query_builder.pod
new file mode 100644
index 0000000..c84b40e
--- /dev/null
+++ b/docs/query_builder.pod
@@ -0,0 +1,139 @@
+=head1 Introduction
+
+The Query Builder is RT's search engine. It lets you find tickets matching
+some (potentially very complex) criteria. There are loads of criteria you can
+specify in order to perform a search. Strategies for narrowing your searches
+to find exactly what you're looking for (and no more) are discussed below.
+
+The Query Builder is the heart of reporting in RT, which is covered in the
+L<Dashboard and Reports|docs/dashboards_reporting.pod> document.
+
+To follow along with the examples, go to
+L<issues.bestpractical.com|http://issues.bestpractical.com> and try the
+searches yourself.
+
+=head1 Example
+
+Let's look for tickets in the "RT" queue (RT's bugtracker for itself) that have
+been resolved in the last year. (These examples assume it's currently mid June,
+2015). To do that, we specify the search criteria (Queue is RT, Status is
+resolved, and Resolved after 2014-06-15) in the upper left hand section of the
+Query Builder.
+
+=for html <img alt="Search Criteria"
+src="images/search-criteria.png">
+
+=for :text [Search Criteria F<docs/images/search-criteria.png>]
+
+=for :man [Search Criteria F<docs/images/search-criteria.png>]
+
+Now that I've selected some criteria, I can click either Add These Terms or
+Add These Terms and Search. I'll click the former:
+
+=for html <img alt="Added Terms"
+src="images/added-terms.png">
+
+=for :text [Added Terms F<docs/images/added-terms.png>]
+
+=for :man [Added Terms F<docs/images/added-terms.png>]
+
+The upper right hand side presents all the logic we've specified. This view is
+a nice way proofread your search: Have you captured everything you want? Are
+there things you'd maybe prefer to leave out for now?
+
+It turns out I've changed my mind. I actually don't want to restrict the search
+to just the RT queue. I want to see all the tickets in issues.bestpractical.com
+(which also includes feature requests, RTIR, etc) that have been resolved
+within the past year. To adjust the search, click on 'AND Queue = RT' and press
+Delete:
+
+=for html <img alt="Delete Term"
+src="images/delete-term.png">
+
+=for :text [Delete Term F<docs/images/delete-term.png>]
+
+=for :man [Delete Term F<docs/images/delete-term.png>]
+
+Your search should now look like this:
+
+=for html <img alt="Deleted Term"
+src="images/deleted-term.png">
+
+=for :text [Deleted Term F<docs/images/deleted-term.png>]
+
+=for :man [Deleted Term F<docs/images/deleted-term.png>]
+
+Now, finally, to make the search go, you can either press 'Add these terms and
+Search' (provided there's no new content in the Query Builder), or scroll all
+the way down and press 'Update format and Search'. This search should turn up
+a full page of tickets. Here's the top portion of the list:
+
+=for html <img alt="Search Results"
+src="images/search-results.png">
+
+=for :text [Search Results F<docs/images/search-results.png>]
+
+=for :man [Search Results F<docs/images/search-results.png>]
+
+This is the default view of your results. However, like nearly everything in RT,
+it's configurable. You can select additional columns to appear in your results,
+eliminate columns you don't find useful, or reorder them. To start, notice that
+at the bottom of the query builder page there are two panes: Sorting and Display
+Columns.
+
+=for html <img alt="Sorting and Display Columns"
+src="images/sorting-display-columns.png">
+
+=for :text [Sorting and Display Columns
+F<docs/images/sorting-display-columns.png>]
+
+=for :man [Sorting and Display Columns F<docs/images/sorting-display-columns.png>]
+
+There is more than one option for Sorting so that you can break apart tickets
+with the same search values into a meaningful order. For example, let's say you
+start off by sorting tickets in a search by their owner. Since you've only
+specified to sort by owner, RT doesn't order the tickets owned by the same user
+in a meaningful way. This is where the multiple sort criteria comes in handy.
+You can use a second sorting criteria to sort within the set of tickets owned by
+a single user. For example, you could add a sort by due date to see tickets
+sorted first by owner, and then tickets with the same order are ordered by due
+date.
+
+The Display Columns tab allows you to add or eliminate information displayed in
+the results of your search. NEWLINE indicates a line break, or new row, in how
+the results are displayed. NBSP for adding an empty column (such as what shows
+up underneath id in the following screenshot).
+
+Here is a search with NEWLINE where it is by default:
+
+=for html <img alt="With NEWLINE"
+src="images/with-newline.png">
+
+=for :text [With NEWLINE F<docs/images/with-newline.png>]
+
+=for :man [With NEWLINE F<docs/images/with-newline.png>]
+
+Notice that the structure of the data that's displayed is stacked: Subject on
+top of Requestor, Status on top of Created, etc.. Because we're displaying a
+lot of information (10 fields for each ticket), having the NEWLINE is
+important for the results more comprehensible.
+
+Here is that same search but without the NEWLINE:
+
+=for html <img alt="Without NEWLINE"
+src="images/without-newline.png">
+
+=for :text [Without NEWLINE F<docs/images/without-newline.png>]
+
+=for :man [Without NEWLINE F<docs/images/without-newline.png>]
+
+The same pieces of information are now spread across the display next to one
+another, which can be harder to read. So when you tell RT to display a lot of
+columns, it's usually worth adding a well-placed NEWLINE.
+
+And there are the basics of the query builder! To implement these basics to
+build reports, please see the Dashboard & Reports document. For definitions of
+piece of RT metadata, please see the Definitions of Ticket Metadata document.
+
+=cut
+
diff --git a/docs/subscriptions_feeds.pod b/docs/subscriptions_feeds.pod
new file mode 100644
index 0000000..61023a7
--- /dev/null
+++ b/docs/subscriptions_feeds.pod
@@ -0,0 +1,57 @@
+=pod
+
+For directions on how to build a dashboard from saved searches, please see
+L<Dashboards and Reporting|docs/dashboards_reporting.pod> documentation.
+
+=head1 Subscriptions
+
+You've built a dashboard to help yourself keep on top of your team's activity.
+Your boss wants to see it periodically, but doesn't want to have to navigate to
+it. You can set up a Subscription so that your boss, or anyone else interested,
+receives an email with these saved searches in the body at a specified interval.
+While modifying the dashboard, click on the Subscription link in the upper right
+hand corner, next to Content:
+
+=for html <img alt="Subscription"
+src="images/subscription.png">
+
+=for :text [Subscription F<docs/images/subscription.png>]
+
+=for :man [Subscription F<docs/images/subscription.png>]
+
+Now all you have to decide is what days and times the dashboard will show up in
+your boss' inbox. I've selected that my boss will see this dashboard every 4
+weeks on Thursday. The only search on this dashboard that isn't static is the
+'Bugs Resolved in the past six months', so every month she'll know roughly how
+many bugs have been addressed in the past month, as well as a short term view
+back to how productivity has compared in recent months.
+
+=head1 Feeds
+
+Feeds also apply to saved searches. Click on the saved search Bugs Created
+between 4.2.0 and 4.2.1 in the dashboard we'd created. In the upper right hand
+corner, there is a menu called Feeds. If you hover over it, there are three
+options to choose from: Spreadsheet, RSS, and iCal.
+
+If you select spreadsheet, all of the information that appears in your saved
+search will be exported into a spreadsheet. You can control the contents that is
+exported into the spreadsheet by going to the Edit Search tab on the top right
+hand side of the screen (also the search builder) and making adjustments in the
+Display Columns tab, as we reviewed above.
+
+The RSS feed options give you a feed of all of the correspondence that has
+occurred on all of the tickets in the queue, in written form, in the order that
+the tickets appear in the search, which can change depending on how you have
+arranged the order of this tickets in the Sorting tab of the Edit Search and
+Search builder.
+
+Choosing the iCal option imports all of the ticket dates that are set into your
+calendar app. The tickets are displayed as Start: (name of ticket) on the day
+that the project starts, and Due: (name of ticket) on the day that they are due.
+Depending on your settings, you can have it send alerts according to when
+tickets are due according to the date that's been set in RT. Keep in mind that
+when you make adjustments to dates in tickets that you'll need to do a fresh
+import, as iCal does not pull data from RT live.
+
+=cut
+
diff --git a/docs/ticket_metadata.pod b/docs/ticket_metadata.pod
new file mode 100644
index 0000000..b96ba01
--- /dev/null
+++ b/docs/ticket_metadata.pod
@@ -0,0 +1,228 @@
+=head1 Basic Terms
+
+=head2 id
+
+This term refers to the ticket ID number. Every ticket in RT has a number,
+different from every other ticket in RT, which is its main identity. Notice
+that you can select less than, greater than, equal to, or not equal to. These
+terms work exactly the way you learned in algebra; if you select 'less than',
+your results will come back with tickets that have a numerical id number lower
+than the ticket number you specified; 'greater than' and your results will be
+tickets whose id is larger than the number you entered, and so on.
+
+Ticket ID is a quick way to cull a potentially large number of tickets from
+your search that are irrelevant, especially if you know for sure that, for
+example, the ticket you're looking for was made recently, i.e. above a
+certainly threshold of ticket ID, and vice versa. As with all the other
+parameters, it's yet another way to isolate and manipulate information in
+RT, if less exacting than some of the other options.
+
+=head2 Subject
+
+This term refers to the title, or subject, of a ticket, which appears as the
+subject of an email if you interact with RT in an email client, or as the
+title you see in a queue if you are working in RT itself. This criterion is
+straightforward. You can either include ('matches') or exclude ('doesn't match')
+a word or phrase from your search, and it will spit out all the tickets that
+have or don't have that word or phrase. Try using 'the' in both cases; there
+are surely a lot of tickets that both do and do not have 'the' in the subject
+of the ticket!
+
+=head2 Queue
+
+Queue specification is a great way to narrow your search. If you are a
+privileged user, i.e. you can log into RT and see more than just the
+tickets you own, you probably know the names of the queues you have
+access to. This criterion is pretty self explanatory: you're searching
+for a ticket either in or not in whatever queue you specify from the drop
+down menu. Choice of queue may affect what custom fields you can select
+to search on as well. Depending on how your RT is configured, some queues
+may have custom fields added to them that others don't because of custom
+workflows or pieces of information that are needed to capture for whatever
+entity the queue is representing. We'll dig into this more later.
+
+=head2 Status
+
+Status - The Query Builder allows you to search for a ticket based on what
+status it's in. RT ships with some default statuses, such as 'open', 'stalled',
+and 'resolved'. There is also the 'deleted' status, but RT does not search
+deleted tickets (they're gone for a reason!), so it does not appear as an
+option in the Query Builder.
+
+Note that the statuses in the drop down menu are categorized by queues
+(more specifically, by lifecycle). Many queues probably share some basic
+statuses such as Open or Resolved, but avoid choosing a queue and then
+selecting a status that doesn't exist in that queue. Nothing bad will
+happen; you just won't get any results in your search!
+
+=head2 Owner/Creator/Last Updated By/Updated by
+
+Each of these terms refers to a user connected to a ticket. Whose task is this?
+Who made the ticket as a placeholder for the task in the first place? Who was
+the last person to change information on the ticket, including updating the
+ticket with a reply, comment, change in due date, or linking another ticket to
+it? Who has touched the ticket at any given time since it's creation?
+
+Keep in mind that, with Last Updated by, even an indirect update to a ticket
+counts as an update, in particular listing ticket A as a 'referred to by' link
+to ticket B. If you visit ticket A, you'll see that the last transaction on the
+ticket (assuming nothing else has occurred since you link the tickets together)
+is 'reference added to ticket B', which counts as updating the ticket.
+
+=head2 Requestor Email Address/Requestor RealName, etc..
+
+Each of these titles, or roles (Requestor, Cc, Admin Cc, Watcher, Owner, Queue
+Cc, Queue Admin Cc, and Queue Watcher) refer to how certain users in the system
+relate to a single or a group of tickets. Each option is a piece of data that
+you can record about a user. Say, for example, you have the phone number, but
+neither the name nor organization for a certain Queue Admin Cc. If that data
+was recorded when the user was set up in the system, you can search for him or
+her using it, and so on and so forth for other data items per user.
+
+=head2 Groups
+
+A group in RT is a collection of users. Most often, a group is comprised of
+users who need the same rights to certain entities in RT: it's much easier to
+assign the rights to, e.g., read a queue, once to a group of people than it is
+to assign it 10 or 20 times individually to a bunch of users, thus making
+rights management, amongst other things, that much easier in RT. You could also
+assign a group the rights to be made watchers on a queue, use saved searches,
+and view saved dashboards.
+
+=head2 Dates
+
+Each of the terms available (Created, Started, Resolved, Last Contacted, Last
+Updated, Starts, Due, Updated) are all events or milestones that can take place
+on any ticket in a default RT. Let's go through some of the terms that are
+unfamiliar.
+
+=head1 Advanced Terms
+
+Several of these terms - Created, Started, and Resolved - are self explanatory.
+Let's cover a few that are less obvious.
+
+=head2 Last Contacted
+
+This means 'the last time we contacted them', i.e. the last time
+correspondence, which goes out to the requestor and Ccs was added to the
+ticket. Last updated means the last time anything was adjusted on the ticket,
+e.g. changing the status of a ticket, the time worked, adding a link to the
+ticket, or adding a requestor, adding a comment, amongst many other things.
+Starts is a field in the Dates box that you (or any user that has the proper
+permissions) can set so that the owner of the ticke knows when he or she needs
+to start working on the ticket. Due functions the same way and means when the
+ticket must be completed. Updated means the same as Last Updated, but will
+include all tickets with any update on the date you specify in the search, not
+just tickets that were last touched that day. You can search on these criteria
+either before, after, or on a specific date.
+
+=head2 Time
+
+Time Estimated, Time Worked, and Time Left are each fields in The Basics tab
+and are manually updated as needed. This group of search criteria is a good way
+to find, for example, tickets that are nearing completion (Time Left less than
+5 minutes), or tickets that represent large projects (Time Estimated greater
+than 40 hours).
+
+=head2 Links
+
+Links represent different sorts of relationships between tickets, from simple
+allusions to related conversations across tickets to more complex systems that
+force resolving related tickets in a specific order to enforce a workflow.
+Below are the definitions of each sort of
+relationship and how one in particular may work with others that complement it.
+
+=head2 Child
+
+For a ticket to be a 'child', it must have a Parent ticket. You can create this
+relationship either by making both tickets and marking one as parent of the
+other, or one as the child of the other (in both cases the corresponding ticket
+will update itself with the opposite relationship).
+
+=head2 Parent
+
+Parent tickets have children tickets, all of which must be resolved before the
+parent ticket can be resolved.
+
+How would one use this information in searches? Let's say you're using RT to
+manage a release of the software your company makes. Often times release
+managers will make a parent ticket for the release, and make each of the
+deliverables meant to be included in the release children tickets of it. When
+you go to the master ticket, in the Links box toward the top of the ticket,
+there will appear a list of all the children tickets. While this list is
+useful, it's a bit hard to read. To get a more visible and detailed list of the
+children tickets, which, again, are the various items to be included in the
+release, you can set 'Parent is' in the Query Builder and then the ticket
+number, which will retrieve the list of children tickets.
+
+Similar searches can occur between other tickets that are linked together with
+other hierarchical relationships, such as Depends On and Depended on By. For
+that reason, making a master ticket for a project and then adding the substeps
+and tasks as dependencies to it is a useful approach.
+
+=head2 Refers to
+
+This ticket linkage is a nice way to note when two tickets overlap on subject
+matter, but do not depend on one another for a task. Either ticket can be
+resolved at any time without affecting the other. If you mark one ticket as
+referring to another, that other ticket will automatically update as being
+'referred to by' the former ticket.
+
+=head2 Reffered to by
+
+This is the mirror of Refers to.
+
+=head2 Depends on & Depended on by
+
+This linkage enforces an order of resolution between tickets. A ticket (ticket
+1) that Depends On another ticket (ticket 2) cannot be resolved before the
+latter ticket (ticket 2) is resolved. These criteria are useful in searching if
+you are looking to narrow results for a ticket or group of tickets that for one
+reason or another are dependent on one ticket, perhaps a bug fix that must
+occur before others can be fixed.
+
+=head2 Time
+
+SLA (Service Level Agreement) - An SLA determines the time limit a company has
+to respond to time sensitive issues. For example, Best Practical offers several
+levels of support, each with different windows within which Best Practical must
+answer the clients query. There may be other requirements attached to an SLA,
+but that is up to the company providing the service.
+
+A searching example of when this metadata may be useful could be a manager
+needing to see all tickets that presently have a 1 business day SLA and wanting
+to make this a saved search that s/he can use in a dashboard for easy access.
+
+=head2 Content
+
+This criterion functions similarly to the simple, or 'full text' search. Type
+in any word you want to search for and decide whether you want the search to
+include it ('matches') or exclude it ('doesn't match') amongst your other
+parameters.
+
+=head2 Content Type
+
+Simply, what sort of attachment does the ticket you're searching for have? a
+PDF? JPEG? Spreadsheet? etc..
+
+=head2 Filename
+
+Again, this term refers to the name of the attachment(s) that might be included
+on the ticket you're looking for. Is it a Master Agreement? Summary? Notes?
+
+=head2 Priority
+
+Every ticket has a 'Priority' in the Basics tab toward the top of the ticket.
+The scale is 0 to 99, and the meaning of high and low depends solely on the
+decision of the people managing RT. This piece of metadata doesn't do anything
+in particular on its own unless there are certain extensions installed that
+either raise (or in rare cases lower) the priority over time in respect of the
+due date that can be set either automatically or manually when a ticket comes
+in, and can send notifications for these tickets as they become closer to due
+(PriorityAsString), or allow for the scale to be non-numerical, i.e. low,
+medium, high, or critical.
+
+This search criterion is most useful to obtain a group of tickets, rather than
+one specific ticket. For example, one might be searching for all tickets owned
+by user X with priority 50, or maybe all tickets with requestor matching
+ at google.com with priority 75.

-----------------------------------------------------------------------