3
<TITLE>Gnatsweb User Guide</TITLE>
6
<H1>Gnatsweb User Guide</H1>
8
<P>The <I>Gnatsweb</I> interface is a front-end to the <I>GNATS</I> problem
9
tracking system used to create, view and modify GNATS problem reports. Support
10
organizations can use it for tracking of issues related to products that are
11
supported (i.e. software, hardware, documentation, etc.) Problem reports are
12
used to notify <I>responsible</I> parties of problems. When the problems are
13
looked into, the problem reports can be edited and email gets sent to all
14
interested parties.</P>
15
<P> The Gnatsweb help is divided into the following sections:</P>
17
<LI><A HREF="#login">Login Page</A></LI>
18
<LI><A HREF="#main">Main Page</A></LI>
19
<LI><A HREF="#create">Create Problem Report Page</A></LI>
20
<LI><A HREF="#edit">Edit Problem Report Page</A></LI>
21
<LI><A HREF="#view">View Problem Report Page</A></LI>
22
<LI><A HREF="#query">Query Problem Reports Page</A></LI>
23
<LI><A HREF="#advquery">Advanced Query Page</A></LI>
24
<LI><A HREF="#qmatches">Query Results Page</A></LI>
26
<P> For more information about GNATS, see the
27
<A HREF="http://www.gnu.org/software/gnats/">GNATS home page</A>.</P>
28
<P>Please note that newer versions of GNATS allows a great degree of
29
customization, such as addition of custom fields, etc. This help file describes
30
default installations of Gnatsweb and for customized installtions, it may not
32
<H2><A NAME="login">Login Page</A></H2>
33
<P>The login page is used to login to the GNATS system. The first time
34
Gnatsweb is used, this page is presented. After the first time, the
35
<A HREF="#main">main page</A> is displayed because the settings are stored in
36
cookies on the machine that has the web browser running. There is a button on
37
the <A HREF="#main">main page</A> that takes the user to the Login Page. This
38
button is used to log out and clear all credentials stored on the user's
39
machine. It is also used to select a new database if desired. There are several
40
controls on the screen: </P>
43
<DT><B>User Name:</B> (textbox) </DT>
44
<DD>This is the GNATS user name to login as. </DD>
45
<DT><B>Password:</B> (textbox)</DT>
46
<DD>This is the GNATS password for the user name. For installations
47
that have been modified not to require passwords, this textbox will be
49
<DT><B>Database:</B> (combobox)</DT>
50
<DD>This selects the database to login to. The dropdown menu lists all
51
the available databases.</DD>
52
<DT><B>Login</B> (button) </DT>
53
<DD>This logs into the selected GNATS database.</DD>
55
<P>If the user name and password are correct, the <A HREF="#main">main
56
page</A> will be shown.</P><HR>
57
<H2><A NAME="main">Main Page</A></H2>
58
<P>The main page is used to select the various operations within the GNATS
59
database. There are seven operations available from this page:</P>
62
<DT><B>Create Problem Report:</B> (button)</DT>
63
<DD>This button displays the <A HREF="#create">Create Problem Report
64
Page</A>. It is used to create a new problem report. If the user has an access
65
level which is too low to create problem reports, this button will be
67
<DT><B>Edit Problem Report:</B> (button and textbox)</DT>
68
<DD>This is used to edit an existing problem report. The Problem Report
69
Number is entered into the text box and either the <KBD>ENTER</KBD> key is
70
pressed or the Edit button is pressed. This button will only be present if the
71
user has sufficiently high access level.</DD>
72
<DT><B>View Problem Report:</B> (button and textbox)</DT>
73
<DD>This is used to view an existing problem report. The Problem Report
74
Number is entered into the text box and either the <KBD>ENTER</KBD> key is
75
pressed or the Edit button is pressed.</DD>
76
<DT><B>Query Problem Reports:</B></DT>
77
<DD>This button displays the <A HREF="#query">Query Problem Reports
78
Page</A>. Used for querying of existing problem reports.</DD>
79
<DT><B>Advanced Query:</B> </DT>
80
<DD>This button displays the <A HREF="#advquery">Advanced Query
81
Page</A>. Used for complex querying of existing problem reports.</DD>
82
<DT><B>Log Out:</B></DT>
83
<DD>This button displays the <A HREF="#login">Login Page</A>. Used for
84
logging out and clearing all login information stored in the user's browser and
85
for selecting a different GNATS database.</DD>
87
<DD>Displays the Gnatsweb User Guide.</DD>
88
</DL></BLOCKQUOTE> <HR>
89
<H2><A NAME="create">Create Problem Report Page</A></H2>
91
<P>The Create Problem Report page is used to create a new problem report.
92
Depending on how the GNATS database is set up, the fields and controls on this
93
page may vary. In the following we describe the fields that are present in a
94
standard installation. Fields that are required to be nonempty are emphasized
95
with a different color, by default red.</P>
98
<DT><B>Reporter's email:</B> (textbox)</DT>
99
<DD>This is the person filing the new problem report. This is necessary
100
because someone without access to the GNATS database may be the
101
<I>Originator</I> (described below).</DD>
102
<DT><B>CC:</B> (textbox)</DT>
103
<DD>Carbon copy the problem report to this email address. This is
104
useful for sending a new problem report to interested parties. Future changes
105
to the problem report are not emailed to this address.</DD>
106
<DT><B>Category:</B> (combobox)</DT>
107
<DD>This combobox allows the selection of a category which the problem
108
report should be filed under. Category names might for instance correspond to
110
<DT><B>Synopsis:</B> (textbox)</DT>
111
<DD>This is a short description of a problem. This is used in the
112
<A HREF="#query">Query Page</A> and the <A HREF="#advquery">Advanced Query
114
<DT><B>Confidential:</B> (combobox)</DT>
115
<DD>This combobox selects whether or not the problem report is
116
confidential. This is useful since in-house problem reports don't necessarily
117
need to be seen by the public.</DD>
118
<DT><B>Severity:</B> (combobox)</DT>
119
<DD>This has three options: <I>critical</I>, <I>serious</I>,
120
<I>non-critical</I>. This is a best guess (i.e. if the hardware catches fire,
121
it should probably be <I>critical</I>). When creating a problem report, the
122
severity level is often merely an educated guess. It will often be changed
123
later on, based on the assessment of the GNATS administrator or the person
124
responsible for the problem category.</DD>
125
<DT><B>Priority:</B> (combobox)</DT>
126
<DD>Like severity, this is merely a guess at the priority level of the
128
<DT><B>Quarter:</B> (textbox)</DT>
129
<DD>What quarter the PR falls into.</DD>
130
<DT><B>Class:</B> (combobox)</DT>
131
<DD>The class (type) of the problem. This is also a guess.</DD>
132
<DT><B>Submitter-Id:</B> (combobox)</DT>
133
<DD>The valid submitter identification. If this is unknown, leave the
134
default setting. Otherwise select the one desired.</DD>
135
<DT><B>Originator:</B> (textbox)</DT>
136
<DD>An email address of the person reporting the problem. This is often
137
the same as the <I>Reporter's email</I> address. </DD>
138
<DT><B>Release:</B> (textbox)</DT>
139
<DD>This should include the installed version of the product which the
140
problem report applies to, together with identification of applied patches,
141
updates, fixes etc. Accurate information in this field is often critical for
142
tracking and diagnosing the problem.</DD>
143
<DT><B>Environment:</B> (textbox)</DT>
144
<DD>A description of the environment where the problem occurred.
145
Important information might include hardware make and model, operating system
146
name and version, system patchlevels etc. In general: the more, the
148
<DT><B>Description:</B> (multi-line textbox)</DT>
149
<DD>A full description of the problem. Good descriptions become good
150
solutions. Bad descriptions make problems hard to solve.</DD>
151
<DT><B>File Attachments:</B> (textbox and button)</DT>
152
<DD>Used for uploading a file to the GNATS database together with the
153
PR. Text files, pictures, anything that is relevant for the problem.</DD>
154
<DT><B>How-To-Repeat:</B> (multi-line textbox)</DT>
155
<DD>This is a description of the steps necessary to recreate the
157
<DT><B>Fix:</B> (multi-line textbox)</DT>
158
<DD>If a workaround or fix has been determined, this is the place to
159
put that information.</DD>
160
<DT><B>Submit</B> (button)</DT>
161
<DD>This submits the problem report to the GNATS database. Email will
162
be sent to several recipients, depending on how GNATS is configured. By default
163
mail goes to the <I>Reporter's email</I> and <I>Originator's</I> email
164
addresses, and all other parties listed in the <I>CC:</I> field. The
165
<I>responsible</I> person and the people on the GNATS category notify list also
167
<DT><B>Reset</B> (button)</DT>
168
<DD>Reset all fields to defaults. Most the textboxes are cleared and
169
the comboboxes are set to their defaults.</DD>
170
</DL></BLOCKQUOTE> <HR>
171
<H2><A NAME="edit">Edit Problem Report Page</A></H2>
172
<P>The Edit page is used to modify a problem report when a solution or fix
173
has been found, or when any other change to the problem report is required.
174
Many of the fields parallel the <A HREF="#create">Create Problem Report
175
Page</A> (consult that section for a description of the other fields), but
176
others are specific to the edit page.</P>
177
<P> Some fields have a textbox labeled <I>Reason Changed</I> just below
178
them. If the field above has been modified, the Reason Changed field must be
179
filled in. This is used for tracking the changes to various fields deemed
180
important enough to require an explicit reason for change.</P>
181
<P> Here are the fields on the edit page that come in addition to those on
182
the Create Problem Report page:</P>
185
<DT><B>Responsible:</B> (combobox)</DT>
186
<DD>This is the identity of the individual who is responsible for
187
handling the problem report.</DD>
188
<DT><B>State:</B> (combobox)</DT>
189
<DD>The current state of the problem report. Usually this field is
190
changed by the Responsible person as the handling of the problem report
192
<DT><B>Class:</B> (combobox)</DT>
193
<DD>The class (type) of the problem report.</DD>
194
<DT><B>Release-Note:</B> (multi-line textbox)</DT>
195
<DD>This field is usually used when a problem report has been closed
196
and incorporated into a new release of a product. The release notes are then
197
usually collected for use in an update report to be distributed with the
198
released software.</DD>
199
<DT><B>Submit Edit</B> (button)</DT>
200
<DD>This submits the changes to the GNATS database. Another page is
201
displayed with the results. If fields are missing or incorrectly filled out,
202
the changes necessary to fix the problem are displayed. By using the 'back'
203
button in the web browser, the user can go back to the problem report, correct
204
the errors and resubmit.</DD>
205
<DT><B>Audit-Trail:</B> (multi-line text display)</DT>
206
<DD>This is a cumulative description of all the changes made to this
208
</DL></BLOCKQUOTE> <HR>
209
<H2><A NAME="view">View Problem Report Page</A></H2>
210
<P>The View page is used to display a GNATS problem report without changing
211
it. It has the same fields described in the <A HREF="#create">Create Problem
212
Report Page</A> and the <A HREF="#edit">Edit Problem Report Page</A>, together
213
with two additional buttons and a link:</P>
216
<DT><B>Edit</B> (button)</DT>
217
<DD>This displays the edit page.</DD>
218
<DT><B>View audit-trail</B> (button)</DT>
219
<DD>Because the Audit-Trail field can get quite long, it is only
220
displayed when this button is clicked.</DD>
221
<DT><B>send email to interested parties</B> (link)</DT>
222
<DD>This is for sending email to the parties interested in this problem
224
</DL></BLOCKQUOTE> <HR>
225
<H2><A NAME="query">Query Problem Reports Page</A></H2>
226
<P>The Query Problem Reports page is for simple searches of the problem
227
report database. It displays the <A HREF="#qmatches">Query Results Page</A>.
228
The fields are "anded" together for the search, meaning that all the criteria
229
selected must match each problem report searched in order for the report to be
230
included in the results. There are several selections that can be made:</P>
233
<DT><B>Submit stored query</B> (button and combobox)</DT>
234
<DD>Often repeated queries can be stored from the <A
235
HREF="#qmatches">Query Results Page</A>. This selects a previously stored
236
query. If no queries have been stored, this field is not displayed.</DD>
237
<DT><B>Category:</B> (combobox)</DT>
238
<DD>This will select <I>any</I> or a specific category to search.</DD>
239
<DT><B>Severity:</B> (combobox)</DT>
240
<DD>This will select <I>any</I> or a specific severity to search.</DD>
241
<DT><B>Priority:</B> (combobox)</DT>
242
<DD>This will select <I>any</I> or a specific priority to search.</DD>
243
<DT><B>Responsible:</B> (combobox)</DT>
244
<DD>This will select <I>any</I> or a specific responsible to
246
<DT><B>State:</B> (combobox)</DT>
247
<DD>This will select <I>any</I> or a specific state to search.</DD>
248
<DT><B>Ignore Closed</B> (checkbox)</DT>
249
<DD>This selects whether or not to ignore closed problem reports
250
(ignore is on by default).</DD>
251
<DT><B>Class:</B> (combobox)</DT>
252
<DD>This will select <I>any</I> or a specific class to search.</DD>
253
<DT><B>Submitter-Id:</B> (combobox)</DT>
254
<DD>This will select <I>any</I> or a specific submitter-id to
256
<DT><B>Originated by You</B> (checkbox)</DT>
257
<DD>Allows you to limit queries to reports originated by yourself. Note
258
that Originator and Submitter-Id are different fields.</DD>
259
<DT><B>Synopsis Search:</B> (textbox)</DT>
260
<DD>This will search the synopsis field for the text entered.</DD>
261
<DT><B>Multi-line Text Search:</B> </DT>
262
<DD>This will search any the multi-line text fields for the text
264
<DT><B>Column Display:</B> (multi-select listbox)</DT>
265
<DD>This selects the columns to be displayed in the query results
266
table. The selection is stored by the web browser, so the next time a query is
267
requested, the columns selected for the previous query will be selected by
269
<DT><B>Sort By:</B> (combobox)</DT>
270
<DD>Selects which field to sort search results by.</DD>
271
<DT><B>Reverse Order:</B> (checkbox)</DT>
272
<DD>Allows you to reverse the sort order. Highest-numbered PRs first,
274
<DT><B>Display: Current Date</B> (checkbox)</DT>
275
<DD>This selects whether or not to display the current date and time on
276
the query results page. (This is on by default).</DD>
277
<DT><B>Submit query</B> (button)</DT>
278
<DD>This submits the query and the <A HREF="#qmatches">Query Results
279
Page</A> is displayed.</DD>
280
</DL></BLOCKQUOTE> <HR>
281
<H2><A NAME="advquery">Advanced Query Problem Reports Page</A></H2>
282
<P>The Advanced Query Problem Reports page is not for the faint of heart.
283
This is a very complicated form with many features. There are three buttons and
284
a combobox to start the search:</P>
287
<DT><B>Submit stored query</B> (button and combobox)</DT>
288
<DD>Often repeated queries can be stored from the <A
289
HREF="#qmatches">Query Results Page</A>. This selects a previously stored
290
query. If no queries have been stored, this field is not displayed.</DD>
291
<DT><B>Submit query</B> (button)</DT>
292
<DD>Submit the advanced query, and display the <A
293
HREF="#qmatches">Query Results Page</A>.</DD>
294
<DT><B>Reset</B> (button)</DT>
295
<DD>Reset the form.</DD>
297
<P>There are four sub-sections to this form:</P>
299
<LI>Search All Text</LI>
300
<LI>Search By Date</LI>
301
<LI>Search Individual Fields</LI>
304
<P>Any one of these sub-sections can be used separately or together for
305
complex searches.</P>
306
<H3>Search All Text</H3>
307
<P>There are two types of searches on all text:</P>
309
<LI>Single-line text fields</LI>
310
<LI>Multi-line text fields</LI>
312
<P>Regular expressions can be used in searches.</P>
313
<H3>Search By Date</H3>
314
<P>The Search By Date sub-section allows you to limit the range of problem
315
reports according to various time parameters. There are six self explanatory
316
fields available:</P>
318
<LI>Arrived After</LI>
319
<LI>Arrived Before</LI>
320
<LI>Modified After</LI>
321
<LI>Modified Before</LI>
322
<LI>Closed After</LI>
323
<LI>Closed Before</LI>
325
<P>The dates are entered in a string like: <KBD>1999-04-01 05:00 GMT</KBD>.
326
Though the date matching scheme is pretty robust, it should accept quite a few
328
<H3>Search Individual Fields</H3>
329
<P>The Search Individual Fields sub-section is used for matching based on a
330
specific field in the GNATS problem report. All the fields have a textbox for
331
doing regular expression searches. Where applicable, fields have a multi-select
332
listbox that can be used. When nothing is entered for the textbox or selected
333
in the listbox, those fields are not used in the match. The available fields
334
may differ depending on the way GNATS is set up, but here are the valid
335
matchable fields in a default installation:</P>
339
<LI>Confidential</LI>
345
<LI>Submitter-Id</LI>
349
<P>Each field is described in the <A HREF="#create">Create Problem Report
350
Page</A> or the <A HREF="#edit">Edit Problem Report Page</A> sections of this
351
user guide. The 'state' field also has an 'Ignore Closed' checkbox to ignore
352
all closed problem reports.</P>
354
<P>This sub-section is a multi-select listbox that is used to set the
355
displayable columns in the <A HREF="#qmatches">Query Results Page</A>.</P>
356
<P>Below this is a row entitled "Display". The checkbox "Current Date" in
357
this row controls whether or not the current date will be displayed on the
358
query results page. (This is on by default).</P><HR>
359
<H2><A NAME="qmatches">Query Results Page</A></H2>
360
<P>The problem report table displayed shows the problem report numbers as
361
links to the <A HREF="#view">View Problem Report Page</A>. In order to sort the
362
table by the contents of a specific column, click the column heading.</P>
363
<P>Near the bottom of the page is a link marked "View for bookmarking".
364
Normally, specific Gnatsweb pages can't be bookmarked, but by clicking on this
365
link and using the bookmark function of your browser, you can get a bookmark
366
for this particular page.</P>
367
<P>Below this again is the "Reverse sort order" link which allows you to
368
reverse the sort order of the currently displayed query results.</P>
369
<P>Below the bookmarking link is a text entry field and a button to store a
370
query selection. Stored queries are accessible from the <A HREF="#query">Query
371
Problem Reports Page</A> or the <A HREF="#advquery">Advanced Query Problem
372
Reports Page</A>. This provides for a quick way to repeat often-made searches
373
without having to make all the selections again. </P> </BODY>
added
removed
contrib/gnatsweb/gnatsweb.html
