1 ==========
2 User Guide
3 ==========
5 :Version: $Revision: 1.17 $
7 .. contents::
9 Note: this document will refer to *issues* as the primary store of information
10 in the tracker. This is the default of the classic template, bubt may vary in
11 any given installation.
13 Your Tracker in a Nutshell
14 ==========================
16 Your tracker holds information about issues in bundles we call *items*. An
17 item may be an *issue* (a bug or feature request) or a *user*. The issue-ness or
18 user-ness is called the item's *class*. So, for bug reports and features, the
19 class is "issue", and for users the class is "user".
21 Each item in the tracker has an id number that identifies it along with its
22 item class. To identify a particular issue or user, we combine the class with
23 the number to create a unique label, so that user 1 (who, incidentally, is
24 *always* the "admin" user) is referred to as "user1". Issue number 315 is
25 referred to as "issue315". We call that label the item's *designator*.
27 Accessing the Tracker
28 ---------------------
30 You may access your tracker through one of three ways:
32 1. through the `web interface`_,
33 2. through the `e-mail gateway`_, or
34 3. using the `command line tool`_.
36 The last is usually only used by administrators. Most users will use the web
37 and email interfaces. All three are explained below.
40 Web Interface
41 =============
43 Note: this document contains screenshots of the default look and feel. Your
44 site may have a slightly (or very) different look, but the functionality will
45 be very similar, and the concepts still hold.
47 The web interface is broken up into the following parts:
49 1. `lists of items`_,
50 2. `display, edit or entry of an item`_, and
51 3. `searching page`_.
54 Lists of Items
55 --------------
57 The first thing you'll see when you log into Roundup will be a list of open
58 (ie. not resolved) issues. This list has been generated by a bunch of controls
59 `under the covers`_ but for now, you can see something like:
61 .. img: images/index_logged_out.png
63 The screen is divided up into three sections:
65 .. img: images/page_layout.png
67 you may either register or log in. Registration takes you to:
69 .. img: images/registration.png
71 Once you're logged in, the screen changes slightly to:
73 .. img: images/index_logged_in.png
75 Note that the sidebar menu has changed slightly, so you can now get to your
76 "My Details" page:
78 .. img: images/my_details.png
80 Note the new information on this page - the history.
83 Display, edit or entry of an item
84 ---------------------------------
86 Create a new issue with "create new" under the issue subheading. This will
87 take you to:
89 .. img: images/new_issue.png
91 The `nosy list`_ is explained below.
92 Enter some information and click "submit new entry" and you'll be rewarded
93 with:
95 .. img: images/new_issue_created.png
97 or, if you don't enter all the required information (or some other error
98 occurs) you'll get something like:
100 .. img: images/new_issue_error.png
103 Searching Page
104 --------------
106 XXX: some information about how searching works
108 Some fields in the search page (e.g. "Activity" or "Creation date") accept
109 ranges of dates. You can specify range of dates in one of two formats:
111 1. Native english syntax::
113 [[From] <value>][ To <value>]
115 Keywords "From" and "To" are case insensitive. Keyword "From" is optional.
117 2. "Geek" syntax::
119 [<value>][; <value>]
121 Either first or second ``<value>`` can be omitted in both syntaxes.
123 For example:
125 if you enter string "from 9:00" to "Creation date" field, roundup
126 will find all issues, that were created today since 9 AM.
128 Searching of "-2m; -1m" on activity field gives you issues, which were
129 active between period of time since 2 months up-till month ago.
131 Other possible examples (consider local time is Sat Mar 8 22:07:48 EET 2003):
133 >>> Range("from 2-12 to 4-2")
134 <Range from 2003-02-12.00:00:00 to 2003-04-02.00:00:00>
136 >>> Range("18:00 TO +2m")
137 <Range from 2003-03-08.18:00:00 to 2003-05-08.20:07:48>
139 >>> Range("12:00")
140 <Range from 2003-03-08.12:00:00 to None>
142 >>> Range("tO +3d")
143 <Range from None to 2003-03-11.20:07:48>
145 >>> Range("2002-11-10; 2002-12-12")
146 <Range from 2002-11-10.00:00:00 to 2002-12-12.00:00:00>
148 >>> Range("; 20:00 +1d")
149 <Range from None to 2003-03-09.20:00:00>
152 Under the covers
153 ----------------
155 Index views may be modified by the following arguments:
157 ========== =============================================================
158 Argument Description
159 ========== =============================================================
160 :sort sort by prop name, optionally preceeded with '-'
161 to give descending or nothing for ascending sorting.
162 :group group by prop name, optionally preceeded with '-' or
163 to sort in descending or nothing for ascending order.
164 :filter selects which props should be displayed in the filter
165 section. Default is all.
166 :columns selects the columns that should be displayed.
167 Default is all.
168 propname selects the values the item properties given by propname
169 must have (very basic search/filter).
170 ========== =============================================================
172 Access Controls
173 ---------------
175 User access is controlled through Permissions. These are are grouped into
176 Roles, and users have a comma-separated list of Roles assigned to them.
178 Permissions divide access controls up into answering questions like:
180 - may the user edit issues ("Edit", "issue")
181 - is the user allowed to use the web interface ("Web Access")
182 - may the user edit other user's Roles through the web ("Web Roles")
184 Any number of new Permissions and Roles may be created as described in the
185 customisation documentation. Examples of new access controls are:
187 - only managers may sign off issues as complete
188 - don't give users who register through email web access
189 - let some users edit the details of all users
192 E-Mail Gateway
193 ==============
195 E-mail sent to Roundup is examined for several pieces of information:
197 1. `subject-line information`_ identifying the purpose of the e-mail
198 2. `e-mail message content`_ which is to be extracted
199 3. e-mail attachments which should be associated with the message
201 Subject-line information
202 ------------------------
204 The subject line of the incoming message is examined to find one of:
206 1. the item that the message is responding to,
207 2. the type of item the message should create, or
208 3. we default the item class and try some trickiness
210 If the subject line contains a prefix in ``[square brackets]`` then we're
211 looking at case 1 or 2 above. Note that any "re:" or "fwd:" prefixes are
212 stripped off the subject line before we start looking for real information.
214 If an item designator (class name and id number, for example ``issue123``)
215 is found there, a new "msg" item is added to the "messages" property for
216 that item, and any new "file" items are added to the "files" property for
217 the item.
219 If just an item class name is found there, we attempt to create a new item of
220 that class with its "messages" property initialized to contain the new "msg"
221 item and its "files" property initialized to contain any new "file" items.
223 The third case above - where no ``[information]`` is provided, the tracker's
224 ``MAIL_DEFAULT_CLASS`` configuration variable defines what class of item
225 the message relates to. We try to match the subject line to an existing
226 item of the default class, and if there's a match, the message is related to
227 that matched item. If not, then a new item of the default class is created.
229 Setting Properties
230 ~~~~~~~~~~~~~~~~~~
232 The e-mail interface also provides a simple way to set properties on items. At
233 the end of the subject line, propname=value pairs can be specified in square
234 brackets, using the same conventions as for the roundup set shell command.
236 For example,
238 - setting the priority of an issue::
240 Subject: Re: [issue1] the coffee machine is broken! [priority=urgent]
242 - adding yourself to a nosy list::
244 Subject: Re: [issue2] we're out of widgets [nosy=+richard]
246 - setting the nosy list to just you and cliff::
248 Subject: Re: [issue2] we're out of widgets [nosy=richard,cliff]
250 - removing yourself from a nosy list and setting the priority::
252 Subject: Re: [issue2] we're out of widgets [nosy=-richard;priority=bug]
254 In all cases, the message relates to issue 2. The ``Re:`` prefix is stripped
255 off.
258 Automatic Properties
259 ~~~~~~~~~~~~~~~~~~~~
261 **status of new issues**
262 When a new message is received that is not identified as being related to an
263 existing issue, it creates a new issue. The status of the new issue is
264 defaulted to "unread".
266 **reopening of resolved issues**
267 When a message is is received for a resolved issue, the issue status is
268 automatically reset to "chatting" to indicate new information has been
269 received.
272 E-Mail Message Content
273 ----------------------
275 Roundup only associates plain text (MIME type ``text/plain``) as messages for
276 items. Any other parts of a message are associated as downloadable files. If
277 no plain text part is found, the message is rejected.
279 To do this, incoming messages are examined for multiple parts:
281 * In a multipart/mixed message or part, each subpart is extracted and
282 examined. The text/plain subparts are assembled to form the textual body
283 of the message, to be stored in the file associated with a "msg" class
284 item. Any parts of other types are each stored in separate files and
285 given "file" class items that are linked to the "msg" item.
286 * In a multipart/alternative message or part, we look for a text/plain
287 subpart and ignore the other parts.
289 If the message is a response to a previous message, and contains quoted
290 sections, then these will be stripped out of the message if the
291 ``EMAIL_KEEP_QUOTED_TEXT`` configuration variable is set to ``'no'``.
293 Message summary
294 ~~~~~~~~~~~~~~~
296 The "summary" property on message items is taken from the first non-quoting
297 section in the message body. The message body is divided into sections by blank
298 lines. Sections where the second and all subsequent lines begin with a ">" or
299 "|" character are considered "quoting sections". The first line of the first
300 non-quoting section becomes the summary of the message.
303 Address handling
304 ----------------
306 All of the addresses in the ``To:`` and ``Cc:`` headers of the incoming
307 message are
308 looked up among the tracker users, and the corresponding users are placed
309 in the
310 "recipients" property on the new "msg" item. The address in the ``From:`` header
311 similarly determines the "author" property of the new "msg" item. The default
312 handling for addresses that don't have corresponding users is to create new
313 users with no passwords and a username equal to the address.
315 The addresses mentioned in the ``To:``, ``From:`` and ``Cc:`` headers of
316 the message may be added to the `nosy list`_ depending on:
318 ``ADD_AUTHOR_TO_NOSY``
319 Does the author of a message get placed on the nosy list automatically?
320 If 'new' is used, then the author will only be added when a message
321 creates a new issue. If 'yes', then the author will be added on followups
322 too. If 'no', they're never added to the nosy.
324 ``ADD_RECIPIENTS_TO_NOSY``
325 Do the recipients (To:, Cc:) of a message get placed on the nosy list?
326 If 'new' is used, then the recipients will only be added when a message
327 creates a new issue. If 'yes', then the recipients will be added on
328 followups too. If 'no', they're never added to the nosy.
331 Nosy List
332 ~~~~~~~~~
334 Roundup watches for additions to the "messages" property of items.
336 When a new message is added, it is sent to all the users
337 on the "nosy" list for the item that are not already on the "recipients" list
338 of the message. Those users are then appended to the "recipients" property on
339 the message, so multiple copies of a message are never sent to the same user.
340 The journal recorded by the hyperdatabase on the "recipients" property then
341 provides a log of when the message was sent to whom.
343 If the author of the message is also in the nosy list for the item that the
344 message is attached to, then the config var ``MESSAGES_TO_AUTHOR`` is queried
345 to determine if they get a nosy list copy of the message too.
348 Mail gateway script command line
349 --------------------------------
351 The roundup mail gateway may be called in one of three ways:
353 . with an instance home as the only argument,
354 . with both an instance home and a mail spool file, or
355 . with both an instance home and a pop server account.
357 It also supports optional -C and -S arguments that allows you to set a
358 fields for a class created by the roundup-mailgw. The default class if
359 not specified is msg, but the other classes: issue, file, user can
360 also be used. The -S or --set options uses the same
361 property=value[;property=value] notation accepted by the command line
362 roundup command or the commands that can be given on the Subject line
363 of an email message.
365 It can let you set the type of the message on a per email address basis.
367 PIPE:
368 In the first case, the mail gateway reads a single message from the
369 standard input and submits the message to the roundup.mailgw module.
371 UNIX mailbox:
372 In the second case, the gateway reads all messages from the mail spool
373 file and submits each in turn to the roundup.mailgw module. The file is
374 emptied once all messages have been successfully handled. The file is
375 specified as::
377 mailbox /path/to/mailbox
379 POP:
380 In the third case, the gateway reads all messages from the POP server
381 specified and submits each in turn to the roundup.mailgw module. The
382 server is specified as::
384 pop username:password@server
386 The username and password may be omitted::
388 pop username@server
389 pop server
391 are both valid. The username and/or password will be prompted for if
392 not supplied on the command-line.
394 APOP:
395 Same as POP, but using Authenticated POP::
397 apop username:password@server
400 Command Line Tool
401 =================
403 The basic usage is::
405 Usage: roundup-admin [options] [<command> <arguments>]
407 Options:
408 -i instance home -- specify the issue tracker "home directory" to administer
409 -u -- the user[:password] to use for commands
410 -d -- print full designators not just class id numbers
411 -c -- when outputting lists of data, comma-separate them.
412 Same as '-S ","'.
413 -S <string> -- when outputting lists of data, string-separate them
414 -s -- when outputting lists of data, space-separate them.
415 Same as '-S " "'.
417 Only one of -s, -c or -S can be specified.
419 Help:
420 roundup-admin -h
421 roundup-admin help -- this help
422 roundup-admin help <command> -- command-specific help
423 roundup-admin help all -- all available help
425 Commands:
426 commit
427 create classname property=value ...
428 display designator[,designator]*
429 export [class[,class]] export_dir
430 find classname propname=value ...
431 get property designator[,designator]*
432 help topic
433 history designator
434 import import_dir
435 initialise [adminpw]
436 install [template [backend [admin password]]]
437 list classname [property]
438 pack period | date
439 reindex
440 retire designator[,designator]*
441 rollback
442 security [Role name]
443 set items property=value property=value ...
444 specification classname
445 table classname [property[,property]*]
446 Commands may be abbreviated as long as the abbreviation matches only one
447 command, e.g. l == li == lis == list.
450 All commands (except help) require a tracker specifier. This is just the
451 path to the roundup tracker you're working with. A roundup tracker is where
452 roundup keeps the database and configuration file that defines an issue
453 tracker. It may be thought of as the issue tracker's "home directory".
454 It may be specified in the environment variable ``TRACKER_HOME`` or on
455 the command line as "``-i tracker``".
457 A designator is a classname and an itemid concatenated, eg. bug1, user10, ...
458 Property values are represented as strings in command arguments and in the
459 printed results:
461 - Strings are, well, strings.
462 - Password values will display as their encoded value.
463 - Date values are printed in the full date format in the local time zone,
464 and accepted in the full format or any of the partial formats explained
465 below.::
467 Input of... Means...
468 "2000-04-17.03:45" 2000-04-17.08:45:00
469 "2000-04-17" 2000-04-17.00:00:00
470 "01-25" yyyy-01-25.00:00:00
471 "08-13.22:13" yyyy-08-14.03:13:00
472 "11-07.09:32:43" yyyy-11-07.14:32:43
473 "14:25" yyyy-mm-dd.19:25:00
474 "8:47:11" yyyy-mm-dd.13:47:11
475 "." "right now"
477 - Link values are printed as item designators. When given as an argument,
478 item designators and key strings are both accepted.
479 - Multilink values are printed as lists of item designators joined by
480 commas. When given as an argument, item designators and key strings are
481 both accepted; an empty string, a single item, or a list of items joined
482 by commas is accepted.
484 When multiple items are specified to the roundup get or roundup set
485 commands, the specified properties are retrieved or set on all the listed
486 items. When multiple results are returned by the roundup get or roundup
487 find commands, they are printed one per line (default) or joined by commas
488 (with the "``-c``" option).
490 Where the command changes data, a login name/password is required. The login may
491 be specified as either "``name``" or "``name:password``".
493 - ``ROUNDUP_LOGIN`` environment variable
494 - the "``-u``" command-line option
496 If either the name or password is not supplied, they are obtained from the
497 command-line.
499 Using with the shell
500 ~~~~~~~~~~~~~~~~~~~~
502 With version 0.6.0 or newer of roundup which supports: multiple
503 designators to display and the -d, -S and -s flags.
505 To find all messages regarding chatting issues that
506 contain the word "spam", for example, you could execute the
507 following command from the directory where the database
508 dumps its files::
510 shell% for issue in `roundup-admin -ds find issue status=chatting`; do
511 > grep -l spam `roundup-admin -ds ' ' get messages $issue`
512 > done
513 msg23
514 msg49
515 msg50
516 msg61
517 shell%
519 Or, using the -dc option, this can be written as a single command::
521 shell% grep -l spam `roundup get messages \
522 \`roundup -dc find issue status=chatting\``
523 msg23
524 msg49
525 msg50
526 msg61
527 shell%
529 You can also display issue contents::
531 shell% roundup-admin display `roundup-admin -dc get messages \
532 issue3,issue1`
533 files: []
534 inreplyto: None
535 recipients: []
536 author: 1
537 date: 2003-02-16.21:23:03
538 messageid: None
539 summary: jkdskldjf
540 files: []
541 inreplyto: None
542 recipients: []
543 author: 1
544 date: 2003-02-15.01:59:11
545 messageid: None
546 summary: jlkfjadsf
548 or status::
550 shell% roundup-admin get name `/tools/roundup/bin/roundup-admin \
551 -dc -i /var/roundup/sysadmin get status issue3,issue1`
552 unread
553 deferred
555 or status on a single line::
557 shell% echo `roundup-admin get name \`/tools/roundup/bin/roundup-admin \
558 -dc -i /var/roundup/sysadmin get status issue3,issue1\``
559 unread deferred
561 which is the same as::
563 shell% roundup-admin -s get name `/tools/roundup/bin/roundup-admin \
564 -dc -i /var/roundup/sysadmin get status issue3,issue1`
565 unread deferred
567 Also the tautological::
569 shell% roundup-admin get name \
570 `roundup-admin -dc get status \`roundup-admin -dc find issue \
571 status=chatting\``
572 chatting
573 chatting
575 Remember the roundup commands that accept multiple designators accept
576 them ',' separated so using '-dc' is almost always required.
578 -----------------
580 Back to `Table of Contents`_
582 .. _`Table of Contents`: index.html
583 .. _`customisation documentation`: customizing.html