=head1 Introduction

The Ticket 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.

Newer RT versions also include a Transaction query builder, which allows
you to search for specific changes or types of changes in tickets.

The Query Builder is the heart of reporting in RT, which is covered in the
L<Dashboard and Reports|docs/dashboards_reporting.pod> document.

=head1 Basic Ticket Searches

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>]

RT also has two meta-statuses, 'active' and 'inactive'. By selecting either of
these from the status dropdown of the query builder, your search will include
tickets in all active or inactive statuses without adding each individual
status name.

The sets of active and inactive statuses for a queue are defined by the
associated lifecycle. Active tickets are those listed for the 'active' and
'initial' configurations. Inactive tickets are those defined as 'inactive'.
For the default RT lifecycle, for example, the active statuses are new, open,
and stalled, and the inactive statuses are resolved, rejected and deleted. See
F<docs/customizing/lifecycles.pod> for more information.

After you select some criteria, you can click either Add These Terms to start
to build your query.

=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 you have 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?

You can continue to modify and refine your search, adding or removing criteria.
For example, to see all queues and not just the RT queue, you click that part
of the query and click 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>]

The updated search has just the remaining criteria:

=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>]

To run the search, click either 'Add these terms and Search', 'Update format
and Search' at the very bottom, or Show Results in the submenu near the top.

=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>]

=head1 Customizing Search Result Fields

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.

=head1 Custom Field Searches

Users often add custom fields to tickets to capture additional important information.
All of these fields can be searched in the Query Builder as well. Global custom fields
will show up by default when you start a search. To see custom fields that are applied
to individual queues, first add the queue to your search and you'll then see the
custom fields appear in the bottom of the Add Criteria section.

For example, you might have a custom field named "Transport Type" with values
like "Car", "Bus" or "Train". You can easily build a search to show just tickets
with a Transport Type of Train for some time period by selecting those options
in the custom field entry.

=head2 Custom Field Searches and Null Values

There is a special case if you want to search for tickets with no value, called
a "Null" value, for a custom field. If you search for all tickets that
do not have Transport Type set to "Car", this results in a list of tickets
with Transport Type values of 'Bus', 'Train', and '(no value)'.

If what you intended was to show all tickets that have a value and that value
is not "Car", you can clarify your query to get the correct results. To filter
out the empty values, add the following to your search query:

    AND CF.{'Transport Type'} IS NOT NULL

=head1 Transaction Query Builder

Similar to the Ticket Query Builder, the Transaction Query Builder provides an
interface to search for individual transactions. Transactions are all of the
changes made to a ticket through its life. Each of the entries displayed in the
ticket history at the bottom of the ticket display page is a transaction.

In some cases, RT users looking for a particular reply on a ticket will
search in their email client rather than in RT because they will remenber
getting the email with the information they need. On a busy ticket, it
can be a challenge to find the reply from Jane some time this week. The
Transaction Query Builder now makes that sort of search easy.

=head2 Basic Transaction Searches

In the example above, suppose you remember getting a reply from Jane in email
on a ticket and you know it was in the last week. But it's been a busy week
and Jane is on a bunch of active tickets, so you're not sure where to start.
With the Transaction Query Builder, you can easily create a search to show all
replies from Jane.

First find Creator, select "is", and type Jane's username. The "Creator" of a
transaction is always the person who made the change. For a reply, by email or
in RT itself, the person who replied will be the Creator of the transaction.

Next, for Created select "after" and type "1 week ago". RT will then automatically
figure out the date 7 days ago and show you only results in the last 7 days.

Finally for Type select "is" and select "Correspond". Correspond is the name RT
users internally for all replies on a ticket.

Run the search and you'll see all replies from Jane on any tickets over the
last week. Note that you'll see all transactions you have rights to see, even
if you aren't a watcher and possibly didn't get an email originally.

=head2 Including Ticket Information

When searching for transactions, you can also add criteria about the types of
tickets the transactions should be on. In our example, we probably only want
to see active tickets, so in the bottom Ticket Fields section you can select
Status "is" and "Active". This will then filter out inactive statuses.

=head1 Learn More

To use the query builder to build and save reports, see
L<Dashboard and Reports|docs/dashboards_reporting.pod>. For definitions of
RT metadata, see L<Ticket Metadata|docs/ticket_metadata.pod>.

=cut
