========== User Guide ========== :Version: $Revision: 1.6 $ .. contents:: Note: this document will refer to *issues* as the primary store of information in the tracker. This is the default of the classic template, bubt may vary in any given installation. Web Interface ------------- Index views may be modified by the following arguments: +-----------+--------------------------------------------------------------+ | :sort | sort by prop name, optionally preceeded with '-' | | | to give descending or nothing for ascending sorting. | +-----------+--------------------------------------------------------------+ | :group | group by prop name, optionally preceeded with '-' or | | | to sort in descending or nothing for ascending order. | +-----------+--------------------------------------------------------------+ | :filter | selects which props should be displayed in the filter | | | section. Default is all. | +-----------+--------------------------------------------------------------+ | :columns | selects the columns that should be displayed. | | | Default is all. | +-----------+--------------------------------------------------------------+ | propname | selects the values the item properties given by propname | | | must have (very basic search/filter). | +-----------+--------------------------------------------------------------+ Searching ~~~~~~~~~ TODO: some information about how searching works Access Controls ~~~~~~~~~~~~~~~ Managing Issues ~~~~~~~~~~~~~~~ TODO: some mention of how the various widgets work E-Mail Gateway -------------- E-mail sent to Roundup is examined for several pieces of information: 1. `subject-line information`_ identifying the purpose of the e-mail 2. `e-mail message content`_ which is to be extracted 3. e-mail attachments which should be associated with the message Subject-line information ~~~~~~~~~~~~~~~~~~~~~~~~ The subject line of the incoming message is examined to find one of: 1. the item that the message is responding to, 2. the type of item the message should create, or 3. we default the item class and try some trickiness If the subject line contains a prefix in ``[square brackets]`` then we're looking at case 1 or 2 above. Note that any "re:" or "fwd:" prefixes are stripped off the subject line before we start looking for real information. If an item designator (class name and id number, for example ``issue123``) is found there, a new "msg" item is added to the "messages" property for that item, and any new "file" items are added to the "files" property for the item. If just an item class name is found there, we attempt to create a new item of that class with its "messages" property initialized to contain the new "msg" item and its "files" property initialized to contain any new "file" items. The third case above - where no ``[information]`` is provided, the tracker's ``MAIL_DEFAULT_CLASS`` configuration variable defines what class of item the message relates to. We try to match the subject line to an existing item of the default class, and if there's a match, the message is related to that matched item. If not, then a new item of the default class is created. Setting Properties :::::::::::::::::: The e-mail interface also provides a simple way to set properties on items. At the end of the subject line, propname=value pairs can be specified in square brackets, using the same conventions as for the roundup set shell command. For example, - setting the priority of an issue:: Subject: Re: [issue1] the coffee machine is broken! [priority=urgent] - adding yourself to a nosy list:: Subject: Re: [issue2] we're out of widgets [nosy=+richard] - setting the nosy list to just you:: Subject: Re: [issue2] we're out of widgets [nosy=richard] - removing yourself from a nosy list:: Subject: Re: [issue2] we're out of widgets [nosy=-richard] In all cases, the message relates to issue 2. The ``Re:`` prefix is stripped off. E-Mail Message Content ~~~~~~~~~~~~~~~~~~~~~~ Roundup only associates plain text (MIME type ``text/plain``) as messages for items. Any other parts of a message are associated as downloadable files. If no plain text part is found, the message is rejected. To do this, incoming messages are examined for multiple parts: * In a multipart/mixed message or part, each subpart is extracted and examined. The text/plain subparts are assembled to form the textual body of the message, to be stored in the file associated with a "msg" class item. Any parts of other types are each stored in separate files and given "file" class items that are linked to the "msg" item. * In a multipart/alternative message or part, we look for a text/plain subpart and ignore the other parts. If the message is a response to a previous message, and contains quoted sections, then these will be stripped out of the message if the ``EMAIL_KEEP_QUOTED_TEXT`` configuration variable is set to ``'no'``. Message summary ::::::::::::::: The "summary" property on message items is taken from the first non-quoting section in the message body. The message body is divided into sections by blank lines. Sections where the second and all subsequent lines begin with a ">" or "|" character are considered "quoting sections". The first line of the first non-quoting section becomes the summary of the message. Address handling ~~~~~~~~~~~~~~~~ All of the addresses in the ``To:`` and ``Cc:`` headers of the incoming message are looked up among the tracker users, and the corresponding users are placed in the "recipients" property on the new "msg" item. The address in the ``From:`` header similarly determines the "author" property of the new "msg" item. The default handling for addresses that don't have corresponding users is to create new users with no passwords and a username equal to the address. The addresses mentioned in the ``To:``, ``From:`` and ``Cc:`` headers of the message may be added to the `nosy list`_ depending on: ``ADD_AUTHOR_TO_NOSY`` Does the author of a message get placed on the nosy list automatically? If 'new' is used, then the author will only be added when a message creates a new issue. If 'yes', then the author will be added on followups too. If 'no', they're never added to the nosy. ``ADD_RECIPIENTS_TO_NOSY`` Do the recipients (To:, Cc:) of a message get placed on the nosy list? If 'new' is used, then the recipients will only be added when a message creates a new issue. If 'yes', then the recipients will be added on followups too. If 'no', they're never added to the nosy. Nosy List ::::::::: The nosy list watches for additions to the "messages" property of items. When a new message is added, it is sent to all the users on the "nosy" list for the item that are not already on the "recipients" list of the message. Those users are then appended to the "recipients" property on the message, so multiple copies of a message are never sent to the same user. The journal recorded by the hyperdatabase on the "recipients" property then provides a log of when the message was sent to whom. If the author of the message is also in the nosy list for the item that the message is attached to, then the config var ``MESSAGES_TO_AUTHOR`` is queried to determine if they get a nosy list copy of the message too. Command Line Tool ----------------- Usage: ``roundup-admin [-i tracker home] [-u login] [-c] `` Options: -i tracker home specify the issue tracker "home directory" to administer -u the ``user[:password]`` to use for commands -c when outputting lists of data, comma-separate them +-----------------------------------------------------------------------------+ | Command Help | +=============+===============================================================+ |commit |Usage: commit | | |The changes made during an interactive session are not | | |automatically written to the database - they must be committed | | |using this command. | | | | | |One-off commands on the command-line are automatically | | |committed if they are successful. | +-------------+---------------------------------------------------------------+ |create |Usage: create classname property=value ... | | |This creates a new entry of the given class using the property | | |name=value arguments provided on the command line after the | | |"create" command. | +-------------+---------------------------------------------------------------+ |display |Usage: display designator | | |This lists the properties and their associated values for the | | |given item. | +-------------+---------------------------------------------------------------+ |export |Usage: export class[,class] destination dir | | |This action exports the current data from the database into | | |tab-separated-value files that are placed in the nominated | | |destination | | |directory. The journals are not exported. | +-------------+---------------------------------------------------------------+ |find |Usage: find classname propname=value ... | | |Find the items of the given class with a given link property | | |value. The | | |value may be either the itemid of the linked item, or its key | | |value. | +-------------+---------------------------------------------------------------+ |get |Usage: get property designator[,designator]* | | |Retrieves the property value of the items specified by the | | |designators. | +-------------+---------------------------------------------------------------+ |help |Usage: help topic | | |commands -- list commands | | |x -- help specific to a command | | |initopts -- init command options | | |all -- all available help | +-------------+---------------------------------------------------------------+ |history |Usage: history designator | | |Lists the journal entries for the item identified by the | | |designator. | +-------------+---------------------------------------------------------------+ |import |Usage: import class file | | |The file must define the same properties as the class | | |(including having | | |a "header" line with those property names.) The new items are | | |added to | | |the existing database - if you want to create a new database | | |using the | | |imported data, then create a new database (or, tediously, | | |retire all | | |the old data.) | +-------------+---------------------------------------------------------------+ |initialise |Usage: initialise [template [backend [admin password]]] | | |The command will prompt for the tracker home directory (if not | | |supplied | | |through INSTANCE HOME or the -i option. The template, backend | | |and admin | | |password may be specified on the command-line as arguments, in | | |that | | |order. | | | | | |See also initopts help. | +-------------+---------------------------------------------------------------+ |list |Usage: list classname [property] | | |Lists all trackers of the given class. If the property is not | | |specified, the "label" property is used. The label property is| | |tried | | |in order: the key, "name", "title" and then the first property,| | |alphabetically. | +-------------+---------------------------------------------------------------+ |retire |Usage: retire designator[,designator]* | | |This action indicates that a particular item is not to be | | |retrieved by | | |the list or find commands, and its key value may be re-used. | +-------------+---------------------------------------------------------------+ |rollback |Usage: rollback | | |The changes made during an interactive session are not | | |automatically written to the database - they must be committed | | |manually. This command undoes all those changes, so a commit | | |immediately after would make no changes to the database. | +-------------+---------------------------------------------------------------+ |set |Usage: set designator[,designator]* propname=value ... | | |Sets the property to the value for all designators given. | +-------------+---------------------------------------------------------------+ |specification|Usage: specification classname | | |This lists the properties for a given class. | +-------------+---------------------------------------------------------------+ |table |Usage: table classname [property[,property]*] | | |Lists all trackers of the given class. If the properties are | | |not | | |specified, all properties are displayed. By default, the column| | |widths | | |are the width of the property names. The width may be | | |explicitly defined | | |by defining the property as "name:width". For example:: | | | | | | roundup> table priority id,name:10 | | | Id Name | | | 1 fatal-bug | | | 2 bug | | | 3 usability | | | 4 feature | +-------------+---------------------------------------------------------------+ All commands (except help) require a tracker specifier. This is just the path to the roundup tracker you're working with. A roundup tracker is where roundup keeps the database and configuration file that defines an issue tracker. It may be thought of as the issue tracker's "home directory". It may be specified in the environment variable ``ROUNDUP_INSTANCE`` or on the command line as "``-i tracker``". A designator is a classname and an itemid concatenated, eg. bug1, user10, ... Property values are represented as strings in command arguments and in the printed results: - Strings are, well, strings. - Password values will display as their encoded value. - Date values are printed in the full date format in the local time zone, and accepted in the full format or any of the partial formats explained below.:: Input of... Means... "2000-04-17.03:45" 2000-04-17.08:45:00 "2000-04-17" 2000-04-17.00:00:00 "01-25" yyyy-01-25.00:00:00 "08-13.22:13" yyyy-08-14.03:13:00 "11-07.09:32:43" yyyy-11-07.14:32:43 "14:25" yyyy-mm-dd.19:25:00 "8:47:11" yyyy-mm-dd.13:47:11 "." "right now" - Link values are printed as item designators. When given as an argument, item designators and key strings are both accepted. - Multilink values are printed as lists of item designators joined by commas. When given as an argument, item designators and key strings are both accepted; an empty string, a single item, or a list of items joined by commas is accepted. When multiple items are specified to the roundup get or roundup set commands, the specified properties are retrieved or set on all the listed items. When multiple results are returned by the roundup get or roundup find commands, they are printed one per line (default) or joined by commas (with the "``-c``" option). Where the command changes data, a login name/password is required. The login may be specified as either "``name``" or "``name:password``". - ``ROUNDUP_LOGIN`` environment variable - the "``-u``" command-line option If either the name or password is not supplied, they are obtained from the command-line. ----------------- Back to `Table of Contents`_ .. _`Table of Contents`: index.html