Each work record is composed of (many) data fields. Most of the fields have names that are simple words, corresponding to data in a conventional database. Some have a special syntax to allow "summing" fields in related records, and some have a special syntax to allow experimentation with hierarchical field names.
The list of all field names is rather long. The WWW interface may eventually provide the list.
The term "external field names" is used to refer to the complete set of possible field names, being the union of database field names and their alternatives as described below.
The individual field descriptions describe alternate names for fields.
Some field names are just alternate names for fields to allow for shorter column headings in a queue listing, and/or more readable column headings. E.g. "#" is a name for the "serial_num" field, while "Date Worked" is the name of the "date_worked" field. Most, but not all, of them are dual case.
Some can also affect the verbosity of the display of the corresponding data.
E.g. Dept
might result in CS
,
while department
might result in Computer Science
.
Appending a "+" to a field name is a directive to "sum"
that field's value across the record and all,
or an appropriate subset, of each record's children.
The children
of an item are its dependencies,
and their dependencies, and so on.
In general, when selecting open items
only the open children will be selected for summing.
When not restricting a selection to just open items,
all the children of an item will be summed.
For arithmetic fields, the sum is arithmetic. For date fields, it's typically a range of dates. For durations, it's usually the sorted list of durations, from smallest to largest, with multiple equal durations being represented as N × duration rather than repeating duration N times. For lists, it's usually the union of values. For lists of words, it's usually the union of values, ordered from most to least frequent.
Every field can be summed.
However it doesn't make much sense for many of them.
E.g. asking for the sum of the subject
field isn't useful,
although it does work.
The most common fields to sum are
time_worked
and cost_estimate
.
Appending a "-" to a field name results in a summary of the history (of changes) of the field. The history is typically constrained by a time interval and, if relevant, to changes made by a specific person (or group of people).
For times (i.e. the Time Worked field) the history is expressed as the difference in times, followed by a summary of the changes. The terse summary is a parenthesized start and end value. The medium summary lists all of the changes. The verbose summary includes the date of when each change was made.
E.g. a group title in a queue listing might include
Time Worked-: 1:10 (0:20 -> 1:30)
meaning that before the start of the time period that the queue listing is about, the total Time Worked of the displayed items was 0:20, and the Time Worked during the period was 1:10, resulting in a total Time Worked of 1:30 by the end of the time period. A display that doesn't include the parenthesized times means that there was no time worked before the display period.
Field names of the form
field_name/restrictionhave values computed from the field_name field by selecting the words in the field value that begin with restriction followed by a '/' (or nothing). The computed value is what follows the restriction. For example, if the keywords field had the value
budget/now/10000 budget/later/9000then the field name keywords/budget would have the values now/10000 and later/9000.
If
/budget/now/10000 /budget/later/9000is preferred, then the field name keywords//budget would be needed to access the values.
The restriction is currently applied to the internal value of the field, so applying it to something other than fields that appear as words, e.g. "keywords", "theme", "service", "component", "advancement", will be futile. The internal form of the last 3 fields above can be seen by displaying them in terse verbosity (by using a fieldname syntax like "service!terse"). They look like relative pathnames, and so work well with the syntax.
The primary purpose of this syntax is to allow the introduction of artificial fields for purposes of experimentation, or temporary categorization needs. The result of the experimentation may result in the creation of new fields.
For historical reasons, the syntax /value1/value2/... is equivalent to theme/value1/value2/....