ST - Internals - CGI Interface

Table of Contents

Access

The CGI can appear at a URL, provided that:

E.g. if

https://www.cs.uwaterloo.ca/cscf/internal/request_beta

invokes the CGI (by whatever means), then

https://www.cs.uwaterloo.ca/cscf/internal/request_beta/Queue

will invoke the "beta" version, with an action of "Queue", which will assume that

https://www.cs.uwaterloo.ca/cscf/internal/ST/beta/doc/

exists.

Actions

The actions to perform are determined either by the value of the CGI "display" variable, or by the action being appended to the CGI URL as described above. E.g.

https://.../request?display=WhatEver&Stuff

is equivalent to

https://.../request/WhatEver?Stuff

"display" overrides whatever action is appended (if any).

Not all actions are determined by "display", there are other variables that cause things to happen.

Possible actions are:

Welcome
displays selections suitable for client use, common to all organizations, followed by organization specific text.
Login
becoming obsolete.
Logout
becoming obsolete.
DisplayRequest
display a request, not for updating.
DisplayARequest
asks for the number of the request to display.
UpdateRequest
display a request to allow updating.
UpdateARequest
asks for the number of the request to display.
Queue
displays a selected subset of all records.
WorkForMe
like "Queue" above, with "search_sql" set to select items for which the invoker is a requestor, defaulting to open items, and "banner" defaulting appropriately, Used in pages describing how to see one's requests.
OwnersQueue
like "Queue" above, with "q_person" set to the userid and name of the invoker's queue to display, defaulting to open items. Both lead as owner or responsible are selected.
CreateRequest
create a request based upon CGI variables set if the form is submitted, else display the request creation form.
SetReply
compose a mail message, defaulting to the record requesters.
WorkFlow
displays a graph of records opening/closing over time.
Activity
a report of recent transactions. Looks unused.
Statistics
shows a cross product of two fields, defaulting to Sponsors vs Department. A debugging tool.
DumpAuth
shows information about current authentication. A debugging tool.
DumpEnv
shows environment provided to the CGI. A debugging tool.
None

or a serial number to display.

displayFirst, if present, is an action to be performed before what's actually in "display". It's handy when performing a subaction that should return to the action that caused it, e.g. a "Login".

displayNext, if present, is an action to be done first in the 2nd "display" step of the CGI, unlike the above which takes effect in the 1st action step. That's currently (2011/09) to allow the "DisplayRequest" rather than "UpdateRequest" to be the "display" step after "CreateRequest", even when it would recommend otherwise, to facilitate printing!

Action Parameters

Where Clause

An SQL "where clause" is used for both selecting records of interest, and transactions of interest. For the former, the "each_req" table is assumed, although an explicit reference to the "transactions" table will cause a join between the two tables. For transaction selection, the "transactions" table is assumed.

This "where clause" can also include a reference to functions that are evaluated in place before the where clause is used as SQL. Currently that's just

ST_previous_business_day()
the timestamp of the start (as in midnight) of the first business day before today. It takes weekends and UW holidays into account. Primarily for debugging purposes, it will accept an argument of the date to be considered as "today". It's a string argument, using the same date syntax as accepted elsewhere, e.g. ST_previous_business_day("2014-05-31").

Queue Display

This is the queue display subset of the CGI interface. At very least, add new CGI variables here. These work if the "display" CGI variable is set to "Queue", or equivalently, "/Queue" is appended to the URL.

banner: the "banner" (main heading) of the queue display.
The text to be used as the main heading of the queue display, as produced by the "search", and "search_sql" variables.
q_title: an optional title for the record display.
A title that will appear immediately after the beginning menu in a queue display. It is followed by another title, mentioning how many matches were found.

What Records to Select

search_sql: an SQL where clause fragment to constrain a queue display.
This is used when one wants to select a queue subset for display without preventing the use of the selectors of the standard search page. This is "and"ed with search constraints supplied by the regular search page or by the use of other CGI variables, such as "search". This defaults to "".
search: the text to search for, in various record fields.
This is used to constrain a queue display to the desired subset, e.g. as done by the standard search form. This defaults to "". Prepending with "EXPR: " causes it to be treated as an SQL where clause to be applied to the main record table. Some details may be found in ../request/page/RunOn.html
fulltext: determines the kind of text search to do.
If this is "yes", then a MySQL "fulltext" search will be done on comments and summaries, rather than on the usual record fields.
q_status: the status of the records to display.
This defaults to "Open" and "Stalled" and "recently done" records, unless the invoker is a potential item owner, in which case it defaults to "Open" and "Stalled" records. For a complete list of legal values, see "%status_info" in the source (in database/representation.pm).
q_person: who's queue to display.
This is the userid followed by name of the person who's queue is to be displayed. It only works if the action is "OwnersQueue" rather than "Queue".
unowned: constrain selections to unowned items.
If true ("1"), selections will be constrained to unowned items.
serial_num: the serial number of the item to select.
TypeOfWork: which "type" of work to constrain selections to.
This is typically one of: software, hardware, network, general, test. This parameter is mostly unused, as we default to a type of "general" for everything.
q_prio: the priority to select.
This is likely never used, as the current definition of priority is such one virtually always wants a range of values. It's an integer in the range [1000000, 6000000).
q_user: an SQL pattern matching requestors of work.
This is an SQL "like" pattern to match against the email addresses of the requesters of the work. In practice that means matching userids.
q_responsible: an SQL pattern matching the person responsible for the work.
This is an SQL "like" pattern to match against the email address of the person responsible for the work. In practice that means matching userids.
q_owner: an SQL pattern matching the people doing the work.
This is an SQL "like" pattern to match against the email addresses of those doing the work. In practice that means matching userids.
q_subject: an SQL pattern matching the subject of the work record.
This is an SQL "like" pattern to match against the subject of the work record.
q_equip_name: an SQL pattern matching the DNS name of the equipment involved.
This is an SQL "like" pattern to match against the DNS name of the equipment being worked on.

What Records to Display

After records are selected, each is replaced by related records determined by the following parameters. The result is the union of the sets described by the parameters. The default is to perform no replacement. Replacements are used to show all or parts of a "project".

q_display_project_depth: depth of display starting with the ultimate parent
Depth of dependency display starting with the ultimate parent of each selected item, defaulting to 0. Selected items are not included by default.
0 => no display
1 => display just the ultimate parents of selected items, if there are any; an item can be it's own parent (many are)
-1 => display ultimate parent(s) and all children; this can include more than the descendants of selected items
q_display_ancestors_depth: depth of display from an ancestor down
Depth of dependency display from an ancestor down to each selected item, defaulting to 0.
0 => include no ancestors
1 => include all immediate ancestors of selected items
-1 => include all ancestors of selected items
q_display_item_depth: depth of display starting with selected items
Depth of dependency display of the selected items, defaulting to 1, i.e. to just the selected items.
0 => don't include the selected items
1 => include the selected items
q_display_children_depth: depth of display starting with descendants of selected items
Depth of dependency display of the selected items, defaulting to 0.
0 => include no dependencies
1 => include the immediate children of the selected items
-1 => include all of children of the selected items
q_relatives_where_clause: a where clause to constrain selection of relatives.

An optional SQL where clause to constrain the selection of relatives specified by any of the q_display_*_depth parameters, as well as the relatives used to compute summed fields (e.g. "Last+").

It's typically used to apply similar constraints to relatives as were applied to the original record selections (e.g. only "open" records). It defaults to adding open requests, not in the "test queue", with one exception. When selecting related records when no relative selections have been specified (via q_*_depth), it defaults to no constraints. That's done to allow simple queries to work as expected, i.e. with no other constraints than the query, and summed fields to work as expected, i.e. to default to open dependencies.

These defaults, for the "status" and "queue_id" field, can be overridden by providing explicit alternatives. The most common of these is "status = status", which effectively removes the default for "status".

What Order to Display Records In

q_sort: the names of the columns to sort and group the queue display by.
It can be a comma separated list, or a null ('\0') separated list, the latter being the result of specifying the variable multiple times. See the field syntax that can be used to affect sort order. Records that have the same values for the specified sort fields, at the specified precision, are grouped by supplying a title containing those values. E.g. specifying
q_sort=date_created-year,date_acted-term
would sort by creation date, then date of last change. and then would group records by term within each year.

The sort fields do not affect the order of records related by the q_display_*_depth parameters above. A family of records remains together, following the "head" of the family, with an empty title.

q_reverse: the overall direction of the sort.
It is one of:
0 an ascending sort
1 a descending sort

It affects the sort order for all fields in q_sort.

What Transactions to Display

transaction_select
A where clause that acts on the transactions table to select which transactions to display. It should result in a number or "" (i.e. TRUE or FALSE). It defaults to all transactions for a record display, and no transactions for a queue display. It's used for these actions:
  • Queue
  • DisplayRequest
  • UpdateRequest
transaction_describe
The additional text to follow the "Transactions" heading to describe what the transaction_select parameter is selecting. It's used for the same set of actions.
oldest_transaction: to include in the queue display
The age (in seconds) of the oldest transaction to display, where age is measured via &date_last_worked(), or <0 if we want them all. This is deprecated in favour of the transaction_select parameter.
newest_transaction: to include in the queue display.
The age (in seconds) of the newest transaction to display, where age is measured via &date_last_worked(), or <0 if we want them all. This is deprecated in favour of the transaction_select parameter.
actor_displayed: userid to restrict transaction display
The userid to restrict transaction display to. An empty string is treated as undefined, i.e. doesn't restrict the display. This is deprecated in favour of the transaction_select parameter.
transaction_difference_select
A where clause to select the transactions used to compute a history field (trailing "-" fieldname syntax, e.g. time_worked-). It should result in a number or "" (i.e. TRUE or FALSE). It defaults to all transactions for a record display, and no transactions for a queue display.

What Data to Display

q_columns: names of the columns to display.
A comma separated list of column names. Many columns have multiple names, that affect the detail used in the column values. There are so many, that for now, the reader is referred to the %display_queue_column_info in lib/rt/ui/web/rtuser2.pm in the source.
q_exploded_sort: use an "exploded sort".
If "1", multi-valued (sort) fields are converted to multiple records with single-valued fields.

Titles for Grouping

q_title_depth: is the number of non-empty title values to use.
The number of non-empty title values to include in each title, starting the count with the first non-empty value. It defaults to not limiting values.
q_visibility: optionally show just titles, not records.
By default, each group of sorted records are titled. If q_visibility is "visible", then it becomes possible to double-click a title to cause the associated records to not be displayed. A value of "hidden" displays only the titles initially; double-clicking causes the associated records to be displayed. In either case, double-clicking a title alternates between displaying and not displaying records.
q_fitg: provide titles for groups that have no members.
q_fitg is the number of sort/group fields for which all "possible" values should be displayed, even when there are no selected records with those values. Use this to provide context, to show what's not being done, in addition to what is. Warning: a value of more than 1 can produce a lot of titles, especially if q_title_depth isn't set. A value of 2 with a title_depth of 1 is feasible. A value of 3 is a bad idea.
q_title_fields: the names of the fields to total across each sort group.
A standard field list, to determine which fields will be totaled across each sort group, and displayed following the sort group titles. Grand totals are also displayed before the first title. The common choice is "time_worked, cost_estimate".

Other Effects

There are parameters that generally modify the behaviour of multiple actions.

Printable: makes some pages more appropriate to print.
TRUE (not "" or "0") persuades non-update displays to avoid or reduce things not interesting to print, e.g. some information messages or the generic actions at the bottom of most pages.
verbosity: affects the "verbosity" of the form chosen to display data.
It is one of: "terse", "medium", "verbose". There is no guarantee that

The default verbosity depends upon the context of the data being displayed. E.g. titles are usually more verbose than column data.

tree_child_color: the color of dependencies in the queue display.
The HTML numeric color specification for the background color to use for items that are dependencies of others, i.e. have parents, are children in a dependency tree. E.g. tree_child_color="%23DDFFDD" results in a light green background. Note that the text is "#DDFFDD" however the "#" is excluded from URLs (see RFC 2396), so it must be escaped.

Debugging

ShowOnly: shows what would happen, without doing it.
TRUE (not "" or "0") causes some actions (at least CreateRequest and UpdateRequest) to display what they would do, without doing it.
PermsMax: reduce permissions to facilitate testing.,
Requests a reduction in permissions. It is a comma separated list of reductions, each of the form
<action>: <perm>
For example:
reply: 3, summary: 3, history: 3 manipulate: 0, admin: 0
would reduce the permissions of a computing staff member to those typically used for a consultant or co-op student. See the schema description of the queue_acl table for details of possible values. Attempts to increase permissions are silently ignored.

Request Creation and Update

The actions CreateRequest and UpdateRequest both use variables of the form

ReqNewField_fieldname
for providing defaults and/or new values for form fields that happen to directly correspond to (internal) fieldnames. E.g. setting
ReqNewField_owner=Larry
will cause the "owner" field to be displayed in the request creation form with a default of "Larry", or set to "Larry" when invoking the request update action. There are some form values that aren't identical to internal database values, which (therefore) don't use names of the above form.

Claim: invoker wants the item
when set to one or more of a comma separated list of "owner", "responsible", and "requestors" will cause the corresponding fields to default to the invoker. It exists only avoid having to wire in userids to things like
ReqNewField_owner=MyUserid
Submit: actions for the request creation form
Possible values are: