Fields in ST

Documentation copied from https://cs.uwaterloo.ca/cscf/internal/ST/debug/doc/fields/ . The proposed situation in campus RT will be recorded in BOLDCAPS with comments below with bullet-points. See also STToRTInvestigationChangeRequests , which will have our queue-specific (CSCF and MFCF) change requests for IST.

"Account Number" Field

The "Account Number" field in a work request identifies a UW account number to be used to pay for any parts or equipment needed for the requested work.

When specifying this field in a customized sort or display, use the name "account_number".

CSCF: IGNORE: NOT USED
MFCF: add custom field

"Admin CC" Field

The "Admin CC" field in a service record identifies who wishes to monitor the work, by receiving the same generated email that the owner does, and by having the same access to the record that the owner does. This is typically someone in a supervisory or management role.

When specifying this field in a customized sort or display, the name "admin_cc" can be used.

BUILT IN

"Assigned By" Field

The "Assigned By" field in a service record identifies the person who assigned the work before the record was made. In practice, this was used only for processing problem reports submitted via newsgroups, which is a deprecated practice.

When specifying this field in a customized sort or display, use the name "assigned_by".

IGNORE: NOT USED

"Audited By" Field

The "Audited By" field in a service record identifies the person who audited the work before the record was made. In practice, this was used only for processing problem reports submitted via newsgroups which is a deprecated practice.

When specifying this field in a customized sort or display, use the name "audited_by".

IGNORE: NOT USED

"CC" Field

The "CC" field in a service record contains the id's of those who should receive email any time the requesters do, while not being formally considered as requesters. It can be handy when submitting work on the behalf of someone else.

When specifying this field in a customized sort or display, use the name "cc".

BUILT IN

"Cost Estimate" Field

The "Cost Estimate" field contains an estimate of the resources (time and/or money) needed to complete an item. The primary purpose is to facilitate planning (the spending of time and money).

Costs are expressed as one or more of

A rate can be one of "day", "week", "month", "term" or "year".

If the monetary cost of work isn't yet known, other than that money will have to be found and spent, use "$?". In general, if the cost is uncertain, a "?" can be appended. Costs can use units of K to represent $1000. Comments may be added between cost estimates by surrounding them in parentheses.

Some examples are:

$1.1K (purchase) $100/year (maintenance)

as the comments say, this is a $1100 one-time cost, and $100/year thereafter.

$15K 20h 20%

is $15000 one-time cost, 20 hours of staff time, provided as 20% of an FTE. So that's expected to take a little more than 14 work days (20 / 20% / 7).

At one time, once the (financial) spending had been approved, and financial administration informed, the cost estimate was removed from this field, quite likely by financial administration. That is no longer the case (at least in CS).

There are no separate fields to record the various subsequent intermediate states money can be in. That may change, if some experiments using the keywords field prove to be useful.

The display of this field in the item display or update page may include an estimate of the minimum time rate required or the time to be taken, when enough information is supplied for time estimates to be made.

When specifying this field in a customized sort or display, any of the names "cost_estimate", "Cost Estimate" or "$?" (for terse output) can be used.

CSCF: Custom Field

• use this extensively for budget planning and tracking, expense management, and expenditure authorization.
• Summarizing dollar amounts: built in to Charts tab visible in search-results
• Time estimates are default field built into RT

MFCF: IGNORE

"Date Due" Field

The "Date Due" field contains a date recording an agreed upon date and time for the completion of the work.

When a date without a time is entered, the time is set to close to the end of the business day, to provide as much flexibility as possible in meeting the due date while still being able to claim that the work was completed on the specified day. The current default is 16:00 (4PM), given that usual business hours are 8:30\x{2192}16:30.

In CS, the due date is intended to never be exceeded; overdue should never happen. Instead, when it becomes clear that a due date will likely not be met, a new due date should be negotiated with the requester of the work. Ideally, this should happen well in advance of the due date. If an agreement can't be reached, the due date should be removed.

The display of this field in the item display or update page may include an estimate of the earliest possible due date made when enough information is supplied for time estimates to be made.

The Due field can be used to express the due date as a duration.

When specifying this field in a customized sort or display, any of the names "date_due", "Date Due" or "Due Date" can be used.

BUILT IN

"Date Start" Field

The "date start" field contains a date with multiple related uses. It can range from a rigorous start time used in worked planning, to a reminder of when attention to an item should resume.

The display of this field in the item display or update page may include an estimate of the latest possible start date, when enough information is supplied for time estimates to be made.

The Starts field can be used to express the start date as a duration.

When specifying this field in a customized sort or display, any of the names "date_start", "Date Start" or "Start Date" can be used.

BUILT IN

"Group" Field

The "Group" field in the Create Request form describes which part of the faculty is requesting assistance. These are the departments and schools within the faculty.

A common concern of those who pay for the work is whether each group is receiving their proper share of available support resources. So we're obliged to ask this question.

By default, the form looks in the UW Directory to find your department, so you almost never have to fill this in.

When specifying this field in a customized sort or display, any of the names "department", "Department", "Dept" (for terse output), or "Unit" (for terse output) can be used.

CSCF: IGNORE (?)
MFCF: add custom field

"Barcode" Field

The "barcode" field in a service record identifies the marking on the associated equipment as used in an inventory system. The general form is 2 letters followed by 6 digits. CSCF's system is found at https://cs.uwaterloo.ca/cscf/internal/inventory/. MFCF's is found at https://www.math.uwaterloo.ca/inventory/login.php.

When specifying this field in a customized sort or display, use the name "equip_barcode".

ADD CUSTOM FIELD - linked to inventory URL

"Machine Name" Field

The "Machine Name" field in the Create Request form names the machine that needs to be fixed. The answer is usually obvious. Although, this being a comparatively new policy, it's easy to imagine that situations not accounted for will arise.

Although the machine name is often found in the problem description, it sometimes isn't, so this field is a reminder that it's needed information.

In principle, all work is paid for. The faculty have agreed that MFCF support is purchased for machines, not people. So please do your best. Since we're not allowed to work on unsupported machines, we'll be forced to find out the machine name ourselves, which just slows the work.

Names are recorded as relative to "uwaterloo.ca". So there is no need to enter "MyMachine.math.uwaterloo.ca"; "MyMachine.math" is fine, and how the name will be displayed.

In general, only names that can be found in DNS (the Internet Domain Naming System) are accepted. In the obscure case of needing to specify a name that no longer exists, enter as fully qualified, ending in a ".". E.g. "doesnt.exist.uwaterloo.ca" won't be accepted, while "doesnt.exist.uwaterloo.ca." will be accepted.

When specifying this field in a customized sort or display, any of the names "equip_name", "Hostname" or "MachineName" can be used.

ADD CUSTOM FIELD and look up support status in inventory

"File" Field

The "File" field is a pathname of a file (or directory) containing information related to the request. When empty, it isn't displayed. To set it, it must first be selected from the "Can be set" section of the Update Request form.

The pathname can be any valid path.

Access control on the files should be commensurate with that on the corresponding ST item. I.e. typically no general read permission.

In practice, this is an unused field, as most use attachments to the email gateway as a way of associating files with service records, and that (unfortunately) places the files elsewhere.

When specifying this field in a customized sort or display, use the name "file".

IGNORE: NOT USED

an "ID"

To address the requirement of dealing with both email addresses (if only because there is an email gateway), and permissions for people, people are identified via a canonicalized email address, that is also used to record characteristics and permissions. It is of the form

Userid@[]

The default domain is currently configured to be "uwaterloo.ca". Any sub-domain of that is presumed to use the same userids, and thus be in the default domain. That assumption isn't strictly true, however the exceptions are rare and benign enough that they're worth ignoring to reduce complexity.

The practical result of this is that people are represented by their WatIam userid, and others, typically vendors, or those uW people who have a special email address, e.g. (as of 2012) addresses of the form userid@iqc.ca, are represented by their email address.

Since an ID is used to generate an email address, by appending the default domain, canonicalization doesn't happen if WatIam doesn't record an email address for a userid. As a bonus, WatIam will (also) be searched for the "friendly" email address, which will be replaced by the userid.

In fields that have IDs as values, e.g. requestors, responsible, and owner, canonicalization happens during data entry. Canonicalization also happens at various other times to compensate for as yet un-canonicalized data. Existing data may eventually be canonicalized in place.

"Other IDs" Field

The "Other IDs" field records the "ID" of the problem in other work reporting/tracking systems, or in related information sources. A common example is a reference to IST's RT system, e.g. of the form

[UW-RT #69899]

And there are other references that can appear in this field.

The intent is that, where relevant, it be the text one ought to include in a Subject line when communicating via email with other work tracking systems.

They can also appear in the Dependencies and See Also fields. That wasn't always the case, and not being able to do so was the primary reason for this field to exist. So this field isn't really necessary any more.

Since the IDs can contain blanks, the values are comma separated in the Other IDs field.

When specifying this field in a customized sort or display, use the name "id_other".

Custom Field (to record PR, PO, quote number, sales order number, vendor service request number...)

"importance" Field

The "importance" field in a work request is an indication of importance of the work. It's currently the number after the decimal point in the priority field, expressed in the range [0, 10). E.g. the "importance" in a priority of "4.82" is "8.2".

The smaller the number, the higher the importance. The default is 5.

When specifying this field in a customized sort or display, any of the names "importance" or "Importance" can be used.

BUILT IN: RANGE OF 0-99

"Keywords" Field

The "Keywords" field provides a place to record words and phrases that happen to be awkward or possibly misleading to include in the "Subject" field. The "Keywords" field is searched along with the "Subject" field (and several others) when an item search is done.

It's recommended to separate keywords by commas, as some day we might make use of hierarchical blank separated keyword phrases.

Some keywords with agreed upon specific meanings follow. For the CSCF version, some of these are subsumed by the Service and Component categories. See docs: https://cs.uwaterloo.ca/cscf/internal/ST/debug/doc/fields/keywords.html

BUILT IN

"Location" Field

The "Location" field in a service record identifies the physical location (typically a room number) of where the work is to be done, if any. For work on a single machine it's usually the room where the machine resides. Since the location is almost always associated with a machine, a warning is issued for an entered location that can't be found in the inventory system.

When specifying this field in a customized sort or display, use the name "location".

Custom Field: perhaps filled in this if the work location doesn't match the location reported by inventory barcode

"Owner" Field

The "Owner" field in a work request identifies who (or what) is doing the work to resolve the request. An owner is either a UW userid, or an e-mail address of another work tracking system, typically "request@ist".

This is distinct from who/whatever is responsible for the resolution of that work; that's recorded in the responsible field.

When there are multiple owners, the extra names in the list identify those who may be advising, or in fact doing part of the work best suited to their skills and availability. Regardless of their contribution, it's the first person/system in the list who is currently doing the work. That name may change over time.

When specifying this field in a customized sort or display, any of the names "owner" or "Owner" can be used.

BUILT IN

And add Custom role, named "Supporters", for the 2nd through nth owners, to help comply with RASI concept.

"Priority Class" Field

The "Priority Class" is that part of a record's priority that categorizes the service in general terms that affect overall priority. The possibilities are:

Emergency

An emergency causes other work to stop until it's resolved. So of course it's at the top of the queue. An emergency isn't expected to last very long. And there aren't (or at least shouldn't be) very many of them. An example would be the failure of a shared faculty server.

Current

These are what we're focusing on now. There shouldn't be very many per person. It's expected that there will be significant work done on these at least every week. Items with a status of "stalled" can contribute to a greater than expected number of current items. A stalled item is one for which we have to wait until work out of the direct control of the owner is completed.

Upcoming Requests

These are the work explicitly requested by faculty and their staff. The goal is to resolve all such work within 8 weeks. Work older than that will have an explanation (readable by the requester) of why it hasn't been completed. When a request is first submitted, it's added to this part of the queue, in a relative position influenced by the user-specified urgency, unless of course it's been called an emergency, in which case it's starts in the "emergency" part of the queue.

Upcoming Projects

These are work required by our ongoing commitments and future planning. It's intended to be fairly obvious why these have to be resolved; they aren't optional. As they can be justified, they're moved into the current projects list to be completed. As with Upcoming Requests, we expect all of these to be resolved; rather than remaining on the list forever.

Uncommitted

These describe work that we cannot (yet) commit to, due to unavailable resources. And they can also be work that would be nice to do, but can't (yet) be justified (to faculty). They're kept just in case there's time, and/or as a repository of ideas that might be relevant to future higher priority work.

When specifying this field in a customized sort or display, any of the names "priority_class" or "Priority Class" can be used.

CSCF: IGNORE (?)
MFCF: not so sure we want to drop this

• Further discussion: do we want to explicitly record Emergency/Current/Upcoming Request/Upcoming Project/Uncommitted as a separate custom field? Robyn and Daniel wonder if "priority 0-99" is sufficient, with conventions about highest are Emergencies, lowest is Uncommitted; and Requests could be any ticket whose requester is not in CSCF/MFCF - which Daniel believes could be done in a custom search.
• https://uwaterloo.ca/request-tracking-system/new-rt4/issue-solver-documentation#priority says: "How priority is used depends on each queue. For new queues, we hope to work with priorities of 1-5: highest priority is '1', while lowest is '5'." Daniel has asked Lisa if that's accurate.

• Is a custom search based on requester good enough for distinguishing requests from projects? (How would it distinguish between a ticket from Marek Stastna as MFCF Director for a project vs a ticket from Marek Stastna as AM prof for a request?)

• The priority class as implemented in ST is based on interpreting ranges of numbers. ST shows that interpretation by displaying section headers to separate the priority classes. Would we make RT do that? Or would we "just have to know" that certain numerical ranges belong to emergency, current, upcoming, etc.? "Just have to know" seems a bit too obscure.

• The priority class as implemented in ST also mixes two different concepts: the priority of what's being worked on (emergency, current, upcoming, uncommitted) and the constituency for whom the work is being done ("requests" from users vs. "projects" we've made internally). When a ticket is current, the distinction between request and project is obscured, and if it gets moved back to upcoming, one must read the history or infer from requester field whether it should move to upcoming request or upcoming project.

• Separate queues for user requests and internal projects would solve all these problems, making it obvious at all times which tickets are requests and which are projects, independently of priority, without needing custom searches or heuristics.

• Another way to solve it more cleanly would be to add a custom field that is simply a flag for request vs project. No separate queue needed.

"Priority" Field

SEE "Priority Class" AND "Importance" ABOVE

"Private Content" Field

The "Private Content" field in the Create Request form indicates that the nature of the requested work should not be made public.

It's already the case that the detailed problem description, ongoing comments, the record of changes, and a few other potentially sensitive things are private ('account number' and 'signing authority'). Marking an item as private adds the subject, summary and the cost estimate to the list of private fields.

See docs: https://cs.uwaterloo.ca/cscf/internal/ST/debug/doc/fields/private.html

IGNORE (?)

• Option to add a custom field to contain client-invisible content

"Type of Work" Field

The "Type of Work" field in the Create Request form describes the general nature of the work to be done.

By specifying this, the form can add extra fields that may be needed. For example, work classified as "hardware" may need extra information about the hardware, and a financial services account number to be used to buy replacement parts. It's also useful in directing the work to the most appropriate people.

When specifying this field in a customized sort or display, any of the names "queue_id", "Queue", or "Q" (for terse output) can be used.

IGNORE: UNUSED

references to other work tracking systems

Both the See Also and Dependencies fields contain references to other work items. While the (original) intent is that they refer to other items in this system, and thus be a simple number, they are sometimes used to refer to other systems. Current supported examples are references of the form:

Forms of reference for other systems can be added as needed.

When using other than simple numbers, the references should be separated by commas, to make it practical to recognize the separate references. This is necessary both for people reading the work items, and for the system itself so that it can build a searchable structure of all of the references.

There are a variety of older styles of references that are still accepted, primarily to avoid having to change them all. At some point, we can expect support for these will be removed, so please use only the documented formats above.

ADD CUSTOM FIELD for Other IDs

"Requesters" Field

The "Requesters" field, also called the "e-mail" field, contains the e-mail addresses of the people for whom the work is being done.

That is sometimes different than the person creating the request. So if you're submitting for someone else, please change the field to contain the address of the person for whom the work is being done. Your name will be automatically recorded as the author of the first transaction.

The field usually starts with one name, but multiple requests for the same work usually result in the requests being merged into a single request.

If a simple userid is provided, then it will be treated as an @uwaterloo.ca address if it's registered as such, otherwise it will be used as is, which means that it had better work on the WWW server on which ST is running. So, mail sent by ST for an item assigned to "accounts" (for example) will be to "accounts@cs" if the cs.uwaterloo.ca version sends it, and to "accounts@math" if the www.math.uwaterloo.ca version sends it.

When specifying this field in a customized sort or display, any of the names "requestors", "Requestor" or "Req." can be used.

BUILT IN

"Responsible" Field

The "Responsible" field in a work request identifies the single entity that is responsible for resolving the request. It is either a UW userid, or an e-mail address of another work tracking system, typically "request@ist".

This is potentially distinct from the owners of a request, who are responsible for doing the actual work. It is usually the person who the requesters of the work have personal contact with.

The default for the "Responsible" field is the first name in the list of owners that has permission to modify requests, if any of them do. Otherwise it's just the first name in the list.

When specifying this field in a customized sort or display, any of the names "responsible" or "Responsible" can be used.

Custom role, named "Accountable", to help comply with RASI concept.

"See Also" Field

The "See Also" field is a handy way of grouping related work requests, by serial numbers (just the numbers, no text). E.g. sometimes two requests really aren't the same thing, but the outcome of one might affect the other. Or while completing work for a (client) request, followon work is determined that doesn't affect the completion of this work.

It's usually the case that if a request refers to another, that request refers to the original.

To be specific about whether a related request must be done first, use the "Dependencies" field.

Preceding the list is one line for each item, in the same format as used by the dependencies display. Unlike dependencies, a complete tree is not displayed, as it tends to be annoying large.

It's also possible to refer to items in some other systems, although no attempt is made to determine and display any details about them.

When specifying this field in a customized sort or display, use the name "see_also".

BUILT IN

Sponsors / "Activity" Field

The "activity" field in the Create Request form describes which of the fundamental university activities the work supports; i.e. Research, Teaching, or Administration.

Those paying for the work are concerned about where support resources are being allocated. So, we're obliged to ask this question.

- see https://cs.uwaterloo.ca/cscf/internal/ST/debug/doc/fields/sponsors.html
CSCF and MFCF: add custom field

"Status" Field

The "status" field in the Update Request form describes the state of completion of an item. If work is still ongoing, the status is one of:

If work has been completed, the status is one of:

When specifying this field in a customized sort or display, any of the names "status" or "Status" can be used.

BUILT IN

• WITH DIFFERENT VALUES: New, Open, Stalled, Resolved, Rejected, Deleted

Subject Field

(undocumented)

BUILT IN

"Subscription Code" Field

A "Subscription Code" identifies which source of (research) funds is supporting some work. The general form of a CSCF subscription code is

sc-name

where name identifies the person (uwuserid) or group funding the work.

Currently valid codes may be found via the CSCF Subscriptions System.

Information about graduate student supervisors, and research visitor sponsors, useful in deducing subscription codes, is usually found at CS Office Assignments.

CUSTOM FIELD FOR CSCF QUEUES

• will be linked to subscription database URLs

"Summary" Field

The "Summary" of a service record is intended to be a terse description of the highlights of progress and problems, focusing on what remains to be done. Ideally the reader shouldn't have to consult all of the transactions and from that attempt to deduce what remains to be done, and what the fundamental problems are.

When work is recorded as stalled, the reason for that should be mentioned in the Summary. When work has become overdue, any problems that caused should be documented as well.

Estimated time to completion can be recorded as well, if time worked isn't being tracked. If work time is tracked, then the total time estimate is better placed in the cost estimate field.

An example of a style that's been used is timestamped single sentence descriptions of highlights, e.g.

2003/09/15: documentation remains.

2003/09/15: setup for Math hosts not done.

2003/10/14: inquired.

2003/11/06: lowered in priority; other work competing.

2003/12/18: other work still competing.

When specifying this field in a customized sort or display, any of the names "summary" or "Summary" can be used.

CUSTOM FIELD

"Theme" Field

The "Theme" field provides a place to record words and phrases that can be used to categorize work items in a useful way. It implements hierarchical keywords, which can be referenced by fieldnames. The hierarchical keywords look just like pathnames, e.g. /service/student/graphics. The fieldname "/service" would then have the value "student/graphics". This facility is intended to be useful in experimental categorizations, on the assumption that such use may eventually be moved to new database fields.

When specifying this field in a customized sort or display, the name "theme" can be used.

IGNORE: NOT USED

"Time Added" Field

(undocumented)

BUILT IN: add either minutes or hours

"Urgency" Field

The "Urgency" field in the Create Request form provides an indication of how urgent the request is to the person for whom the work is being done. It is used to determine a rough starting position for the work in the "Upcoming Projects" part of the work queue, unless of course it's an "Emergency", in which case it's added to the "Emergency" section at the top of the queue.

When specifying this field in a customized sort or display, any of the names "urgency", "Urgency" or "Urg" (for terse output) can be used.

CSCF: IGNORE:NOT USED
MFCF: may create custom form for users to specify due-date and urgency, which could alter the priority and due-date fields