<html><head>
<title>Roundup: an Issue-Tracking System for Knowledge Workers</title>
</head><body>
<h1 align=center>Roundup (0.3.1)</h1>
<h3 align=center>An Issue-Tracking System for Knowledge Workers</h2>
<h1>Contents</h1>
<ul>
<li><a href="overview.html">Overview</a> (Initial submission to SC Track)
<li><a href="#installation">Installation</a>
<ul>
<li><a href="#requires">Prerequisites</a>
<li><a href="#getting">Getting Roundup</a>
<li><a href="#installing">Installing Roundup</a>
</ul>
<li><a href="#starting">Getting Started</a>
<ul>
<li><a href="#instance">The Instance</a>
<li><a href="#startcmd">Command Line Tool</a>
<li><a href="#startmail">E-Mail Interface</a>
<li><a href="#startweb">Web Interface</a>
<li><a href="#users">Users and Access Control</a> (Users and permissions, Adding users)
<li><a href="#issues">Issues</a>
</ul>
<li><a href="#guide">User Guide</a>
<ul>
<li><a href="#cmd">Command Line Tool</a>
<li><a href="#web">Web Interface</a>
<li><a href="#mail">E-Mail Gateway</a> (Message content summary, Address handling, Performing Actions)
</ul>
<li><a href="#custom">Customising Roundup</a>
<ul>
<li><a href="#config">Instance Configuration</a>
<li><a href="#custinst">Instance Schema</a> (Creating a new information store)
<li><a href="#custweb">Web Interface</a> (Displaying properties, Index views, Item views)
</ul>
<li><a href="spec.html">Roundup's Design Document</a> ("Implementation Guide")
<li><a href="#ack">Acknowledgements</a>
</ul>
<p><hr>
<h1><a name="installation">Installation</a></h1>
<h2><a name="requires">Prerequisites</a></h2>
<p>
Python 2.1.1 is required for the correct operation of roundup.
</p>
<p>
Download the latest version from
<a href="http://www.python.org/">http://www.python.org/</a>.
</p>
<h2><a name="getting">Getting Roundup</a></h2>
Download the latest version from
<a href="http://roundup.sf.net/">http://roundup.sf.net/</a>.
<h2><a name="installing">Installing Roundup</a></h2>
<ol>
<li>Run:
<br><tt>python setup.py install</tt>
<li>If you would prefer the scripts installed in somewhere other than
<tt>/usr/local/bin</tt>, add <tt>"--install-scripts=<dir>"</tt>
to the command:
<br><tt>python setup.py install --install-scripts=<dir></tt>
<li>The command:
<br><tt>python setup.py install --help</tt>
<br>gives all the options available for installation.
</ol>
<p><hr>
<h1><a name="starting">Getting Started</a></h1>
The following instructions assume that you have installed roundup. If you
haven't, you may still proceed - just preface all commands with "./"
ie. "./roundup-admin init".
<h2><a name="instance">The Instance</a></h2>
We'll be referring to the term <em>instance</em> a lot from now on. An
instance is
a directory in your filesystem that is where all the information about a
live issue tracker database is stored. The data that is entered as issues,
the users who access the database and the definition of the database itself
all reside there:
<ol>
<li><strong>Hyperdatabase</strong>
<br>This is the lowest component of Roundup and is where all the
issues, users, file attachments and messages are stored.
<li><strong>Database schema</strong>
<br>This describes the content of the hyperdatabase - what fields are
stored for issues, what user information, etc. Being stored in the
instance, this allows it to be customised for a particular application.
It also means that changes in the Roundup core code do not affect a
running instance.
<li><strong>Web Interface</strong>
<br>The web interface templates are defined in the instance too - and
the actual CGI interface class is defined (mostly using base classes in
the Roundup core code) so it, like the database, may be customised for
each instance in use.
</ol>
Instances are created using the <tt>roundup-admin</tt> tool.
<h2><a name="startcmd">Command Line Tool</a></h2>
To initiliase a new instance, run <tt>roundup-admin init</tt>. You will be
asked a series of questions:
<ol>
<li>Instance home directory
<li>Schema to use
<li>Database back-end to use
<li>Administration user "admin" password.
</ol>
You should also think about whether there is going to be controlled access
to the instance on the machine the instance is running on. That is, who can
actually make changes to the database using the roundup-admin tool. See
the section on <a href="#users">Users and Access Control</a> for
information on how to secure your instance from the start.
<p>
Roundup is configurable using an instance_config.py file in the instance home.
It should be edited before roundup is used, and may have the following
variable declarations:
<ol>
<li>MAILHOST
<br>The SMTP mail host that roundup will use to send mail
<li>MAIL_DOMAIN
<br>The domain name used for email addresses
<li>ISSUE_TRACKER_WEB
<br>The web address of the issue tracker's web interface
</ol>
<p>
The email addresses used by the system by default are:
<ol>
<li>ISSUE_TRACKER_EMAIL - issue_tracker@MAIL_DOMAIN
<br>submissions of issues
<li>ADMIN_EMAIL - roundup-admin@MAIL_DOMAIN
<br>roundup's internal use (problems, etc)
</ol>
<h2><a name="startmail">E-Mail Interface</a></h2>
<h3>Setup 1: As a mail alias pipe process</h3>
Set up a mail alias called "issue_tracker" as (include the quote marks):
<blockquote>
<tt>"|/usr/bin/python /usr/local/bin/roundup-mailgw <instance_home>"</tt>
</blockquote>
In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh
so sendmail will accept the pipe command. In that case, symlink
/etc/smrsh/roundup-mailgw to /usr/local/bin/roundup-mailgw and change the
command to:
<blockquote>
<tt>|roundup-mailgw <instance_home></tt>
</blockquote>
To test the mail gateway on unix systems, try:
<blockquote>
<tt>echo test |mail -s '[issue] test' issue_tracker@your.domain</tt>
</blockquote>
<h3>Setup 2: As a regular cron job using a mailbox source</h3>
Set the roundup-mailgw up to run every 10 minutes or so. For example:
<blockquote>
<tt>10 * * * * /usr/local/bin/roundup-mailgw <instance_home> mailbox <mail_spool_file></tt>
</blockquote>
Where the mail_spool_file argument is the location of the roundup
submission user's mail spool. On most systems, the spool for a user
"issue_tracker" will be "/var/mail/issue_tracker".
<h3>Setup 3: As a regular cron job using a POP source</h3>
To retrieve from a POP mailbox, use a similar cron entry to the mailbox
one:
<blockquote>
<tt>10 * * * * /usr/local/bin/roundup-mailgw <instance_home> pop <pop_spec></tt>
</blockquote>
where pop_spec is "username:password@server" that specifies the roundup
submission user's POP account name, password and server.
<h2><a name="startweb">Web Interface</a></h2>
This software will work through apache or stand-alone.
<p>
<strong>Stand-alone:</strong>
<ol>
<li>Edit roundup-server at the top - ROUNDUP_INSTANCE_HOMES needs to know
about your instance. You may also specify the values for
ROUNDUP_INSTANCE_HOMES on the command-line using "name=home" pairs.
<li><tt>roundup-server [hostname port]</tt> (hostname may be "")
<li>Load up the page <tt>/<instance name>/index</tt> where
instance name is the
name you nominated in <tt>ROUNDUP_INSTANCE_HOMES</tt>.
</ol>
<strong>Apache:</strong>
<ol>
<li>The CGI script is found in the cgi-bin directory of the roundup
distribution.
</li>
<li>Make sure roundup.cgi is executable. Edit it at the top -
ROUNDUP_INSTANCE_HOMES needs to know about your instance.
</li>
<li>Edit your /etc/httpd/conf/httpd.conf and make sure that the
/home/httpd/html/roundup/roundup.cgi script will be treated as a CGI
script.
</li>
<li>Re-start your apache to re-load the config if necessary.
</li>
<li>Load up the page "/roundup/roundup.cgi/<instance name>/index" where
instance name is the name you nominated in ROUNDUP_INSTANCE_HOMES.
</li>
<li>To use the CGI script unchanged, which allows much easier updates,
add these directives to your "httpd.conf":
<pre>
SetEnv ROUNDUP_LOG "/var/log/roundup.log"
SetEnv ROUNDUP_INSTANCE_HOMES "Default=/usr/local/share/roundup/instances/Default"
SetEnv ROUNDUP_DEBUG "0"
</pre>
</li>
<li>On Windows, write a batch file "roundup.bat" similar to the one below
and place it into your cgi-bin directory:
<pre>
@echo off
set ROUNDUP_LOG=c:\Python21\share\roundup\cgi.log
set ROUNDUP_INSTANCE_HOMES=Default=c:\Python21\share\roundup\instances\Default;
set ROUNDUP_DEBUG=0
c:\Python21\python.exe c:\Python21\share\roundup\cgi-bin\roundup.cgi
</pre>
</li>
</ol>
<h2><a name="users">Users</a></h2>
<h3>Users and permissions</h3>
By default, roundup automatically creates one user when the instance
database is initialised (using roundup-admin init). The user is "admin" and
the password is the one you supply at that time.
<p>
If users attempt to use roundup in any manner and are not identified to
roundup, they will be using the database in a read-only mode. That is, if
roundup doesn't know who they are, they can't change anything. This has the
following repurcussions:
<dl>
<dt><strong>Command-line interface</strong>
<dd>The data modification commands (create, init, retire, set) are
performed as the "admin" user. It is therefore important that the database
be protected by the filesystem if protection is required. On a Unix system,
the easiest and most flexible method of doing so is:
<ol>
<li>Add a new user and group to your system (e.g. "issue_tracker")
<li>When creating a new instance home, use the following commands
(substituting instance_home for the directory you want to use):<br>
<pre>
mkdir instance_home
chown issue_tracker:issue_tracker instance_home
chmod g+rwxs instance_home
roundup-admin -i instance_home init
</pre>
<li>Now, edit the /etc/group line for the issue_tracker group so it includes
the unix logins of all the users who are going to administer your roundup
instance. If you're running the web or mail gateways, then be sure to
include those users in the group too (on some Linux systems, these
users are "www" or "apache" and "mail".)
</ol>
<dt><strong>E-Mail interface</strong>
<dd>Users are identified by e-mail address - a new user entry will be
created for any e-mail address that is not recognised, so users are
<em>always</em> identified by roundup.
<dt><strong>Web interface</strong>
<dd>Unidentified users have read-only access. If the users database has an
entry with the username "anonymous", then unidentified users are
automatically logged in as that user. This gives them write access.
</dl>
<p>
*** anonymous access and the ANONYMOUS_* configuratins.
<h3>Adding users</h3>
To add users, use one of the following interfaces:
<ol>
<li>On the web, access the URL <tt>.../<instance name>/newuser</tt>
to bring up a form which may be used to add a new user.
<li>On the command-line, use:
<br><tt>roundup-admin -i <instance home> create user
username=bozo password=bozo address=richard@clown.org</tt>
<br>Supply the admin username and password. roundup-admin will print the
id of the new user.
<li>Any e-mail sent to roundup from an address that doesn't match an
existing user in the database will result in a new user entry being
created for that user.
</ol>
<h2><a name="issues">Issues</a></h2>
To add issues, use one of the following interfaces:
<ol>
<li>On the web, access the URL <tt>.../<instance name>/newissue</tt>
to bring up a form which may be used to add a new issue.
<li>On the command-line, use:
<br><tt>roundup-admin -i <instance home> create issue
title="test issue"</tt>
<br>Supply the admin username and password. roundup-admin will print the
id of the new issue.
<li>Any e-mail sent to roundup with the subject line containing [issue]
will automatically created a new issue in the database using the
contents of the e-mail.
</ol>
<p><hr>
<h1><a name="guide">User Guide</a></h1>
<h2><a name="cmd">Command Line Tool</a></h2>
Usage:
<tt>roundup-admin [-i instance home] [-u login] [-c] <command>
<arguments></tt>
<p>
<table><tr><th colspan=2>Options:</th></tr>
<tr><td>-i instance home </td><td>specify the issue tracker "home directory" to administer
</td></tr>
<tr><td>-u </td><td>the user[:password] to use for commands
</td></tr>
<tr><td>-c </td><td>when outputting lists of data, just comma-separate them
</td></tr>
</table>
<p>
<table width=100% border=1 cellspacing=0>
<tr><th colspan=2>Command Help</th></tr>
<tr><td valign=top><strong>commit</strong></td>
<td><tt>Usage: commit</tt><p>
<pre>
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.
</pre></td></tr>
<tr><td valign=top><strong>create</strong></td>
<td><tt>Usage: create classname property=value ...</tt><p>
<pre>
This creates a new entry of the given class using the property
name=value arguments provided on the command line after the "create"
command.
</pre></td></tr>
<tr><td valign=top><strong>display</strong></td>
<td><tt>Usage: display designator</tt><p>
<pre>
This lists the properties and their associated values for the given
node.
</pre></td></tr>
<tr><td valign=top><strong>export</strong></td>
<td><tt>Usage: export class[,class] destination_dir</tt><p>
<pre>
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.
</pre></td></tr>
<tr><td valign=top><strong>find</strong></td>
<td><tt>Usage: find classname propname=value ...</tt><p>
<pre>
Find the nodes of the given class with a given link property value. The
value may be either the nodeid of the linked node, or its key value.
</pre></td></tr>
<tr><td valign=top><strong>get</strong></td>
<td><tt>Usage: get property designator[,designator]*</tt><p>
<pre>
Retrieves the property value of the nodes specified by the designators.
</pre></td></tr>
<tr><td valign=top><strong>help</strong></td>
<td><tt>Usage: help topic</tt><p>
<pre>
commands -- list commands
<command> -- help specific to a command
initopts -- init command options
all -- all available help
</pre></td></tr>
<tr><td valign=top><strong>history</strong></td>
<td><tt>Usage: history designator</tt><p>
<pre>
Lists the journal entries for the node identified by the designator.
</pre></td></tr>
<tr><td valign=top><strong>import</strong></td>
<td><tt>Usage: import class file</tt><p>
<pre>
The file must define the same properties as the class (including having
a "header" line with those property names.) The new nodes 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.)
</pre></td></tr>
<tr><td valign=top><strong>initialise</strong></td>
<td><tt>Usage: initialise [template [backend [admin password]]]</tt><p>
<pre>
The command will prompt for the instance 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.
</pre></td></tr>
<tr><td valign=top><strong>list</strong></td>
<td><tt>Usage: list classname [property]</tt><p>
<pre>
Lists all instances 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.
</pre></td></tr>
<tr><td valign=top><strong>retire</strong></td>
<td><tt>Usage: retire designator[,designator]*</tt><p>
<pre>
This action indicates that a particular node is not to be retrieved by
the list or find commands, and its key value may be re-used.
</pre></td></tr>
<tr><td valign=top><strong>rollback</strong></td>
<td><tt>Usage: rollback</tt><p>
<pre>
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.
</pre></td></tr>
<tr><td valign=top><strong>set</strong></td>
<td><tt>Usage: set designator[,designator]* propname=value ...</tt><p>
<pre>
Sets the property to the value for all designators given.
</pre></td></tr>
<tr><td valign=top><strong>specification</strong></td>
<td><tt>Usage: specification classname</tt><p>
<pre>
This lists the properties for a given class.
</pre></td></tr>
<tr><td valign=top><strong>table</strong></td>
<td><tt>Usage: table classname [property[,property]*]</tt><p>
<pre>
Lists all instances 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
</pre></td></tr>
</table>
<p>
All commands (except help) require an instance specifier. This is just the path
to the roundup instance you're working with. A roundup instance 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 instance".
<p>
A designator is a classname and a nodeid concatenated, eg. bug1, user10, ...
<p>
Property values are represented as strings in command arguments and in the
printed results:
<ul>
<li>Strings are, well, strings.
<li>Password values will display as their encoded value.
<li>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.
<table>
<tr><th>Input of...</th><th>Means...</th></tr>
<tr><td>"2000-04-17.03:45"</td><td>2000-04-17.08:45:00</td></tr>
<tr><td>"2000-04-17"</td><td>2000-04-17.00:00:00</td></tr>
<tr><td>"01-25"</td><td>yyyy-01-25.00:00:00</td></tr>
<tr><td>"08-13.22:13"</td><td>yyyy-08-14.03:13:00</td></tr>
<tr><td>"11-07.09:32:43"</td><td>yyyy-11-07.14:32:43</td></tr>
<tr><td>"14:25"</td><td>yyyy-mm-dd.19:25:00</td></tr>
<tr><td>"8:47:11"</td><td>yyyy-mm-dd.13:47:11</td></tr>
<tr><td>"."</td><td>"right now"</td></tr>
</table>
<li>Link values are printed as node designators. When given as an argument,
node designators and key strings are both accepted.
<li>Multilink values are printed as lists of node designators joined by commas.
When given as an argument, node designators and key strings are both
accepted; an empty string, a single node, or a list of nodes joined by
commas is accepted.
</ul>
When multiple nodes are specified to the roundup get or roundup set
commands, the specified properties are retrieved or set on all the listed
nodes.
<p>
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.
<p>
Where the command changes data, a login name/password is required. The
login may be specified as either "name" or "name:password".
<ul>
<li>ROUNDUP_LOGIN environment variable
<li>the -u command-line option
</ul>
If either the name or password is not supplied, they are obtained from the
command-line.
<h2><a name="web">Web Interface</a></h2>
Index views may be modified by the following arguments:
<pre>
: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 node properties given by propname
must have (very basic search/filter).
</pre>
<strong>Not sure what to put in here...</strong>
<h2><a name="mail">E-Mail Gateway</a></h2>
<h3>Performing Actions</h3>
The subject line of the incoming message is examined to determine whether
the message is an attempt to create a new item or to discuss an existing
item. A designator enclosed in square brackets is sought as the first thing
on the subject line (after skipping any "Fwd:" or "Re:" prefixes).
<p>
If an item designator (class name and id number) is found there, the newly
created "msg" node is added to the "messages" property for that item, and
any new "file" nodes are added to the "files" property for the item.
<p>
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" node and its "files" property initialized to contain any new "file"
nodes.
<h3>Setting Properties</h3>
The e-mail interface also provides a simple way to set
properties on items. At the end of the subject line,
<em>propname</em><tt>=</tt><em>value</em> pairs can be
specified in square brackets, using the same conventions
as for the <tt>roundup set</tt> shell command.
explanatory message given in the exception.
<h3>Message content</h3>
Incoming messages are examined for multiple parts:
<ul>
<li>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 node. Any parts of other types are each stored in separate files
and given "file" class nodes that are linked to the "msg" node.
<li>In a multipart/alternative message or part, we look for a text/plain
subpart and ignore the other parts.
</ul>
<h4>Message summary</h4>
The "summary" property on message nodes 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.
<h3>Address handling</h3>
All of the addresses in the To: and Cc: headers of the incoming message are
looked up among the user nodes, and the corresponding users are placed in
the "recipients" property on the new "msg" node. The address in the From:
header similarly determines the "author" property of the new "msg"
node. 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 web interface does not permit logins for users with no
passwords.) If we prefer to reject mail from outside sources, we can simply
register an auditor on the "user" class that prevents the creation of user
nodes with no passwords.
<h3>Triggers</h3>
Both cases may trigger detectors (in the first case we are calling the
set() method to add the message to the item's spool; in the second case we
are calling the create() method to create a new node). If an auditor raises
an exception, the original message is bounced back to the sender with the
<h4>Nosy Lists</h4>
A standard detector is provided that watches for additions
to the "messages" property. When a new message is added, the
detector sends it 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.
<p><hr>
<h1><a name="custom">Customising Roundup</a></h1>
Instances have the following structure:
<table>
<tr><td valign=top><strong>instance_config.py</strong></td>
<td>Holds the basic <a href="#config">instance configuration</a></td></tr>
<tr><td valign=top><strong>dbinit.py</strong></td>
<td>Holds the <a href="#custinst">instance schema</a></td></tr>
<tr><td valign=top><strong>interfaces.py</strong></td>
<td>Defines the <a href="#custweb">Web</a> and E-Mail interfaces for the instance</td></tr>
<tr><td valign=top><strong>select_db.py</strong></td>
<td>Selects the database back-end for the instance</td></tr>
<tr><td valign=top><strong>db/</strong></td>
<td>Holds the instance's database</td></tr>
<tr><td valign=top><strong>db/files/</strong></td>
<td>Holds the instance's upload files and messages</td></tr>
<tr><td valign=top><strong>detectors/</strong></td>
<td>Auditors and reactors for this instance</td></tr>
<tr><td valign=top><strong>html/</strong></td>
<td>Web interface <a href="#custweb">templates</a>, images and style sheets</td></tr>
</table>
<h2><a name="config">Instance Configuration</a></h2>
The <tt>instance_config.py</tt> located in your instance home contains the
basic configuration for the web and e-mail components of roundup's
interfaces. This file is a Python module. The default
<tt>instance_config.py</tt> is given below - as you can see, the
MAIL_DOMAIN must be edited before any interaction with the instance is
attempted.
<p>
<pre>
MAIL_DOMAIN=MAILHOST=HTTP_HOST=None
HTTP_PORT=0
# roundup home is this package's directory
INSTANCE_HOME=os.path.split(__file__)[0]
# The SMTP mail host that roundup will use to send mail
if not MAILHOST:
MAILHOST = 'localhost'
# The domain name used for email addresses.
if not MAIL_DOMAIN:
MAIL_DOMAIN = 'fill.me.in.'
# the next two are only used for the standalone HTTP server.
if not HTTP_HOST:
HTTP_HOST = ''
if not HTTP_PORT:
HTTP_PORT = 9080
# This is the directory that the database is going to be stored in
DATABASE = os.path.join(INSTANCE_HOME, 'db')
# This is the directory that the HTML templates reside in
TEMPLATES = os.path.join(INSTANCE_HOME, 'html')
# The email address that mail to roundup should go to
ISSUE_TRACKER_EMAIL = 'issue_tracker@%s'%MAIL_DOMAIN
# The web address that the instance is viewable at
ISSUE_TRACKER_WEB = 'http://some.useful.url/'
# The email address that roundup will complain to if it runs into trouble
ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN
# Somewhere for roundup to log stuff internally sent to stdout or stderr
LOG = os.path.join(INSTANCE_HOME, 'roundup.log')
# Where to place the web filtering HTML on the index page
FILTER_POSITION = 'bottom' # one of 'top', 'bottom', 'top and bottom'
# Deny or allow anonymous access to the web interface
ANONYMOUS_ACCESS = 'deny'
# Deny or allow anonymous users to register through the web interface
ANONYMOUS_REGISTER = 'deny'
# Send nosy messages to the author of the message
MESSAGES_TO_AUTHOR = 'no' # either 'yes' or 'no'
</pre>
<h2><a name="custinst">Instance Schema</a></h2>
<b>Note:</b> if you modify the schema, you'll most likely need to
<a href="#schemarepurcussions">
web interface to reflect your changes</a>.
<p>
An instance schema defines what data is stored in the instance's database.
The two schemas shipped with Roundup turn it into a typical software bug
tracker (the extended schema allowing for support issues as well as bugs).
Schemas are defined using Python code. The "classic" schema looks like
this:
<p>
<pre>
pri = Class(db, "priority", name=String(), order=String())
pri.setkey("name")
pri.create(name="critical", order="1")
pri.create(name="urgent", order="2")
pri.create(name="bug", order="3")
pri.create(name="feature", order="4")
pri.create(name="wish", order="5")
stat = Class(db, "status", name=String(), order=String())
stat.setkey("name")
stat.create(name="unread", order="1")
stat.create(name="deferred", order="2")
stat.create(name="chatting", order="3")
stat.create(name="need-eg", order="4")
stat.create(name="in-progress", order="5")
stat.create(name="testing", order="6")
stat.create(name="done-cbb", order="7")
stat.create(name="resolved", order="8")
keyword = Class(db, "keyword", name=String())
keyword.setkey("name")
user = Class(db, "user", username=String(), password=String(),
address=String(), realname=String(), phone=String(), organisation=String())
user.setkey("username")
user.create(username="admin", password=adminpw, address=instance_config.ADMIN_EMAIL)
msg = FileClass(db, "msg", author=Link("user"), recipients=Multilink("user"),
date=Date(), summary=String(), files=Multilink("file"))
file = FileClass(db, "file", name=String(), type=String())
issue = IssueClass(db, "issue", assignedto=Link("user"),
topic=Multilink("keyword"), priority=Link("priority"), status=Link("status"))
issue.setkey('title')
</pre>
<h3>Classes and Properties - creating a new information store</h3>
In the instance above, we've defined 7 <em>classes</em> of information:
<dl>
<dt><strong>priority</strong>
<dd>Defines the possible levels of urgency for issues.
<dt><strong>status</strong>
<dd>Defines the possible states of processing the issue may be in.
<dt><strong>keyword</strong>
<dd>Initially empty, will hold keywords useful for searching issues.
<dt><strong>user</strong>
<dd>Initially holding the "admin" user, will eventually have an entry
for all users using roundup.
<dt><strong>msg</strong>
<dd>Initially empty, will all e-mail messages sent to or generated by roundup.
<dt><strong>file</strong>
<dd>Initially empty, will all files attached to issues.
<dt><strong>issue</strong>
<dd>Initially emtyp, this is where the issue information is stored.
</dl>
<p>
We define the "priority" and "status" classes to allow two things: reduction
in the amount of information stored on the issue and more powerful, accurate
searching of issues by priority and status. By only requiring a link on
the issue (which is stored as a single number) we reduce the chance
that someone mis-types a priority or status - or simply makes a new one
up.
<h4>Class and Nodes</h4>
A <em>Class</em> defines a particular class (or type) of data that will be
stored in the database. A class comprises one or more properties, which
given the information about the class nodes.
<p>
The actual data entered into the database, using <em>class</em>.create()
are called <em>nodes</em>. They have a special immutable property called
id. We sometimes refer to this as the <em>nodeid</em>.
<h4>Properties</h4>
A Class is comprised of one or more <em>properties</em> of the following types:
<ul>
<li><em>String</em> properties are for storing arbitrary-length
strings.
<li><em>Password</em> properties are for storing encoded arbitrary-length
strings. The default encoding is defined on the roundup.password.Password
class.
<li><em>Date</em> properties store date-and-time stamps.
Their values are Timestamp objects.
<li>A <em>Link</em> property refers to a single other node
selected from a specified class. The class is part of the property;
the value is an integer, the id of the chosen node.
<li>A <em>Multilink</em> property refers to possibly many nodes
in a specified class. The value is a list of integers.
</ul>
<h4>FileClass</h4>
FileClasses save their "content" attribute off in a separate file from the
rest of the database. This reduces the number of large entries in the
database, which generally makes databases more efficient, and also allows
us to use command-line tools to operate on the files. They are stored in
the files sub-directory of the db directory in your instance.
<h4>IssueClass</h4>
IssueClasses automatically include the "messages", "files", "nosy", and
"superseder" properties.
<p>
The messages and files properties list the links to the messages and files
related to the issue. The nosy property is a list of links to users who
wish to be informed of changes to the issue - they get "CC'ed" e-mails when
messages are sent to or generated by the issue. The nosy reactor (in the
detectors directory) handles this action. The superceder link indicates an
issue which has superceded this one.
<p>
They also have the dynamically generated
"creation", "activity" and "creator" properties.
<p>
The value of the "creation" property is the date when a node was created,
and the value of the "activity" property is the date when any property on
the node was last edited (equivalently, these are the dates on the first
and last records in the node's journal). The "creator" property holds a
link to the user that created the issue.
<h4>setkey(property)</h4>
Select a String property of the class to be the key property. The key
property muse be unique, and allows references to the nodes in the class by
the content of the key property. That is, we can refer to users by their
username, e.g. let's say that there's an issue in roundup, issue 23. There's
also a user, richard who happens to be user 2. To assign an issue to him,
we could do either of:
<p>
<blockquote><tt>roundup-admin set issue assignedto=2</tt></blockquote>
<p>
or
<p>
<blockquote><tt>roundup-admin set issue
assignedto=richard</tt></blockquote>
<p>
Note, the same thing can be done in the web and e-mail interfaces.
<h4>create(information)</h4>
Create a node in the database. This is generally used to create nodes in
the "definitional" classes like "priority" and "status".
<h2><a name="custweb">Web Interface</a></h2>
The web interface works behind the cgi-bin/roundup.cgi or roundup-server
scripts. In both cases, the scripts determine which instance is being
accessed (the first part of the URL path inside the scope of the CGI
handler) and pass control on to the instance interfaces.Client class which
handles the rest of the access through its main() method. This means that
you can do pretty much anything you want as a web interface to your
instance.
<p>
Most customisation of the web view can be done by modifying the templates
in the instance html directory. These are divided into index, item and
newitem views. The newitem view is optional - the item view will be used if
the newitem view doesn't exist.
<h3><a name="schemarepurcussions">Repurcussions of changing the instance schema</a></h3>
If you choose to <a href="custinst">change the instance schema</a> you will need to
ensure the web interface knows about it:
<ol>
<li>Index, item and filter pages for the relevant classes may need to have properties
added or removed,
<li>The default page header relies on the existence of, and some values of the
priority, status, assignedto and activity classes. If you change any of these (specifically
if you remove any of the classes or their default values) you will need to implement your
own pagehead() method in your instance's interfaces.py module.
</ol>
<h3>Displaying Properties</h3>
<p>
Properties appear in the user interface in three contexts:
in indices, in editors, and as filters. For each type of
property, there are several display possibilities. For example,
in an index view, a string property may just be printed as
a plain string, but in an editor view, that property should
be displayed in an editable field.
<p>
The display of a property is handled by functions in
the htmltemplate module.
<p>
Displayer functions are triggered by <tt><display></tt>
tags in templates. The <tt>call</tt> attribute of the tag
provides a Python expression for calling the displayer
function. The three standard arguments are inserted in
front of the arguments given. For example, the occurrence of
<blockquote><pre><small
> <display call="plain('status')">
</small></pre></blockquote>
in a template triggers a call the "plain" function. The displayer
functions can accept extra arguments to further specify
details about the widgets that should be generated. By defining new
displayer functions, the user interface can be highly customized.
<p>
<table border=1 cellspacing=0>
<tr><th colspan=2>The displayer functions are</th></tr>
<tr><td valign="top"><strong>plain</strong></td>
<td>Display a String property directly.
<p>
Display a Date property in a specified time zone with an option
to omit the time from the date stamp.
<p>
For a Link or Multilink
property, display the key strings of the linked nodes (or the
ids if the linked class has no key property).
<p>
<em>Options:</em><br>
escape (boolean) - HTML-escape the resulting text.
</td></tr>
<tr><td valign="top"><strong>field</strong></td>
<td>Display a property like the
<strong>plain</strong> displayer above, but in a form field
to be edited. Strings, Dates and Intervals use TEXT fields, Links use
SELECT fields and Multilinks use SELECT MULTIPLE fields.
<p>
<em>Options:</em><br>
size (number) - width of TEXT fields.<br>
height (number) - number of nows in SELECT MULTIPLE tags.<br>
showid (boolean) - true includes the id of linked nodes in the SELECT
MULTIPLE fields.
</td></tr>
<tr><td valign="top"><strong>menu</strong></td>
<td>For a Links and Multilinks, display the same field as would be
generated using <strong>field</strong>.
</td></tr>
<tr><td valign="top"><strong>link</strong></td>
<td>For a Link or Multilink property, display the names of the linked
nodes, hyperlinked to the item views on those nodes.
<p>
For other properties, link to this node with the property as the text.
<p>
<em>Options:</em><br>
property (property name) - the property to use in the second case.
</td></tr>
<tr><td valign="top"><strong>count</strong></td>
<td>For a Multilink property, display
a count of the number of links in the list.
<p>
<em>Arguments:</em><br>
property (property name) - the property to use.
</td></tr>
<tr><td valign="top"><strong>reldate</strong></td>
<td>Display a Date property in terms
of an interval relative to the current date (e.g. "+ 3w", "- 2d").
<p>
<em>Arguments:</em><br>
property (property name) - the property to use.
<p>
<em>Options:</em><br>
pretty (boolean) - display the relative date in an English form.
</td></tr>
<tr><td valign="top"><strong>download</strong></td>
<td>For a Link or Multilink property, display the names of the linked
nodes, hyperlinked to the item views on those nodes.
<p>
For other properties, link to this node with the property as the text.
<p>
In all cases, append the name (key property) of the item to the path so it
is the name of the file being downloaded.
<p>
<em>Arguments:</em><br>
property (property name) - the property to use.
</td></tr>
<tr><td valign="top"><strong>checklist</strong></td>
<td>For a Link or Multilink property,
display checkboxes for the available choices to permit filtering.
<p>
<em>Arguments:</em><br>
property (property name) - the property to use.
</td></tr>
<tr><td valign="top"><strong>note</strong></td>
<td>Display the special notes field, which is a text area for entering a
note to go along with a change.
</td></tr>
<tr><td valign="top"><strong>list</strong></td>
<td>List the nodes specified by property using the standard index for
the class.
<p>
<em>Arguments:</em><br>
property (property name) - the property to use.
</td></tr>
<tr><td valign="top"><strong>history</strong></td>
<td>List the history of the item.
</td></tr>
<tr><td valign="top"><strong>submit</strong></td>
<td>Add a submit button for the item.
</td></tr>
</table>
<h3>Index Views</h3>
<p>An index view contains two sections: a filter section
and an index section.
The filter section provides some widgets for selecting
which items appear in the index. The index section is
a table of items.
<h4>Index View Specifiers</h4>
<p>An index view specifier (URL fragment) looks like this (whitespace
has been added for clarity):
<blockquote><pre><small
>/issue?status=unread,in-progress,resolved&
topic=security,ui&
:group=+priority&
:sort=-activity&
:filters=status,topic&
:columns=title,status,fixer
</small></pre></blockquote>
<p>The index view is determined by two parts of the
specifier: the layout part and the filter part.
The layout part consists of the query parameters that
begin with colons, and it determines the way that the
properties of selected nodes are displayed.
The filter part consists of all the other query parameters,
and it determines the criteria by which nodes
are selected for display.
<p>The filter part is interactively manipulated with
the form widgets displayed in the filter section. The
layout part is interactively manipulated by clicking
on the column headings in the table.
<p>The filter part selects the <em>union</em> of the
sets of items with values matching any specified Link
properties and the <em>intersection</em> of the sets
of items with values matching any specified Multilink
properties.
<p>The example specifies an index of "issue" nodes.
Only items with a "status" of <em>either</em>
"unread" or "in-progres" or "resolved" are displayed,
and only items with "topic" values including <em>both</em>
"security" <em>and</em> "ui" are displayed. The items
are grouped by priority, arranged in ascending order;
and within groups, sorted by activity, arranged in
descending order. The filter section shows filters
for the "status" and "topic" properties, and the
table includes columns for the "title", "status", and
"fixer" properties.
<p>Associated with each item class is a default
layout specifier. The layout specifier in the above
example is the default layout to be provided with
the default bug-tracker schema described above in
section 4.4.
<h4>Filter Section</h4>
<p>The template for a filter section provides the
filtering widgets at the top of the index view.
Fragments enclosed in <tt><property></tt>...<tt></property></tt>
tags are included or omitted depending on whether the
view specifier requests a filter for a particular property.
<p>A property must appear in the filter template for it to be available
as a filter.
<p>Here's a simple example of a filter template.
<blockquote><pre><small><property name=status>
<display call="checklist('status')">
</property>
<br>
<property name=priority>
<display call="checklist('priority')">
</property>
<br>
<property name=fixer>
<display call="menu('fixer')">
</property></small></pre></blockquote>
<p>
The standard index generation code appends a section to the index pages
which allows selection of the filters - from those which are defined in the
filter template.
<h4>Index Section</h4>
<p>The template for an index section describes one row of
the index table.
Fragments enclosed in <tt><property></tt>...<tt></property></tt>
tags are included or omitted depending on whether the
view specifier requests a column for a particular property.
The table cells should contain <tt><display></tt> tags
to display the values of the item's properties.
<p>Here's a simple example of an index template.
<blockquote><pre><small><tr>
<property name=title>
<td><display call="plain('title', max=50)"></td>
</property>
<property name=status>
<td><display call="plain('status')"></td>
</property>
<property name=fixer>
<td><display call="plain('fixer')"></td>
</property>
</tr></small></pre></blockquote>
<h4>Sorting</h4>
<p>String and Date values are sorted in the natural way.
Link properties are sorted according to the value of the
"order" property on the linked nodes if it is present; or
otherwise on the key string of the linked nodes; or
finally on the node ids. Multilink properties are
sorted according to how many links are present.
<h3>Item Views</h3>
<p>An item view contains an editor section and a spool section.
At the top of an item view, links to superseding and superseded
items are always displayed.
<h4>Editor Section</h4>
<p>The editor section is generated from a template
containing <tt><display></tt> tags to insert
the appropriate widgets for editing properties.
<p>Here's an example of a basic editor template.
<blockquote><pre><small><table>
<tr>
<td colspan=2>
<display call="field('title', size=60)">
</td>
</tr>
<tr>
<td>
<display call="field('fixer', size=30)">
</td>
<td>
<display call="menu('status')>
</td>
</tr>
<tr>
<td>
<display call="field('nosy', size=30)">
</td>
<td>
<display call="menu('priority')>
</td>
</tr>
<tr>
<td colspan=2>
<display call="note()">
</td>
</tr>
</table>
</small></pre></blockquote>
<p>As shown in the example, the editor template can also
request the display of a "note" field, which is a
text area for entering a note to go along with a change.
<p>When a change is submitted, the system automatically
generates a message describing the changed properties.
<p>If a note is given in the "note" field, the note is
appended to the description. The message is then added
to the item's message spool (thus triggering the standard
detector to react by sending out this message to the nosy list).
<p>
The message also displays all of the property values on the
item and indicates which ones have changed.
An example of such a message might be this:
<blockquote><pre>
Polly's taken a turn for the worse - this is now really important!
-----
title: Polly Parrot is dead
priority: critical
status: unread -> in-progress
fixer: terry
keywords: parrot,plumage,perch,nailed,dead
</pre></blockquote>
<h4>Spool Section</h4>
<p>The spool section lists messages in the item's "messages"
property. The index of messages displays the "date", "author",
and "summary" properties on the message nodes, and selecting a
message takes you to its content.
<p>The <property> tag used in the index may also be used here -
it checks to see if the nominated Multilink property has any entries.
This can be used to eliminate sections of the spool section if the
property has no entries.
<blockquote><pre>
<property name="files">
<tr class="strong-header">
<td><b>Files</b></td>
</tr>
<tr>
<td><display call="list('files')"></td>
</tr>
</property>
</pre></blockquote>
<p><hr>
<h1><a name="ack">Acknowledgements</a></h1>
Go Ping, you rock! Also, go Bizar Software for letting me implement this
system on their time.
<p> </p>
<hr>
$Id: index.html,v 1.27 2002-01-23 05:10:27 richard Exp $
<p> </p>
</body></html>