Service Tracking - The "RunOn Sentence"

The RunOn Sentence is used to generate potentially non-trivial queries of our service tracking data. It's called the "RunOn Sentence" because it reads like a very long sentence.

Ideally it should be self-explanatory. However there are a few details that aren't obvious.

Table of Contents

Searching

The "that match" input box (around line 10) specifies text to search for, in these fields:

Serial Number   Other IDs
Subject
Keywords   Theme
Service   Component   Advancement
Requesters   CC   Owner   Responsible
Machine Name
Package

The input is treated as a single string (including blanks), unless a "fulltext" search is done, as described below.

Fulltext Search — WARNING

The "Fulltext" selection causes the search specified in the preceding box, right after "that match" near the end of the Sentence, to examine the comments (in the display of "transactions") to be searched, in addition to the usual fields. The catch is that it also changes the syntax of the search! Without it, the search text is just that. With it, there's a non-trivial syntax that can be used.

The most common pitfall is that punctuation matters, separating words. So a search for grad-pc.math will look for all records that match grad OR pc OR math. That's a lot of matches. It can be avoided by quoting the search string, so search instead for "grad-pc.math".

Record "subject" and "summary" fields, as well as transaction comments, are searched, using the "fulltext" syntax. The usual fields are searched as well, however the "fulltext" syntax handled is just a common subset of the complete syntax. It will handle a leading "-", leading "+", and a trailing "*", and double quoting words to search for a single string.

A fulltext search is for words, not for substrings. So looking for "full" won't find "fulltext" as a separate word. Looking for "fulltext" or "full*" will match the word "fulltext".

A fulltext search is fuzzy. If you ask to look for the words "Santa" and "Claus", it will find records with either of those words, unless a leading "+" is used. That's not the case for the search of the usual search fields; both words would have to be present to match, regardless of whether a leading "+" was used.

Specific Searches

The Sentence can't do everything one might imagine. However for those who understand the internal database schema, and basic SQL, it's possible to use a feature of the WWW CGI which allows an SQL "where clause" to be specified as the search. This is done by prefixing the search with "EXPR:". It's this feature that the Sentence itself uses to implement some of the "about" selections, based upon knowing some of the informal conventions used in the "keywords" and "subject" fields. It's most useful when one wishes to search a specific field, rather than the default set. E.g. to search just the "keywords" field for the word "MyKeyword", search text like:

EXPR: keywords like '%MyKeyword%'
or more precisely
EXPR: keywords rlike '[[:<:]]MyKeyword[[:>:]]'
could be used.

Organization Specific Behaviour

It attempts to deduce whether it's running on an MFCF WWW server or a CSCF WWW server. That affects the

Exceptions to Set Intersection

The resulting selection is usually the intersection of all of the constraints that are selected.

The initial "details of" selection is not considered a selection constraint. So one could ask to see the contributions of Larry to all of the items worked on by Curly, whether or not Larry worked on them. Whether it would be more useful to avoid items for which the details were an empty set hasn't been determined.

For a few of the cases where set intersection produces less than desirable results, there is a different interpretation, as follows.

When the action in the second line is Worked On and the action in the third line is Worked On By, e.g.

Select a list of
Requests Worked On Today
Worked On By Larry
...
then instead of intersecting the set of requests worked on (by anyone) today with the set of requests Larry has ever worked on, it selects the requests that Larry has worked on today. I.e. it treats it as:
Select a list of
Requests Worked On Today by Larry
...
which is almost always what one wants.

A similar thing is done for active and Acted On By, and Created and Created By.

Specifying Which Fields to Sort/Group By

The menu item near the bottom of the Sentence which starts with sorted and determines sorting and grouping of the result. Commonly specified fields for sorting appear in the menu by default. If you want to add to the menu (until it's reloaded), select the last menu item, titled *Customize*. That changes the menu to a text box where a new fieldname can be added. A comma separated list of fieldnames is accepted. There is a syntax for specifying fields which allows sort order to be specified.

Once the change is made, the display reverts to a drop-down menu, with the addition, selected as the default. For most (all?) browsers, a text field is considered changed when a return is entered.

The initial menu items are, in some cases, descriptive phrases which are converted to the appropriate fieldnames when the form is submitted. Additions to the menu need to be valid fieldnames to work, the descriptive phrases won't work.

After the selected records are sorted as specified, they are sorted by Priority, and Effective Due.

Group Titles with Optional Content

When dealing with a large query result, it is sometimes easier to start with the group titles, and add the content just for those sections of interest. The phrase (on the line near the end beginning with showing) that defaults to with records always visible can be changed to with records Hidden to Start. That causes just the group titles to be displayed, with a count of items in the group appended to the title. Double-clicking a title causes the associated records to appear below it (doing it again causes them to vanish). The selection with records Hideable is similar to the default display, with the addition of the number of items to the group titles, and the ability to double-click a title to cause the associated records to disappear (or reappear). This behaviour may become the default.

Avoiding the Group Titles

Should you not want the sorted records to be grouped and titled, select Not Grouped rather than group on the sort specification line. The sorting still occurs, the group titles are suppressed.

If you want to avoid the group titles for just some of the sort fields, specify a precision of "none" for them (by adding a trailing "-none" to the customized specification as described above). This only makes sense for trailing fields (results will be goofy if used otherwise). For example, a specification of lead-userid, date_acted-none will sort and group by userid of the lead owner, and then within each grouping, sort by date_acted.

An Exploded Sort

Instead of sorted normally one can specify Using an Exploded Sort. Doing so has the effect of duplicating records that have multiple values for the selected sort fields, grouping by each of the values in turn. For example, if records were sorted by "owners", and the selected records were:

Curly Moe
# Owner Subject
1 Curly Moe Play a trick on Larry ?

Larry Curly

# Owner Subject
2 Larry Curly Play a trick on Moe ?
then specifying an Exploded sort would result in:
Curly
# Owner Subject
1 Curly Moe Play a trick on Larry ?
2 Larry Curly Play a trick on Moe ?
Larry
# Owner Subject
2 Larry Curly Play a trick on Moe ?
Moe
# Owner Subject
1 Curly Moe Play a trick on Larry ?

Specifying Which Fields to Display

Heuristics applied to the choices made in the Sentence are used to determine which fields to display. There names are listed on the line near the end of the sentence which says displaying these fields. The names of the fields can be edited, by adding fields, and reordering them. The names must be comma-separated, as some valid names contain blanks.

The Sentence will add fields it deems necessary every time any of the choices made in the Sentence are changed. It never deletes a field that it has added. It will add back a field you delete, unless it's done as the last step before submitting the Sentence for processing, via the Select button at the beginning, or the and then display it button at the end.

The "depth" field is special in that when it is immediately before the "subject" field, it will cause each subject to be indented by the depth of the item within a dependency tree, rather than displaying that depth itself. This only has an effect when dependencies are being displayed, via the selection following showing on the 3rd last line of the Sentence.

Valid Field Names

The commonly used fieldnames are documented. Some of the interesting field names are:

summary
Add this to the end of the field display list to see the item summaries.
cost_estimate+
Total the cost estimates for all of the dependencies of each selected item. Doing this while also selecting showing Children as Well provides sub-totals.
time_worked+
Total the time worked for all of the dependencies of each selected item. Doing this while also selecting showing Children as Well provides sub-totals.
depth
The depth field is defined only when displaying the relatives of selected items (see below). For each relative it's the distance from the root of the dependency tree (graph), represented by the corresponding number of "|" characters to provide a visual representation of the relationships.

A special case is specifying depth immediately before subject, in which case the depth is instead represented by indenting the subject accordingly.

Including Related Items

It can be handy to display items related to the selected items via the "dependencies" field. The line near the end of the Sentence starting with showing allows for 4 alternatives. In general, they result in the selected items being replaced by the selected relatives, although most of the selections also include the selected items.

Relatives are determined by dependencies only. The possibilities are

Children as Well
is the same dependency list shown in the update page for each selected item. This is handy when you know the parent item of interest, and wish to see more or different fields than the dependency display in the update page. If the parent item isn't readily known, then the "All Relatives" selection may be useful.
Ancestors as Well
shows a dependency path from the most distant parent item down to each selected item. For items that have multiple parents, multiple paths will be shown. This provides context for why an item exists.
All Relatives
displays the complete dependency tree(s) of the most distant parent(s) of each selected item. It would be used when it's easier to specify some member the dependency tree, rather than finding the parent and then using "Children as Well".
Just the Leaders
displays the most distant parent(s) of the each selected item. This is handy in providing an overview of work, as it suppresses the details of the dependencies. Note that it does not display selected items unless they are their own parent, i.e. are not a dependency of anything.

The resulting display isn't always simple when the relatives of multiple items are being displayed. The general approach is, for each initially selected item (via the rest of the Sentence), to display each set of relatives, with the first item in each set separated from the rest by a blank title. Sorting and grouping is done for that first item. The remaining relatives immediately follow, rather than being sorted/grouped with the rest of the result. It is assumed that it's more useful to keep relatives together than to spread them across the multiple groups. Otherwise there'd be no way to know what the relationships are.

As Part of a WWW Page

The Sentence can be made part of another WWW page by including this: 

<!--#set var="RT_VERSION" value="request_beta" -->
<!--#set var="RT_BASEURL" value="https://www.cs.uwaterloo.ca/cscf/internal/" -->
<!--#include virtual="/cscf/internal/rtDoc/workList/$RT_VERSION.shtml" -->
for the CSCF version, or this: 
<!--#set var="RT_VERSION" value="request_beta" -->
<!--#set var="RT_BASEURL" value="https://www.math.uwaterloo.ca/mfcf/help/rt/" -->
<!--#include virtual="/mfcf/help/rtDoc/workList/$RT_VERSION.shtml" -->
for the MFCF version. The request_beta can be just request for the production version, and request_debug for the debug version (not recommended).