[Rt-commit] rt branch, 4.4/query-builder-documentation, repushed

Dustin Graves dustin at bestpractical.com
Thu Oct 29 11:52:47 EDT 2015


The branch 4.4/query-builder-documentation was deleted and repushed:
       was 1c48f1e8269c9679f45853f6492d3da683678310
       now b8bd7921b1af63a6d76ec89e3263bc2861a55324

1:  1c48f1e ! 1:  b8bd792 Documentation for query builder
    @@ -1,6 +1,6 @@
     Author: Dustin Graves <dustin at bestpractical.com>
     
    -    add pod format version of Query Builder Documentation
    +    Documentation for query builder
     
     diff --git a/docs/dashboards_reporting.pod b/docs/dashboards_reporting.pod
     new file mode 100644
    @@ -143,9 +143,11 @@
     +=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>]
    ++=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.
    @@ -208,10 +210,286 @@
     +=cut
     +
     
    -diff --git a/docs/definitions.pod b/docs/definitions.pod
    +diff --git a/docs/images/added-terms.png b/docs/images/added-terms.png
    +new file mode 100644
    +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
    +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
    +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
    +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
    +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
    +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
    +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
    +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
    +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
    +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
    +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
    +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
    +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
    +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
    +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
    +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
    +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
     --- /dev/null
    -+++ b/docs/definitions.pod
    ++++ b/docs/query_builder.pod
    +@@
    ++=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> 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
    +--- /dev/null
    ++++ b/docs/subscriptions_feeds.pod
    +@@
    ++=pod
    ++
    ++For directions on how to build a dashboard from saved searches, please see
    ++Dashboards & Reporting 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
    +--- /dev/null
    ++++ b/docs/ticket_metadata.pod
     @@
     +=head1 Basic Terms
     +
    @@ -276,7 +554,7 @@
     +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? 
    ++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
    @@ -286,13 +564,13 @@
     +
     +=head2 Requestor Email Address/Requestor RealName, etc..
     +
    -+Each of these titles, or roles  (Requestor, Cc, Admin Cc, Watcher, Owner, Queue
    ++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. 
    ++her using it, and so on and so forth for other data items per user.
     +
     +=head2 Groups
     +
    @@ -316,7 +594,7 @@
     +Several of these terms - Created, Started, and Resolved - are self explanatory.
     +Let's cover a few that are less obvious.
     +
    -+=head2 Last Contacted 
    ++=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
    @@ -344,7 +622,7 @@
     +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 
    ++Below are the definitions of each sort of
     +relationship and how one in particular may work with others that complement it.
     +
     +=head2 Child
    @@ -352,7 +630,7 @@
     +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). 
    ++will update itself with the opposite relationship).
     +
     +=head2 Parent
     +
    @@ -423,7 +701,7 @@
     +=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? 
    ++on the ticket you're looking for. Is it a Master Agreement? Summary? Notes?
     +
     +=head2 Priority
     +
    @@ -441,273 +719,3 @@
     +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.
    -
    -diff --git a/docs/images/added-terms.png b/docs/images/added-terms.png
    -new file mode 100644
    -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
    -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
    -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
    -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
    -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
    -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
    -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
    -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
    -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
    -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
    -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
    -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
    -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
    -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
    -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
    -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
    -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
    ---- /dev/null
    -+++ b/docs/query_builder.pod
    -@@
    -+=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 & Reports> 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 & Display Columns"
    -+src="images/sorting-display-columns.png">
    -+
    -+=for :text [Sorting & Display Columns F<docs/images/sorting-display-columns.png>]
    -+
    -+=for :man [Sorting & 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
    ---- /dev/null
    -+++ b/docs/subscriptions_feeds.pod
    -@@
    -+=pod
    -+
    -+For directions on how to build a dashboard from saved searches, please see
    -+Dashboards & Reporting 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
    -+



More information about the rt-commit mailing list