The Tracker conducts web-based support and development dialogues, organizing the flow and artifacts of the correspondence. This document presents a user-oriented overview.
Any number of distinct trackers can be created within a single Zope site. Each Tracker has its own administrator, with overriding configuration privileges including, among other things, the ability to designate specific supporters - tracker staff responsible for satisfying requests - and the mode by which site users are allowed to submit (request) and browse existing issues. In Open operating mode, trackers admit all Zope site users. In Dedicated mode, the tracker only admits browsing and requests from designated users.
Individual tracker dialogues are known as issues. An issue is basically a container for messages, known as items, between the issue requester and suporters. When submitting an issue, the requester selects traits which characterize it. The ranges of traits are configured by the tracker administrator, tailored for the tracker's subject domain.
See also the discussion about browsing the issue overview page, below.
The lifetime of a tracker issue proceeds in stages, from their initiation as requests at start to one of a variety of conclusions. These stages reflect the issue's current status with respect to attention from supporters:
| Stage | Due To Action | Description |
|---|---|---|
| Pending |
Issue Submission |
Awaiting supporter attention |
| Accepted |
Supporter Accept |
In-process - one or more supporter has claimed responsibility |
| Resolved |
Supporter Resolve |
Completed - these counts against ticket quota, if any. |
| Rejected |
Supporter Reject |
Concluded without resolution, does not count against any quota. (Requester can cancel only while their issue is in the 'pending' stage.) |
| Deferred |
Supporter Defer |
Put aside until whenever |
| Diverted |
Supporter Divert |
Subsumed into another issue |
An issue starts its life with submission by a member of the tracker's community. (Trackers can operate so they are open to all comers, or can be restricted to designated clients - see here for more details.) The issue can be submitted using the "Submit New Issue" tab in the tracker's web interface, or via email.
When submitting via the web, the requester selects trait values to characterize the issue.
When submitting via email, in addition to describing the issue, the requester uses leading lines followed by a blank line to specify "trait: value" pairs that further characterize the issue. (The requester then receives an email acknowledging receipt of the issue, and instructions for replying to that receipt if they wish to correct or revise any trait settings.)
The arrival of a new issue triggers email describing the issue to concerned supporters - those designated by the tracker as being concerned with the traits specified by the requester. There may be no traits sensitivity, in which case all supporters are notified, or a lot of sensitivity, for fine-grained routing of issues to particular supporters.
Once the issue is submitted it exists on the tracker in the pending stage, until one of the supporters accepts responsibility for the issue. The requester and supporters can followup to the issue, and others can subscribe to it, to be included in the notification loop. As long as the issue is in the pending stage, notices are sent to supporters, the requester, and subscribers, with routing as for new issue notification.
Followups can be submitted via the web interface, which we describe in detail below, or via email using the issue's emblem to uniquely identify it.
Correspondence in an issue is threaded, each item tracking the messages that it follows from, and followups to it. These threads can be viewed and traversed in the issue summary view and in the individual messages.
At any point a supporter can submit a message accepting the pending issue, claiming responsibility for it. They could also take other actions, even concluding the issue directly from the pending state. See the table for the complete set of available actions and their context.
When a supporter changes the issue stage from pending, relevant supporters are notified and then subsequent notifications are confined to the requester, subscribers/kibitzers, and the responsible supporter ("issue owner"). Multiple supporters can accept. Supporters can resign from an issue so long as at least one other supporter has accepted/is kibitzing the issue.
Eventually a supporter(s) completes the issue - by, eg, resolving or rejecting it, by diverting it to an already existing issue, or by deferring it indefinitely for later attention. The issue no longer shows up among the pending or accepted issues shown by the default browse/search. It can be reactivated, and parties to the issue can still correspond in it, but only gets attention when someone specifically seeks it out.
Tracker items convey issue correspondence and also are vehicles for actions affecting its stage. Actions that supporters take with respect to an issue - accepting responsibility for it, marking it resolved, combining it with another issue, etc. - are effected by submitting new items.
See also the discussion about browsing issue items, below.
There are many situations in a tracker where concise references are made to specific issues and items - often with links to the objects. The tracker has formalisms for presenting these references, so you can easily recognize them and unambiguously enter references between elements, where appropriate. These terms are known as tracker element emblems.
Issue and item emblems are presented with one or another kind of bracket pairs around the serial ID of the element.
| (234) | Issues are presented with the ID in parentheses. |
| [17] | Items have their IDs in square brackets. |
| TR(234)[17] | A full emblem includes the issue and item emblems adjacent and in that order, and may include the tracker abbreviation. |
| TR((234))[[17]] |
Privacy of an issue or item (whether or not the privacy excludes you) is indicated by doubling the respective brackets. If you are not privileged to view the element, then the emblem will not be an active link. |
| (234)[] |
In order for the tracker to recognize emblems you enter (as references, or in item title or description text), you must include both pairs of brackets, with no intervening spaces - use an empty pair of square brackets for the item number if you're referring to the issue as a whole. |
Interacting with trackers entails two primary kinds of activities:
At the top of every tracker page is a tab-style activity menu for the tracker element that you're viewing. (This tab arrangement will be familiar if you're acquainted with Zope's management interface.) The leftmost tab goes to the view of the element. Every view's tabs includes one for submitting a new issue. The selection of tabs within an element varies according to the role of the visitor - tracker staff see more tabs than the general public, offering supporter-specific functions, and in some places the tracker admin sees yet a few more.
You are browsing issues as soon as you enter a tracker - the browsing interface is actually a view into an ongoing search. The default search is shows currently active issues. You can adjust the search with the simple form at the bottom of the page, and toggle to an advanced form for more elaborate searching. (You can bookmark the results of your searching to preserve a search for later continuation.)
The top level view of the tracker - the entrance - is a combined browsing/searching view of the tracker's existing issues. From here, visitors can:
Submit New Issue tab at the top to, well, submit a
new issue.
The layout of the page, from top to bottom, consists of:
The issues overview table prents batches of brief entries for issues satisfying the current search criteria. (The default search excludes resolved and discarded issues, showing only currently active or pending ones. It also excludes private issues to which you are not a party.)
Each issues-overview entry has emblem links to the overview of each individual issue and to the
most recent message item in the issue. The issue links
are in the ID and Title fields, and the most-recent
message link is in the Last Msg field. (The Last Msg link is a
convenient shortcut for involved parties to continue the correspondence.)
Here's the scoop on all the ordinary fields:
ID (a link to the issue)
Title / Description, also a link to the issue.
Request
Last Msg, a link to the item.
Stage Traits Tracker staff see some additional fields.
Tracker searches restrict attention among the existing tracker issues.
Search results are those issues that satisfy all of the fields you've selected - effectively an 'and' across the selected fields. Fields in which you made no selection are ignored for that search, to the point where no selections at all yields all the viewable issues. The standard search you get on entering a tracker shows all issues in the 'pending' or 'accepted' stages - those not yet claimed by a supporter, or only claimed, not yet concluded.
The default search is fairly simple - you can do a text query over issue text content, plus a selection-based query over the issue stages. (Once again, tracker staff have a few additional options.)
Using an advanced search form, opened using a button in the simple search, and vice versa, you can restrict the search according to more particular issue characteristics, like date, requester, user-selected traits, and so forth. Both searches have similar controls. Here's how the different field selection types work:
and and
or for boolean searches.
The Issue Summary presents an overview of the history and specifics of an issue. It presents abbreviated versions of all the important correspondence in the issue. The summary has all the important characteristics of the items and the first several lines of the item descriptions. The tags for each entry are links to the specific item pages, which contain the full text of the messages, and also have the fors for posting followups.
There may be other, incidental correspondence in an issue - that is presented only to the requester and tracker staff, below the issue summary.You typically get to an issue summary either from the first links in the Issues Index table entries, or by appending the ID of the issue, after a '/' slash, on the URL for the tracker. Some other common avenues are links upwards from the items, which are "contained" by the issue summary, and cross-reference links from other tracker elements.
You use the issue summary entry link (for example, "Request[1]" to travel to individual items.
Issue Items represent individual messages and actions in an issue's life. The item view presents the specifics of the item, with a full rendering of the message it contains (as opposed to the excerpt included in the issue summary for the item).
For participants in the issue - the requester and relevant tracker staff - the item also includes a form for posting followups to the item, and a link to a form for submitting new items starting separate threads in the issue.
Items are commonly visited using links included in new-item email notifications, or via links from the issue summary or issues index. Items are contained by their issues, and their URLs are those of their issue with a '/' slash and the serial number of the item appended.
All tracker interaction is conducted with messages submitted via the web or via email. Notifications about new and overdue responses are posted to the issue and sent to the involved parties via email.
The tracker notifies all issue participants about new messages via email.
The notices include URLs for the item and any attachments or references included in the item, convenient in many contemporary mail readers for pointing your browser at these components. The notices include the item text as well as characterizing data like the submitter, issue traits, and so forth.
The initial notifications are sent to the requester and routed to supporters according to the traits the requester selected for the issue. When a supporter claims responsibility for an issue then the issue's requester and other relevant supporters are notified, but from then on the set of notice recipients is confined to the requester and the accepting supporter(s) - the issue owner(s).
(The tracker prototype does not currently accept incoming emails for issue correspondence.)
When you have an issue you'd like to register with a tracker you fill out
and submit the new issue form
or you send email to the tracker. (The form for this tracker is
located here. This form is reachable from the
Submit New Issue tab found at the top of every tracker page.)
The user submitting the issue becomes the issue requester. The requester receives notifications about new correspondence in the issue and, except when submitting from the anonymous user account, the requester can followup through the life of the issue.
(Submitting issues under the auspices of the anonymous user is discouraged, and sacrifices certain privileges that depend on confident identification of the issue requester. In particular, anonymous users cannot submit confidential issues, and they cannot followup in ensuing correspondence about the issue. They do receive email notifications of new messages from the supporters, if they register their email address in the space provided on the submit form - see below.)
Here are the details, proceeding through the fields on the form:Unless submitting as the anonymous user, the subject box is accompanied by a check-box for submitting a confidential issue - one which only you, as requester, and the tracker staff have view privileges. Reserve this for occasions when you really need privacy.
Issue requesters are identified by their user id (unless requesting using the anonymous account, which is discouraged - see above). The requester can specify an alternate address to be used within that issue. Followup forms have the same provision, so requesters can vary their email address over the course of an issue.
(The input boxes also provide the means to identify yourself when submitting from an anonymous user account - with the ensuing constraints mentioned above.)
Trackers are configured with sets of issue traits by which requesters characterize their issues within the subject domain of the tracker. Judicious trait choices can help ensure that your request gets the right attention - supporter notifications may be routed according to your trait choices, and people mining a tracker can use the traits to focus their searches.
This is where you spell out the details of your request. Find the balance between concise and complete. Provide enough information to inform your supporters without hiding the crucial bits in extraneous details.
The contents of this box will be appended to your description, separated by a newline. If you check the Retain as personal default check-box, the value you set will be filled in automatically in subsequent use of any tracker on the site.
This is a slot for linking to incidental resources relevant to your request. You include one entry per line. URLs and element emblems are recognized as such, and presented as html links in the issue. (The first reference plays a special role when diverting an issue. It must be the emblem for the target issue - the tracker uses it to do the bookkeeping to link the issues together.) The references you register are also included in a prominent place, as URLs, in the emailed notifications.
The is a pair of file-upload slots for including external materials - patches, image files, non text documents, whatever - within the request object. They use your browser's file upload capability.
Requesters and supporters conduct ongoing correspondence about issues, organized in correspondence threads. The crucial items are collected in the issue summary. This includes items like the initial request, the item in which a supporter accepts responsibility for the issue, and the eventual conclusion of it. Other correspondence - often incidental exchanges - is visible only to the requester and to tracker staff.
Note that only the issue requester and tracker staff can enter correspondence in an issue.
Parties to an issue and tracker staff followup to an item by visiting the item. There are many ways to get there, including:
Last Msg shortcut to get to the most recent item.
Most recent message shortcut located on the upper right
corner of the page.
When you followup to an item your new message follows the original in its correspondence thread. You can also start a new thread by using one of the "Start a New Thread" links, found in the issue summary and in the items.
The forms for submitting new items are similar to those for submitting new issues, with a few additions:
Plain
Note
Cancel - only until issue is accepted
Supporters can invoke several other actions with their issues - they should consult the support-specific help for details.
Most supporter actions are done through posting followups to an issue. The supporter chooses the particular action from among the "Action" radio buttons on the message submit form. The available choices are tailored to the visitor's role in the issue - see the table, below.
Among other things, the message action determines whether or not the item will be included in the issue summary. For regular (non-confidential) issues, the summary is visible to the general public. It includes synopses of all those messages whose actions change the stage of an issue, and also messages that were submitted with the "Note" action. "Plain" correspondence is not included in the summary, and is just between the supporters and requester.
See the topic concerning issue corresondence for more details about who receives what correspondence.
| Action | From/To Stage | Who? * | To Summary? | Purpose / Notes |
|---|---|---|---|---|
| Plain | Any No change |
Involved | No | Correspond with parties to issue / Not distinguished in issue summary |
| Accept | Pending, Deferred
Accepted |
Staff | Yes | Claim ownership of an issue / Other supporters exempted from further issue correspondence |
| Kibitz / Subscribe |
Pending, Deferred, Accepted
No change |
Anyone | No | Join in an issue / Only when not already involved |
| Resign | Any but pending No change |
Owners | No | Abandon ownership of issue you own / Not offered when not involved or only supporter |
| Note | Any No change |
Involved | Yes | Item for summary that doesn't affect stage |
| Resolve | Accepted, Pending Resolved |
Staff | Yes | Conclude issue satisfying requester / If accepted, only owners (acceptor or staff subscribers) can resolve |
| Reject | Accepted, Pending Rejected |
Staff | Yes | Dismiss issue without resolution / Same as note as for resolve |
| Defer | Accepted, Pending Deferred |
Staff | Yes | Table this issue until whenever / Same as resolve note |
| Reframe | Any No change |
Staff | No | Rephrase title/description and/or change traits / For when the requester wasn't quite clear or accurate |
| Divert | Any Diverted |
Staff | Yes | Include the subsuming issue as the first of the references / Same as resolve note |
(Occasionally supporters need to send messages that are not exposed the requester or to the public at large. This is done by checking the "Staff eyes only?" box (beside the message subject input field). You must also check the "don't-post-to-summary box, since summary items can't be private.)
The stage (and other issue state settings) can be forced using the entries on the issue's "Edit State" tab. Some state transitions are inhibited (by default, going to pending from any other stages).
The user creating the tracker has configuration and other special privileges in the tracker. (You can use the Zope management Security tab/local roles to transfer or share those privileges after the tracker is created, if necessary.)
Tracker configuration is a three-step process. The tracker owner is brought to it upon creating the tracker, and can reenter it at any time via the configuration tab (which only the tracker owner sees) at the top of the main tracker page.
Here is where you set the fundamental tracker operation settings, and you name the trait categories by which requesters qualify their issues.
This is where you enumerate a variety of tracker settings. This includes special member roles - identifying supporters, and, if the tracker is running in dedicated mode, clients - and issue trait values. (From here you can get to a form to specify user account's email and name settings, as well.)
This is where you associate specific supporters with specific issue trait values, for new issue notifications. (There is nothing to do here if you did not check any of the Traits Elaboration text-boxes in the Values Configuration form.)
By assigning specific request trait values to a supporter, that supporter receives notifications about new issues having those settings. If no supporters are identified as relevant for a particular request, the notices for that request are directed to the tracker administrator.
Selecting traits is a way of narrowing the range of issues for which supporter receives new-request email notices. Not selecting any of a supporter's values for a particular trait means that trait is ignored when figuring routing for the supporter. (Thus, its equivalent to selecting all the values for that trait, and less work...)
Traits that have many values have a special first entry - <Invert>. Selecting <Invert> means that the supporter is disqualified by the selected values, rather than qualified by them. This makes it easy to disqualify a supporter for just a few values of some extensive trait.
The tracker needs email addresses for all issue participants. On sites with membership, that information is already available. In its absence, the tracker administrator uses the Member Settings to specify email addresses for supporters and clients. It is automatically visited on submission of the Values Configuration form if there are supporters lacking an email address.