HNTracker User Guide

Draft (D2x10) [2002-11-21]


  1. Introduction
  2. Users and Administrators
  3. Logging In
    1. login
    2. The Menu
    3. logout
  4. Using the System
    1. The Joblist
      1. The List Explained
      2. Admin Differences
      3. Deadline Jobs
    2. Adding Jobs
    3. Searching for Jobs
    4. Reports and Views
      1. Reports
      2. Alternative Views
        1. Abstract View
        2. UJL (Unprioritized Jobs List)
    5. Modifying Jobs
      1. make changes
      2. comment on changes
    6. Job History
      1. job info
      2. history summary
      3. history detail
      4. add comment
  5. Reference
    1. Job Categories
    2. Job Statuses

Section 1. Introduction

Welcome to HNTracker, the HealthNet 2 bugfix and enhancement request tracking tool manual. This manual contains information on the appearance and behavior of HNTracker, as well as usage information.

Usage notes look like this.

Finally, be aware that every hyperlink in HNTracker will display a tooltip explaining its function if you hover your mouse over it.

Section 2. Users and Administrators

HNTracker (hence: HNT) has users (and a special class of users, admins). This is not a trust or control issue, as the app is still fundamentally insecure, but an accounting issue. Since the system knows who you are, it can fill in a great deal of info for you, saving everyone time and effort.

HNT has the concept of users, which is hardly an uncommon one these days, but it's a change over the old system. While the user+login concept does keep unauthorized people out, its real job is tracking.

Every action of consequence (i.e. those which result in a database or job status modification of any kind) is tracked and recorded, so that we have a full history of all actions performed on a job which is separate from and independent of whatever descriptions people choose to add. Again, only actions which modify jobs are tracked. Searching for, listing, and/or viewing the details of jobs aren't recorded in any way (other than the logs of the webserver).

Some users will be flagged as administrators, another concept new to HNT. Admins differ from regular users only in that they can make more extensive changes to jobs than users can. Their abilities will be covered in the sections of the guide to which they are germane.

Section 3. Logging In

The first thing you will see when meeting HNT is a login screen. It is divided into two main sections: the actual login area at top, and a news panel on the bottom.

The news section, as you might expect, is simply an area where updates about the HNT system itself will appear. Hopefully the only things you'll be seeing here are notifications that new features have been enabled.

3.1 login

The login panel is pretty self-explanatory as well. Type your username into the top textbox and your password into the lower one, bearing in mind that username and password are case-sensitive, then click login or just hit ENTER.

If you typed everything correctly, you'll be taken directly to the joblist screen (technically, you will be redirected to the joblist page — you may or may not see the interstitial notice go by, depending on your browser). This is unlike the old support database, where you first went to a selection screen where you could choose the criteria for the jobs you wanted to see, but in reality everyone just clicked on the button and went with the defaults.

If you messed something up, you'll end up at a screen which tells you that you messed something up and provides a new username/passwd box so you can try again.

3.2 The Menu

Once you're logged in, you'll be presented with the joblist. We'll get to that in a minute, but first look under "HNTracker::JobList". There's a single row of links in gray boxes with orange left borders. This is the jump menu, and it is on every page in the HNT system (at the bottom of every page and at the top of pages which might prove annoying to scroll all the way to the bottom).

Often, as a result of an action you perform, HNT will redirect you to where it thinks you probably want to go, as when you logged in and were redirected to the joblist. That redirect had a zero second timeout, but most have either 5 or 10 second timeouts. This gives you time to read the message, which will state where you are being redirected to, and use the menu to go elsewhere if you wish to do so.

Admins have a menu option which regular users do not, newjob. This leads to the new job entry screen.

The links in the menu are in order L-R by (estimated) utility, with the most frequently needed item first, and so on down the line. The layout of this document mirrors the order of the menu.

3.3 logout

The last (rightmost) option on the menu is logout. This, predictably, logs you out of the system. Next to the word "logout" will be name of the user you are currently logged in as. This is to help people who have multiple accounts, one an admin and the other not an admin, for instance. If you are logged in an as admin, there will be an asterisk next to your name as a visual reminder.

Section 4. Using the System

4.1 The Joblist

The joblist is really the heart of HNT. It's a simple table which, by default, provides an overview of all current jobs sorted by priority, highest priority first, and then by job id within priority.

4.1.1 The List Explained

jid Job Identification Number A unique numeric identifier. The jid is a link to the detail history of a job; click it to see all changes, notes, and full history. There's an m in parentheses next to the jid; click on it to jump straight to the modjob screen with that job pre-loaded.
job desc Job Description Freeform short text description of the job because humans aren't terribly good at associating things with numbers.
pri Priority A numeric representation of the importance of the job, and the default sort criteria. pri is currently limited to values. between 0 and 99.
cat Category All jobs fit into one of several categories. To save space, only a two character abbreviation is shown (an expanded list is provided in this document). In modern browsers, hovering the mouse over the abbreviation will display the expanded category.
stat Status The current status of the job. Behaves like cat. There is also a list of statuses in this document for your reference, and an expansion of the abbreviation will display on mouse-hover.
handler N/A The handler is the person who is currently assigned to the job. This is NOT neccessarily the same as the person who last modified the job in HNT; the two are now separate.
idle Idle Time This is a counter of elapsed time (in days) since the job was last updated in the HNT system.
age Job Age This is days elapsed since the job was entered into HNT.

You can click on any of the table headers to resort the table by that column. Priority, Idle, and Age sort in descending (high-to-low) order; the rest sort ascending (low-to-high).

4.1.2 Admin Differences

Admins will see some things in the joblist that regular users do not.

First, in the pri column, they will see these characters following the job priority: ++|--. Simply click the plusses to increment the priority of the job or the minuses to decrement the priority of the job. This is one of the actions which automatically creates a history record.

Also, they will see an extra column on the right, also labeled pri and containing a small textbox. This field allows them to manually set a job's priority to any value in one action. This also creates a history record.

4.1.3 Deadline Jobs

HNT has the concept of a "deadline job". These are jobs which have Federal or State imposed deadlines, and thus MUST be completed by same. We should not see many of these jobs, but support for them exists. Note that deadline jobs are sorted by deadline, then priority, and then job id.

When there are deadline jobs, they will appear in a separate table above the regular joblist. When there are none, their table disappears completely.

The deadline job table differs from the regular joblist in a couple of ways. First, and most obviously, there is a dday (standing for "D-Day" or "due date", your choice) column next to the age column. This column (surprise) shows the actual deadline date, followed by days-to-deadline and the percentage of the job's life remaining (now matching the format of this data on othre screens).

These columns will change color as a visible representation of the aging of the job. The color change coincides with percentage-based changes in the age of the job rather than raw days-left reckoning because the jobs are already sorted in that order. The image at right illustrates the various stages.

4.2 Adding Jobs

The newjob screen is fairly straightforward. Here is a key to what its fields mean:

job title This is a short (40 character max) title or name for the job. It should be succinct and as descriptive as you can make it. This is what appears on the joblist.
job abstract Just like an abstract in an academic paper, this is a one-sentence or one-paragraph "executive summary" of the job. No actual length limit, but should be kept short-ish.
initial spec/desc This space is for entry of the initial job specification or any other description you wish to add. The content of this field will become the first history record for the job.
spec/desc button The radiobuttons underneath the text entry field determine whether it is to be treated as a specification (default) or a regular comment. This is here because specs are displayed differently than other record types on the history screen.
job category Sets the category of the job
initial priority This field is optional. If left blank, the priority will default to one (1). Any number between 0 and 99 (inclusive) may be entered to give a job a priority other than the default. Note that the priority of a job can be shifted at any time through the joblist. Only admins can set a priority. Users will not see this field.
deadline This is intended only for use on jobs with State or Federal imposed deadlines. Any date entered here in YYYY-MM-DD format will cause the job to be flagged as a deadline job (as described elsewhere). Only admins can set a deadline. Users will not see this field.

Note that any HTML entered in the abstract and description fields will be "undone" and changed into printable character entities (markup will not work in these fields).

4.3 Searching for Jobs

Using the search screen is fairly self-explanatory, but there are a few things which may not be immediately obvious.

First and foremost, be careful when using the OR toggle. When you are searching with multiple conditions, anything not ORd is automatically ANDed, and mySQL evaluates these conditions in the same manner as C or Perl: AND conditions, left to right, followed by OR conditions, left to right. It is easy to get results that aren't what you might expect in a complex query.

Next, the range operators on the numeric sort values. From left to right they are, of course, less than, equal to, and greater than. Check one of these and enter a value in the left value field to do a search like "age greater than 20".

Also, the NOT operator works a little differently than you may expect. Negating the equals operator produces "not equal to", of course, but NOT less than is equivalent to greater than or equal to, and not simply greater than. In this way, you can get all possible inequalities for a single value.

The second (right) value field is for bounded ranges. When a second value is entered, the range operators (if given) are ignored and the operation becomes a BETWEEN (algebraically, VALUE1 <= x <= VALUE2). Negating this results in a union of x < VALUE1 and x > VALUE2.

Finally, be aware that unlike the rest of this system, which has fairly pervasive data validation checks, the search screen has none at all (at the moment).

If your search returns nothing, you will be told so. Otherwise you will be redirected to a listing of your results, which is in fact a special case of the joblist. You can even sort your results just as you can sort the regular joblist.

4.4 Reports and Views

Here you can find various ways of looking at the data in the system other than the joblist or a single-record lookup. Eventually there'll probably be some neat statistical stuff in here but it's pretty bare bones for now.

4.4.1 Reports

There are no proper reports yet.

4.4.2 Alternative Views

A couple of alternative data views are available. Abstract View

This view of the joblist drops out the status, category, handler, and job age information to make room for the abstract description of each job. This causes a visual shift of the priority to the far right though its position in the field count of the table has not changed.

You cannot sort by the abstract field. UJL (Unprioritized Jobs List)

This view is exactly like the Abstract View except that it only includes jobs with a priority of 1; jobs which have not been shifted from the default priority.

You cannot sort by the abstract field.

4.5 Modifying Jobs

There are three ways to get to the job modification screen: from the joblist, from the detail view screen, and from the bottom link menu.

If you click on modjob in the bottom menu, you'll be prompted for the jid of the job you wish to modify; enter it and you will be shown the job modification screen, which has two sections.

4.5.1 make changes

First, at the top, there is a table showing, on the left:

and on the right side of the table are fields for changing these values. Which fields you see will depend on whether you are a user or administrator.

Everyone will see the words "change status to" and a drop-menu next to the current status diaplay. This, naturally, is where you can change the status of a job.

Note that changing the status of a job to handling does NOT change the handler of a job. Users cannot assign jobs to other users, and creating this relationship would negate that protection. Similarly, a user may have many jobs assigned to them which they are not currently working on, so creating an automatic change of status based on a change of handler would create a false impression as well. Admins must assign jobs to users, who will then change the status of that job whenever neccessary.

Admins will also see a menu of categories, and a menu of users, and a date field for changing the deadline of a job. The category and user fields are pretty self explanatory; the deadline field works as follows: to change a deadline or make a non-deadline job have a deadline, just enter a valid date. To remove the deadline from a job, enter a date of 0000-00-00.

As many aspects of a job as you wish can be changed at once; there is no need to make multiple cycles through the modjob screen to effect multiple changes to a single job. Also, the current value for any given field will never be avialable in its selection list (you can't reassign a job to its current handler), and other values may also be excluded depending on the circumstance (for instance, a job cannot be set back to "New" status).

4.5.2 comment on changes

Below the changes area there is a comment box where you can add any comments you wish to explain why changes are being made to the job. There is no comment type select box here, because all comments made through this form are automatically linked to job changes. If you wish to add an informational comment please go to the history screen.

There are buttons labelled "make changes" in both sections of this screen. This is just a convenience; they have the same function and either can be clicked to submit all changes.

This comment area is intended only to be used to describe changes being made. To make a general comment, add a progress note or an FYI, etc., go to the job's history.

Note that any HTML entered in the comment field will be "undone" and changed into printable character entities (markup will not work in these fields).

4.6 Job History

The easiest way to view a job's history is to click on its jid in the joblist, but you can also use the menu to jump to the history page, which will prompt you for a jid.

Theis screen has three sections: job info, history summary, and history detail. We'll cover them top-to-bottom.

4.6.1 job info

This small block at the top of the page lists some general information about the job, most of which can also be found on the joblist. It is included here for convenience.

Below this is a button which links to the modjob screen; clicking it will take you there with the current job pre-loaded.

4.6.2 history summary

Next is a block of information which represents the complete history of the job. For every change that is made to the job and every note that is added to the job, a single line of information will appear here. There are three pieces of information on every line:

Description - This is a short message, autogenerated by HNT itself, about the action which was recorded, including who initiated it.
Change Type - Tells exactly what kind of change was made, or what kind of documentation was added.
Just as it sounds, lists the time the change was made.

If a change has documentation associated with it, the desc field will be a link to the content of that documentation in the detail section.

4.6.3 history detail

In the detail section, the full text of job specifications, documentation, notes entered by users, and comments on job changes can be found.

Each detail record is contained in a block of its own, with two lines of headers which repeat information from the summary block followed by the text of the record itself.

History records which are flagged as specifications will be displayed in a monospace font, one step smaller than regular text, in order to help preserve their layout.

History records which have a type of FYI will be truncated to 256 characters in the normal view, and will have a link (Read more...) following this excerpt. Click the link to view the full text of the record.

4.6.4 add comment

At the bottom of all view pages is a textarea where you can add a new comment to the history record. Just enter whatever text you wish, select the appropriate comment type from the drop-down menu, and click "submit". Comments entered here are just plain notes, and are not associated with any other type of job change.

There are several types of comment available, and they are intended to be used as follows:

Note that any HTML entered in the comment field will be "undone" and changed into printable character entities (markup will not work in these fields).

Section 5. Reference

5.1 Job Categories

5.2 Job Statuses