doc/index.html

   1 <html><head>
   2 <title>Roundup: an Issue-Tracking System for Knowledge Workers</title>
   3 </head><body>
   4
   5 <h1 align=center>Roundup (0.3.0)</h1>
   6 <h3 align=center>An Issue-Tracking System for Knowledge Workers</h2>
   7
   8 <h1>Contents</h1>
   9
  10 <ul>
  11     <li><a href="overview.html">Overview</a> (Initial submission to SC Track)
  12 <li><a href="#installation">Installation</a>
  13     <ul>
  14         <li><a href="#requires">Prerequisites</a>
  15         <li><a href="#getting">Getting Roundup</a>
  16         <li><a href="#installing">Installing Roundup</a>
  17     </ul>
  18 <li><a href="#starting">Getting Started</a>
  19     <ul>
  20         <li><a href="#instance">The Instance</a>
  21         <li><a href="#startcmd">Command Line Tool</a>
  22         <li><a href="#startweb">E-Mail Interface</a>
  23         <li><a href="#startweb">Web Interface</a>
  24         <li><a href="#users">Users and Access Control</a> (Users and permissions, Adding users)
  25         <li><a href="#issues">Issues</a>
  26     </ul>
  27 <li><a href="#guide">User Guide</a>
  28     <ul>
  29         <li><a href="#cmd">Command Line Tool</a>
  30         <li><a href="#web">Web Interface</a>
  31         <li><a href="#mail">E-Mail Gateway</a> (Message content summary, Address handling, Performing Actions)
  32     </ul>
  33 <li><a href="#custom">Customising Roundup</a>
  34     <ul>
  35         <li><a href="#config">Instance Configuration</a>
  36         <li><a href="#custinst">Instance Schema</a> (Creating a new information store)
  37         <li><a href="#custweb">Web Interface</a> (Displaying properties, Index views, Item views)
  38     </ul>
  39 <li><a href="spec.html">Roundup's Design Document</a> ("Implementation Guide")
  40 <li><a href="#ack">Acknowledgements</a>
  41 </ul>
  42
  43 <p><hr>
  44 <h1><a name="installation">Installation</a></h1>
  45
  46
  47 <h2><a name="requires">Prerequisites</a></h2>
  48
  49 <dl>
  50     <dt>Either:
  51     <dd>Python 2.0 with pydoc installed. See http://www.lfw.org/ for pydoc.
  52     <dt>or
  53     <dd>Python 2.1 or later
  54 </dl>
  55
  56 Download the latest version from
  57 <a href="http://www.python.org/">http://www.python.org/</a>.
  58
  59
  60
  61 <h2><a name="getting">Getting Roundup</a></h2>
  62
  63 Download the latest version from
  64 <a href="http://roundup.sf.net/">http://roundup.sf.net/</a>.
  65
  66
  67 <h2><a name="installing">Installing Roundup</a></h2>
  68
  69 <ol>
  70     <li>Run:
  71     <br><tt>python setup.py install</tt>
  72     <li>If you would prefer the scripts installed in somewhere other than
  73     <tt>/usr/local/bin</tt>, add <tt>"--install-scripts=&lt;dir&gt;"</tt>
  74     to the command:
  75     <br><tt>python setup.py install --install-scripts=&lt;dir&gt;</tt>
  76     <li>The command:
  77     <br><tt>python setup.py install --help</tt>
  78     <br>gives all the options available for installation.
  79 </ol>
  80
  81
  82 <p><hr>
  83 <h1><a name="starting">Getting Started</a></h1>
  84
  85 The following instructions assume that you have installed roundup. If you
  86 haven't, you may still proceed - just preface all commands with "./"
  87 ie. "./roundup-admin init".
  88
  89
  90 <h2><a name="instance">The Instance</a></h2>
  91
  92 We'll be referring to the term <em>instance</em> a lot from now on. An
  93 instance is
  94 a directory in your filesystem that is where all the information about a
  95 live issue tracker database is stored. The data that is entered as issues,
  96 the users who access the database and the definition of the database itself
  97 all reside there:
  98 <ol>
  99     <li><strong>Hyperdatabase</strong>
 100     <br>This is the lowest component of Roundup and is where all the
 101     issues, users, file attachments and messages are stored.
 102     <li><strong>Database schema</strong>
 103     <br>This describes the content of the hyperdatabase - what fields are
 104     stored for issues, what user information, etc. Being stored in the
 105     instance, this allows it to be customised for a particular application.
 106     It also means that changes in the Roundup core code do not affect a
 107     running instance.
 108     <li><strong>Web Interface</strong>
 109     <br>The web interface templates are defined in the instance too - and
 110     the actual CGI interface class is defined (mostly using base classes in
 111     the Roundup core code) so it, like the database, may be customised for
 112     each instance in use.
 113 </ol>
 114
 115 Instances are created using the <tt>roundup-admin</tt> tool.
 116
 117 <h2><a name="startcmd">Command Line Tool</a></h2>
 118
 119 To initiliase a new instance, run <tt>roundup-admin init</tt>. You will be
 120 asked a series of questions:
 121
 122 <ol>
 123     <li>Instance home directory
 124     <li>Schema to use
 125     <li>Database back-end to use
 126     <li>Administration user "admin" password.
 127 </ol>
 128
 129 You should also think about whether there is going to be controlled access
 130 to the instance on the machine the instance is running on. That is, who can
 131 actually make changes to the database using the roundup-admin tool. See
 132 the section on <a href="#users">Users and Access Control</a> for
 133 information on how to secure your instance from the start.
 134
 135 <p>
 136
 137 Roundup is configurable using an instance_config.py file in the instance home.
 138 It should be edited before roundup is used, and may have the following
 139 variable declarations:
 140
 141 <ol>
 142     <li>MAILHOST
 143     <br>The SMTP mail host that roundup will use to send mail
 144     <li>MAIL_DOMAIN
 145     <br>The domain name used for email addresses
 146     <li>ISSUE_TRACKER_WEB
 147     <br>The web address of the issue tracker's web interface
 148 </ol>
 149
 150 <p>
 151 The email addresses used by the system by default are:
 152
 153 <ol>
 154     <li>ISSUE_TRACKER_EMAIL - issue_tracker@MAIL_DOMAIN
 155     <br>submissions of issues
 156     <li>ADMIN_EMAIL - roundup-admin@MAIL_DOMAIN
 157     <br>roundup's internal use (problems, etc)
 158 </ol>
 159
 160 <h2><a name="startweb">E-Mail Interface</a></h2>
 161 Set up a mail alias called "issue_tracker" as:
 162 <blockquote>
 163     <tt>|/usr/bin/python /usr/local/bin/roundup-mailgw
 164         &lt;instance_home&gt;</tt>
 165 </blockquote>
 166
 167 In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh
 168 so sendmail will accept the pipe command. In that case, symlink
 169 /etc/smrsh/roundup-mailgw to /usr/local/bin/roundup-mailgw and change the
 170 command to:
 171 <blockquote>
 172     <tt>|roundup-mailgw &lt;instance_home&gt;</tt>
 173 </blockquote>
 174
 175 To test the mail gateway on unix systems, try:
 176
 177 <blockquote>
 178     <tt>echo test |mail -s '[issue] test' issue_tracker@your.domain</tt>
 179 </blockquote>
 180
 181
 182
 183 <h2><a name="startweb">Web Interface</a></h2>
 184 This software will work through apache or stand-alone.
 185 <p>
 186 <strong>Stand-alone:</strong>
 187 <ol>
 188     <li>Edit roundup-server at the top - ROUNDUP_INSTANCE_HOMES needs to know
 189     about your instance. *** command-line option
 190     <li><tt>roundup-server [hostname port]</tt>   (hostname may be "")
 191     <li>Load up the page <tt>/&lt;instance name&gt;/index</tt> where
 192      instance name is the
 193      name you nominated in <tt>ROUNDUP_INSTANCE_HOMES</tt>.
 194 *** command-line option
 195 </ol>
 196
 197 <strong>Apache:</strong>
 198 <ol>
 199     <li>Make sure roundup.cgi is executable. Edit it at the top -
 200     ROUNDUP_INSTANCE_HOMES needs to know about your instance.
 201     <li>Edit your <tt>/etc/httpd/conf/httpd.conf</tt> and make sure that the
 202         <tt>/home/httpd/html/roundup/roundup.cgi</tt> script will be treated as a CGI
 203     script.
 204     <li>Add the following to your <tt>/etc/httpd/conf/httpd.conf</tt>:
 205 <pre>
 206 ------8<------- snip here ------8<-------
 207 RewriteEngine on
 208 RewriteCond %{HTTP:Authorization} ^(.*)
 209 RewriteRule ^/roundup/roundup.cgi(.*) /home/httpd/html/roundup/roundup.cgi$1 [e=HTTP_CGI_AUTHORIZATION:%1,t=application/x-httpd-cgi,l]
 210 ------8<------- snip here ------8<-------
 211 </pre>
 212    note: the RewriteRule must be on one line - no breaks
 213    <li>Re-start your apache to re-load the config
 214    <li>Load up the page <tt>/roundup/roundup.cgi/&lt;instance name&gt;/index</tt> where
 215     instance name is the name you nominated in ROUNDUP_INSTANCE_HOMES.
 216 </ol>
 217
 218
 219 <h2><a name="users">Users</a></h2>
 220
 221 <h3>Users and permissions</h3>
 222 By default, roundup automatically creates one user when the instance
 223 database is initialised (using roundup-admin init). The user is "admin" and
 224 the password is the one you supply at that time.
 225 <p>
 226 If users attempt to use roundup in any manner and are not identified to
 227 roundup, they will be using the database in a read-only mode. That is, if
 228 roundup doesn't know who they are, they can't change anything. This has the
 229 following repurcussions:
 230 <dl>
 231 <dt><strong>Command-line interface</strong>
 232 <dd>The data modification commands (create, init, retire, set) are
 233 performed as the "admin" user. It is therefore important that the database
 234 be protected by the filesystem if protection is required. On a Unix system,
 235 the easiest and most flexible method of doing so is:
 236 <ol>
 237 <li>Add a new user and group to your system (e.g. "issue_tracker")
 238 <li>When creating a new instance home, use the following commands
 239 (substituting instance_home for the directory you want to use):<br>
 240 <pre>
 241 mkdir instance_home
 242 chown issue_tracker:issue_tracker instance_home
 243 chmod g+rwxs instance_home
 244 roundup-admin -i instance_home init
 245 </pre>
 246 <li>Now, edit the /etc/group line for the issue_tracker group so it includes
 247 the unix logins of all the users who are going to administer your roundup
 248 instance. If you're running the web or mail gateways, then be sure to
 249 include those users in the group too (on some Linux systems, these
 250 users are "www" or "apache" and "mail".)
 251 </ol>
 252
 253 <dt><strong>E-Mail interface</strong>
 254 <dd>Users are identified by e-mail address - a new user entry will be
 255 created for any e-mail address that is not recognised, so users are
 256 <em>always</em> identified by roundup.
 257 <dt><strong>Web interface</strong>
 258 <dd>Unidentified users have read-only access. If the users database has an
 259 entry with the username "anonymous", then unidentified users are
 260 automatically logged in as that user. This gives them write access.
 261 </dl>
 262 <p>
 263 *** anonymous access and the ANONYMOUS_* configuratins.
 264
 265 <h3>Adding users</h3>
 266 To add users, use one of the following interfaces:
 267
 268 <ol>
 269     <li>On the web, access the URL <tt>.../&lt;instance name&gt;/newuser</tt>
 270     to bring up a form which may be used to add a new user.
 271     <li>On the command-line, use:
 272     <br><tt>roundup-admin -i &lt;instance home&gt; create user
 273         username=bozo password=bozo address=richard@clown.org</tt>
 274     <br>Supply the admin username and password. roundup-admin will print the
 275     id of the new user.
 276     <li>Any e-mail sent to roundup from an address that doesn't match an
 277     existing user in the database will result in a new user entry being
 278     created for that user.
 279 </ol>
 280
 281
 282
 283 <h2><a name="issues">Issues</a></h2>
 284 To add issues, use one of the following interfaces:
 285
 286 <ol>
 287     <li>On the web, access the URL <tt>.../&lt;instance name&gt;/newissue</tt>
 288     to bring up a form which may be used to add a new issue.
 289     <li>On the command-line, use:
 290     <br><tt>roundup-admin -i &lt;instance home&gt; create issue
 291         title="test issue"</tt>
 292     <br>Supply the admin username and password. roundup-admin will print the
 293     id of the new issue.
 294     <li>Any e-mail sent to roundup with the subject line containing [issue]
 295     will automatically created a new issue in the database using the
 296     contents of the e-mail.
 297 </ol>
 298
 299 <p><hr>
 300 <h1><a name="guide">User Guide</a></h1>
 301 <h2><a name="cmd">Command Line Tool</a></h2>
 302
 303 Usage:
 304 <tt>roundup-admin [-i instance home] [-u login] [-c] &lt;command&gt;
 305     &lt;arguments&gt;</tt>
 306
 307 <p>
 308 <table><tr><th colspan=2>Options:</th></tr>
 309    <tr><td>-i instance home </td><td>specify the issue tracker "home directory" to administer
 310    </td></tr>
 311    <tr><td>-u               </td><td>the user[:password] to use for commands
 312    </td></tr>
 313    <tr><td>-c               </td><td>when outputting lists of data, just comma-separate them
 314     </td></tr>
 315 </table>
 316
 317 <p>
 318 <table border=1 cellspacing=0>
 319 <tr><th colspan=2>Command Help</th></tr>
 320 <tr><td valign=top><strong>history</strong></td>
 321     <td><tt>history designator</tt><p>
 322     Lists the journal entries for the node identified by the designator.
 323 </td></tr>
 324
 325 <tr><td valign=top><strong>find</strong></td>
 326     <td><tt>find classname propname=value ...</tt><p>
 327     Find the nodes of the given class with a given property value. The
 328     value may be either the nodeid of the linked node, or its key value.
 329 </td></tr>
 330
 331 <tr><td valign=top><strong>list</strong></td>
 332     <td><tt>list classname [property]</tt><p>
 333     Lists all instances of the given class along. If the property is not
 334     specified, the  "label" property is used. The label property is tried
 335     in order: the key, "name", "title" and then the first property,
 336     alphabetically.
 337 </td></tr>
 338
 339 <tr><td valign=top><strong>retire</strong></td>
 340     <td><tt>retire designator[,designator]*</tt><p>
 341     This action indicates that a particular node is not to be retrieved by
 342     the list or find commands, and its key value may be re-used.
 343 </td></tr>
 344
 345 <tr><td valign=top><strong>create</strong></td>
 346     <td><tt>create classname property=value ...</tt><p>
 347     This creates a new entry of the given class using the property
 348     name=value arguments provided on the command line after the "create"
 349     command.
 350 </td></tr>
 351
 352 <tr><td valign=top><strong>get</strong></td>
 353     <td><tt>get property designator[,designator]*</tt><p>
 354     Retrieves the property value of the nodes specified by the designators.
 355 </td></tr>
 356
 357 <tr><td valign=top><strong>spec</strong></td>
 358     <td><tt>spec classname</tt><p>
 359     This lists the properties for a given class.
 360 </td></tr>
 361
 362 <tr><td valign=top><strong>set</strong></td>
 363     <td><tt>set designator[,designator]* propname=value ...</tt><p>
 364     Sets the property to the value for all designators given.
 365 </td></tr>
 366
 367 <tr><td valign=top><strong>init</strong></td>
 368     <td><tt>init [template [backend [admin password]]]</tt><p>
 369     The command will prompt for the instance home directory (if not supplied
 370     through INSTANCE_HOME or the -i option. The template, backend and admin
 371     password may be specified on the command-line as arguments, in that order.
 372 </td></tr>
 373
 374 <tr><td valign=top><strong>export</strong></td>
 375     <td><tt>export class[,class] destination_dir</tt><p>
 376     This action exports the current data from the database into
 377     comma-separated files that are placed in the nominated destination
 378     directory. The journals are not exported.
 379 </td></tr>
 380
 381 <tr><td valign=top><strong>import</strong></td>
 382     <td><tt>import class file</tt><p>
 383     The file must define the same properties as the class (including having
 384     a "header" line with those property names.)
 385 </td></tr>
 386
 387 <tr><td valign=top><strong>freshen</strong></td>
 388     <td><tt>freshen</tt><p>
 389         <strong>**DO NOT USE**</strong>
 390         <p>
 391     This currently kills databases!!!!
 392     <p>
 393     This action should generally not be used. It reads in an instance
 394     database and writes it again. In the future, is may also update
 395     instance code to account for changes in templates. It's probably wise
 396     not to use it anyway. Until we're sure it won't break things...
 397 </td></tr>
 398
 399 <tr><td><strong>help</strong></td>
 400     <td><tt>help [command]</tt><p>
 401     Short help about roundup-admin or the specific command.
 402     </td></tr>
 403
 404 <tr><td><strong>morehelp</strong></td>
 405     <td><tt>morehelp</tt><p>
 406     All available help from the roundup-admin tool.
 407     </td></tr>
 408 </table>
 409
 410 <p>
 411 All commands (except help) require an instance specifier. This is just the path
 412 to the roundup instance you're working with. A roundup instance is where
 413 roundup keeps the database and configuration file that defines an issue
 414 tracker. It may be thought of as the issue tracker's "home directory". It may
 415 be specified in the environment variable ROUNDUP_INSTANCE or on the command
 416 line as "-i instance".
 417
 418 <p>
 419 A designator is a classname and a nodeid concatenated, eg. bug1, user10, ...
 420
 421 <p>
 422 Property values are represented as strings in command arguments and in the
 423 printed results:
 424 <ul>
 425     <li>Strings are, well, strings.
 426     <li>Password values will display as their encoded value.
 427     <li>Date values are printed in the full date format in the local time zone, and
 428    accepted in the full format or any of the partial formats explained below.
 429 <table>
 430     <tr><th>Input of...</th><th>Means...</th></tr>
 431     <tr><td>"2000-04-17.03:45"</td><td>2000-04-17.08:45:00</td></tr>
 432     <tr><td>"2000-04-17"</td><td>2000-04-17.00:00:00</td></tr>
 433     <tr><td>"01-25"</td><td>yyyy-01-25.00:00:00</td></tr>
 434     <tr><td>"08-13.22:13"</td><td>yyyy-08-14.03:13:00</td></tr>
 435     <tr><td>"11-07.09:32:43"</td><td>yyyy-11-07.14:32:43</td></tr>
 436     <tr><td>"14:25"</td><td>yyyy-mm-dd.19:25:00</td></tr>
 437     <tr><td>"8:47:11"</td><td>yyyy-mm-dd.13:47:11</td></tr>
 438     <tr><td>"."</td><td>"right now"</td></tr>
 439 </table>
 440    <li>Link values are printed as node designators. When given as an argument,
 441    node designators and key strings are both accepted.
 442    <li>Multilink values are printed as lists of node designators joined by commas.
 443    When given as an argument, node designators and key strings are both
 444    accepted; an empty string, a single node, or a list of nodes joined by
 445    commas is accepted.
 446 </ul>
 447 When multiple nodes are specified to the roundup get or roundup set
 448 commands, the specified properties are retrieved or set on all the listed
 449 nodes.
 450 <p>
 451 When multiple results are returned by the roundup get or roundup find
 452 commands, they are printed one per line (default) or joined by commas (with
 453 the -c) option.
 454 <p>
 455 Where the command changes data, a login name/password is required. The
 456 login may be specified as either "name" or "name:password".
 457 <ul>
 458     <li>ROUNDUP_LOGIN environment variable
 459     <li>the -u command-line option
 460 </ul>
 461 If either the name or password is not supplied, they are obtained from the
 462 command-line.
 463
 464 <h2><a name="web">Web Interface</a></h2>
 465 Index views may be modified by the following arguments:
 466 <pre>
 467     :sort    - sort by prop name, optionally preceeded with '-'
 468              to give descending or nothing for ascending sorting.
 469     :group   - group by prop name, optionally preceeded with '-' or
 470              to sort in descending or nothing for ascending order.
 471     :filter  - selects which props should be displayed in the filter
 472              section. Default is all.
 473     :columns - selects the columns that should be displayed.
 474              Default is all.
 475     propname - selects the values the node properties given by propname
 476              must have (very basic search/filter).
 477 </pre>
 478
 479 <strong>Not sure what to put in here...</strong>
 480
 481 <h2><a name="mail">E-Mail Gateway</a></h2>
 482
 483 <h3>Performing Actions</h3>
 484 The subject line of the incoming message is examined to determine whether
 485 the message is an attempt to create a new item or to discuss an existing
 486 item. A designator enclosed in square brackets is sought as the first thing
 487 on the subject line (after skipping any "Fwd:" or "Re:" prefixes).
 488 <p>
 489 If an item designator (class name and id number) is found there, the newly
 490 created "msg" node is added to the "messages" property for that item, and
 491 any new "file" nodes are added to the "files" property for the item.
 492 <p>
 493 If just an item class name is found there, we attempt to create a new item
 494 of that class with its "messages" property initialized to contain the new
 495 "msg" node and its "files" property initialized to contain any new "file"
 496 nodes.
 497
 498 <h3>Setting Properties</h3>
 499 The e-mail interface also provides a simple way to set
 500 properties on items.  At the end of the subject line,
 501 <em>propname</em><tt>=</tt><em>value</em> pairs can be
 502 specified in square brackets, using the same conventions
 503 as for the <tt>roundup&nbsp;set</tt> shell command.
 504 explanatory message given in the exception.
 505
 506 <h3>Message content</h3>
 507 Incoming messages are examined for multiple parts:
 508 <ul>
 509 <li>In a multipart/mixed message or part, each subpart is extracted and
 510    examined. The text/plain subparts are assembled to form the textual
 511    body of the message, to be stored in the file associated with a "msg"
 512    class node. Any parts of other types are each stored in separate files
 513    and given "file" class nodes that are linked to the "msg" node.
 514 <li>In a multipart/alternative message or part, we look for a text/plain
 515    subpart and ignore the other parts.
 516 </ul>
 517
 518 <h4>Message summary</h4>
 519 The "summary" property on message nodes is taken from the first non-quoting
 520 section in the message body. The message body is divided into sections by
 521 blank lines. Sections where the second and all subsequent lines begin with
 522 a "&gt;" or "|" character are considered "quoting sections". The first line of
 523 the first non-quoting section becomes the summary of the message.
 524
 525 <h3>Address handling</h3>
 526 All of the addresses in the To: and Cc: headers of the incoming message are
 527 looked up among the user nodes, and the corresponding users are placed in
 528 the "recipients" property on the new "msg" node. The address in the From:
 529 header similarly determines the "author" property of the new "msg"
 530 node. The default handling for addresses that don't have corresponding
 531 users is to create new users with no passwords and a username equal to the
 532 address. (The web interface does not permit logins for users with no
 533 passwords.) If we prefer to reject mail from outside sources, we can simply
 534 register an auditor on the "user" class that prevents the creation of user
 535 nodes with no passwords.
 536
 537 <h3>Triggers</h3>
 538 Both cases may trigger detectors (in the first case we are calling the
 539 set() method to add the message to the item's spool; in the second case we
 540 are calling the create() method to create a new node). If an auditor raises
 541 an exception, the original message is bounced back to the sender with the
 542
 543 <h4>Nosy Lists</h4>
 544 A standard detector is provided that watches for additions
 545 to the "messages" property.  When a new message is added, the
 546 detector sends it to all the users on the "nosy" list for the
 547 item that are not already on the "recipients" list of the
 548 message.  Those users are then appended to the "recipients"
 549 property on the message, so multiple copies of a message
 550 are never sent to the same user.  The journal recorded by
 551 the hyperdatabase on the "recipients" property then provides
 552 a log of when the message was sent to whom.
 553
 554 <p><hr>
 555 <h1><a name="custom">Customising Roundup</a></h1>
 556
 557 Instances have the following structure:
 558 <table>
 559     <tr><td valign=top><strong>instance_config.py</strong></td>
 560     <td>Holds the basic <a href="#config">instance configuration</a></td></tr>
 561     <tr><td valign=top><strong>dbinit.py</strong></td>
 562         <td>Holds the <a href="#custinst">instance schema</a></td></tr>
 563     <tr><td valign=top><strong>interfaces.py</strong></td>
 564     <td>Defines the <a href="#custweb">Web</a> and E-Mail interfaces for the instance</td></tr>
 565     <tr><td valign=top><strong>select_db.py</strong></td>
 566         <td>Selects the database back-end for the instance</td></tr>
 567     <tr><td valign=top><strong>db/</strong></td>
 568         <td>Holds the instance's database</td></tr>
 569     <tr><td valign=top><strong>db/files/</strong></td>
 570         <td>Holds the instance's upload files and messages</td></tr>
 571     <tr><td valign=top><strong>detectors/</strong></td>
 572         <td>Auditors and reactors for this instance</td></tr>
 573     <tr><td valign=top><strong>html/</strong></td>
 574     <td>Web interface <a href="#custweb">templates</a>, images and style sheets</td></tr>
 575 </table>
 576
 577 <h2><a name="config">Instance Configuration</a></h2>
 578 The <tt>instance_config.py</tt> located in your instance home contains the
 579 basic configuration for the web and e-mail components of roundup's
 580 interfaces. This file is a Python module. The default
 581 <tt>instance_config.py</tt> is given below - as you can see, the
 582 MAIL_DOMAIN must be edited before any interaction with the instance is
 583 attempted.
 584
 585 <p>
 586 <pre>
 587 MAIL_DOMAIN=MAILHOST=HTTP_HOST=None
 588 HTTP_PORT=0
 589
 590 # roundup home is this package's directory
 591 INSTANCE_HOME=os.path.split(__file__)[0]
 592
 593 # The SMTP mail host that roundup will use to send mail
 594 if not MAILHOST:
 595     MAILHOST = 'localhost'
 596
 597 # The domain name used for email addresses.
 598 if not MAIL_DOMAIN:
 599     MAIL_DOMAIN = 'fill.me.in.'
 600
 601 # the next two are only used for the standalone HTTP server.
 602 if not HTTP_HOST:
 603     HTTP_HOST = ''
 604 if not HTTP_PORT:
 605     HTTP_PORT = 9080
 606
 607 # This is the directory that the database is going to be stored in
 608 DATABASE = os.path.join(INSTANCE_HOME, 'db')
 609
 610 # This is the directory that the HTML templates reside in
 611 TEMPLATES = os.path.join(INSTANCE_HOME, 'html')
 612
 613 # The email address that mail to roundup should go to
 614 ISSUE_TRACKER_EMAIL = 'issue_tracker@%s'%MAIL_DOMAIN
 615
 616 # The web address that the instance is viewable at
 617 ISSUE_TRACKER_WEB = 'http://some.useful.url/'
 618
 619 # The email address that roundup will complain to if it runs into trouble
 620 ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN
 621
 622 # Somewhere for roundup to log stuff internally sent to stdout or stderr
 623 LOG = os.path.join(INSTANCE_HOME, 'roundup.log')
 624 </pre>
 625
 626 <h2><a name="custinst">Instance Schema</a></h2>
 627 An instance schema defines what data is stored in the instance's database.
 628 The two schemas shipped with Roundup turn it into a typical software bug
 629 tracker (the extended schema allowing for support issues as well as bugs).
 630 Schemas are defined using Python code. The "classic" schema looks like
 631 this:
 632 <p>
 633 <pre>
 634     pri = Class(db, "priority", name=String(), order=String())
 635     pri.setkey("name")
 636     pri.create(name="critical", order="1")
 637     pri.create(name="urgent", order="2")
 638     pri.create(name="bug", order="3")
 639     pri.create(name="feature", order="4")
 640     pri.create(name="wish", order="5")
 641
 642     stat = Class(db, "status", name=String(), order=String())
 643     stat.setkey("name")
 644     stat.create(name="unread", order="1")
 645     stat.create(name="deferred", order="2")
 646     stat.create(name="chatting", order="3")
 647     stat.create(name="need-eg", order="4")
 648     stat.create(name="in-progress", order="5")
 649     stat.create(name="testing", order="6")
 650     stat.create(name="done-cbb", order="7")
 651     stat.create(name="resolved", order="8")
 652
 653     keyword = Class(db, "keyword", name=String())
 654     keyword.setkey("name")
 655
 656     user = Class(db, "user", username=String(), password=String(),
 657         address=String(), realname=String(), phone=String(), organisation=String())
 658     user.setkey("username")
 659     user.create(username="admin", password=adminpw, address=instance_config.ADMIN_EMAIL)
 660
 661     msg = FileClass(db, "msg", author=Link("user"), recipients=Multilink("user"),
 662         date=Date(), summary=String(), files=Multilink("file"))
 663
 664     file = FileClass(db, "file", name=String(), type=String())
 665
 666     issue = IssueClass(db, "issue", assignedto=Link("user"),
 667         topic=Multilink("keyword"), priority=Link("priority"), status=Link("status"))
 668     issue.setkey('title')
 669 </pre>
 670
 671 <h3>Classes and Properties - creating a new information store</h3>
 672 In the instance above, we've defined 7 <em>classes</em> of information:
 673 <dl>
 674     <dt><strong>priority</strong>
 675     <dd>Defines the possible levels of urgency for issues.
 676     <dt><strong>status</strong>
 677     <dd>Defines the possible states of processing the issue may be in.
 678     <dt><strong>keyword</strong>
 679     <dd>Initially empty, will hold keywords useful for searching issues.
 680     <dt><strong>user</strong>
 681     <dd>Initially holding the "admin" user, will eventually have an entry
 682     for all users using roundup.
 683     <dt><strong>msg</strong>
 684     <dd>Initially empty, will all e-mail messages sent to or generated by roundup.
 685     <dt><strong>file</strong>
 686     <dd>Initially empty, will all files attached to issues.
 687     <dt><strong>issue</strong>
 688     <dd>Initially emtyp, this is where the issue information is stored.
 689 </dl>
 690 <p>
 691 We define the "priority" and "status" classes to allow two things: reduction
 692 in the amount of information stored on the issue and more powerful, accurate
 693 searching of issues by priority and status. By only requiring a link on
 694 the issue (which is stored as a single number) we reduce the chance
 695 that someone mis-types a priority or status - or simply makes a new one
 696 up.
 697
 698 <h4>Class and Nodes</h4>
 699 A <em>Class</em> defines a particular class (or type) of data that will be
 700 stored in the database. A class comprises one or more properties, which
 701 given the information about the class nodes.
 702 <p>
 703 The actual data entered into the database, using <em>class</em>.create()
 704 are called <em>nodes</em>. They have a special immutable property called
 705 id. We sometimes refer to this as the <em>nodeid</em>.
 706
 707
 708 <h4>Properties</h4>
 709 A Class is comprised of one or more <em>properties</em> of the following types:
 710
 711 <ul>
 712 <li><em>String</em> properties are for storing arbitrary-length
 713 strings.
 714
 715 <li><em>Password</em> properties are for storing encoded arbitrary-length
 716 strings. The default encoding is defined on the roundup.password.Password
 717 class.
 718
 719 <li><em>Date</em> properties store date-and-time stamps.
 720 Their values are Timestamp objects.
 721
 722 <li>A <em>Link</em> property refers to a single other node
 723 selected from a specified class.  The class is part of the property;
 724 the value is an integer, the id of the chosen node.
 725
 726 <li>A <em>Multilink</em> property refers to possibly many nodes
 727 in a specified class.  The value is a list of integers.
 728 </ul>
 729
 730 <h4>FileClass</h4>
 731 FileClasses save their "content" attribute off in a separate file from the
 732 rest of the database. This reduces the number of large entries in the
 733 database, which generally makes databases more efficient, and also allows
 734 us to use command-line tools to operate on the files. They are stored in
 735 the files sub-directory of the db directory in your instance.
 736
 737 <h4>IssueClass</h4>
 738 IssueClasses automatically include the "messages", "files", "nosy", and
 739 "superseder" properties.
 740 <p>
 741 The messages and files properties list the links to the messages and files
 742 related to the issue. The nosy property is a list of links to users who
 743 wish to be informed of changes to the issue - they get "CC'ed" e-mails when
 744 messages are sent to or generated by the issue. The nosy reactor (in the
 745 detectors directory) handles this action. The superceder link indicates an
 746 issue which has superceded this one.
 747 <p>
 748 They also have the dynamically generated
 749 "creation", "activity" and "creator" properties.
 750 <p>
 751 The value of the "creation" property is the date when a node was created,
 752 and the value of the "activity" property is the date when any property on
 753 the node was last edited (equivalently, these are the dates on the first
 754 and last records in the node's journal). The "creator" property holds a
 755 link to the user that created the issue.
 756
 757 <h4>setkey(property)</h4>
 758 Select a String property of the class to be the key property. The key
 759 property muse be unique, and allows references to the nodes in the class by
 760 the content of the key property. That is, we can refer to users by their
 761 username, e.g. let's say that there's an issue in roundup, issue 23. There's
 762 also a user, richard who happens to be user 2. To assign an issue to him,
 763 we could do either of:
 764 <p>
 765 <blockquote><tt>roundup-admin set issue assignedto=2</tt></blockquote>
 766 <p>
 767 or
 768 <p>
 769 <blockquote><tt>roundup-admin set issue
 770         assignedto=richard</tt></blockquote>
 771 <p>
 772 Note, the same thing can be done in the web and e-mail interfaces.
 773
 774 <h4>create(information)</h4>
 775 Create a node in the database. This is generally used to create nodes in
 776 the "definitional" classes like "priority" and "status".
 777
 778
 779 <h2><a name="custweb">Web Interface</a></h2>
 780
 781 The web interface works behind the cgi-bin/roundup.cgi or roundup-server
 782 scripts. In both cases, the scripts determine which instance is being
 783 accessed (the first part of the URL path inside the scope of the CGI
 784 handler) and pass control on to the instance interfaces.Client class which
 785 handles the rest of the access through its main() method. This means that
 786 you can do pretty much anything you want as a web interface to your
 787 instance.
 788 <p>
 789 Most customisation of the web view can be done by modifying the templates
 790 in the instance html directory. These are divided into index, item and
 791 newitem views. The newitem view is optional - the item view will be used if
 792 the newitem view doesn't exist.
 793
 794 <h3>Displaying Properties</h3>
 795
 796 <p>
 797 Properties appear in the user interface in three contexts:
 798 in indices, in editors, and as filters.  For each type of
 799 property, there are several display possibilities.  For example,
 800 in an index view, a string property may just be printed as
 801 a plain string, but in an editor view, that property should
 802 be displayed in an editable field.
 803
 804 <p>
 805 The display of a property is handled by functions in
 806 the htmltemplate module.
 807
 808 <p>
 809 Displayer functions are triggered by <tt>&lt;display&gt;</tt>
 810 tags in templates.  The <tt>call</tt> attribute of the tag
 811 provides a Python expression for calling the displayer
 812 function.  The three standard arguments are inserted in
 813 front of the arguments given.  For example, the occurrence of
 814
 815 <blockquote><pre><small
 816 >    &lt;display call="plain('status')"&gt;
 817 </small></pre></blockquote>
 818
 819 in a template triggers a call the "plain" function. The displayer
 820 functions can accept extra arguments to further specify
 821 details about the widgets that should be generated.  By defining new
 822 displayer functions, the user interface can be highly customized.
 823
 824 <p>
 825 <table border=1 cellspacing=0>
 826 <tr><th colspan=2>The displayer functions are</th></tr>
 827
 828 <tr><td valign="top"><strong>plain</strong></td>
 829 <td>Display a String property directly.
 830 <p>
 831 Display a Date property in a specified time zone with an option
 832 to omit the time from the date stamp.
 833 <p>
 834 For a Link or Multilink
 835 property, display the key strings of the linked nodes (or the
 836 ids if the linked class has no key property).
 837 <p>
 838 <em>Options:</em><br>
 839 escape (boolean) - HTML-escape the resulting text.
 840 </td></tr>
 841
 842 <tr><td valign="top"><strong>field</strong></td>
 843 <td>Display a property like the
 844 <strong>plain</strong> displayer above, but in a form field
 845 to be edited. Strings, Dates and Intervals use TEXT fields, Links use
 846 SELECT fields and Multilinks use SELECT MULTIPLE fields.
 847 <p>
 848 <em>Options:</em><br>
 849 size (number) - width of TEXT fields.<br>
 850 height (number) - number of nows in SELECT MULTIPLE tags.<br>
 851 showid (boolean) - true includes the id of linked nodes in the SELECT
 852 MULTIPLE fields.
 853 </td></tr>
 854
 855 <tr><td valign="top"><strong>menu</strong></td>
 856 <td>For a Links and Multilinks, display the same field as would be
 857 generated using <strong>field</strong>.
 858 </td></tr>
 859
 860 <tr><td valign="top"><strong>link</strong></td>
 861 <td>For a Link or Multilink property, display the names of the linked
 862 nodes, hyperlinked to the item views on those nodes.
 863 <p>
 864 For other properties, link to this node with the property as the text.
 865 <p>
 866 <em>Options:</em><br>
 867 property (property name) - the property to use in the second case.<br>
 868 is_download (boolean) - to be used for links te <em>file</em> class nodes -
 869 this indicates that the URL should have the specified property (usually
 870 <em>name</em>) appended so that the download has the correct name (instead
 871 of the node designator.)
 872 </td></tr>
 873
 874 <tr><td valign="top"><strong>count</strong></td>
 875 <td>For a Multilink property, display
 876 a count of the number of links in the list.
 877 <p>
 878 <em>Arguments:</em><br>
 879 property (property name) - the property to use.
 880
 881 </td></tr>
 882
 883 <tr><td valign="top"><strong>reldate</strong></td>
 884 <td>Display a Date property in terms
 885 of an interval relative to the current date (e.g. "+ 3w", "- 2d").
 886 <p>
 887 <em>Arguments:</em><br>
 888 property (property name) - the property to use.
 889 <p>
 890 <em>Options:</em><br>
 891 pretty (boolean) - display the relative date in an English form.
 892 </td></tr>
 893
 894 <tr><td valign="top"><strong>download</strong></td>
 895 <td>Show a Link("file") or Multilink("file")
 896 property using links that allow you to download files.
 897 <p>
 898 <em>Arguments:</em><br>
 899 property (property name) - the property to use.
 900 </td></tr>
 901
 902 <tr><td valign="top"><strong>checklist</strong></td>
 903 <td>For a Link or Multilink property,
 904 display checkboxes for the available choices to permit filtering.
 905 <p>
 906 <em>Arguments:</em><br>
 907 property (property name) - the property to use.
 908 </td></tr>
 909
 910 <tr><td valign="top"><strong>note</strong></td>
 911 <td>Display the special notes field, which is a text area for entering a
 912 note to go along with a change.
 913 </td></tr>
 914
 915 <tr><td valign="top"><strong>list</strong></td>
 916 <td>List the nodes specified by property using the standard index for
 917 the class.
 918 <p>
 919 <em>Arguments:</em><br>
 920 property (property name) - the property to use.
 921 </td></tr>
 922
 923 <tr><td valign="top"><strong>history</strong></td>
 924 <td>List the history of the item.
 925 </td></tr>
 926
 927 <tr><td valign="top"><strong>submit</strong></td>
 928 <td>Add a submit button for the item.
 929 </td></tr>
 930
 931 </table>
 932
 933 <h3>Index Views</h3>
 934
 935 <p>An index view contains two sections: a filter section
 936 and an index section.
 937 The filter section provides some widgets for selecting
 938 which items appear in the index.  The index section is
 939 a table of items.
 940
 941 <h4>Index View Specifiers</h4>
 942
 943 <p>An index view specifier (URL fragment) looks like this (whitespace
 944 has been added for clarity):
 945
 946 <blockquote><pre><small
 947 >/issue?status=unread,in-progress,resolved&amp;
 948         topic=security,ui&amp;
 949         :group=+priority&amp;
 950         :sort=-activity&amp;
 951         :filters=status,topic&amp;
 952         :columns=title,status,fixer
 953 </small></pre></blockquote>
 954
 955 <p>The index view is determined by two parts of the
 956 specifier: the layout part and the filter part.
 957 The layout part consists of the query parameters that
 958 begin with colons, and it determines the way that the
 959 properties of selected nodes are displayed.
 960 The filter part consists of all the other query parameters,
 961 and it determines the criteria by which nodes
 962 are selected for display.
 963
 964 <p>The filter part is interactively manipulated with
 965 the form widgets displayed in the filter section.  The
 966 layout part is interactively manipulated by clicking
 967 on the column headings in the table.
 968
 969 <p>The filter part selects the <em>union</em> of the
 970 sets of items with values matching any specified Link
 971 properties and the <em>intersection</em> of the sets
 972 of items with values matching any specified Multilink
 973 properties.
 974
 975 <p>The example specifies an index of "issue" nodes.
 976 Only items with a "status" of <em>either</em>
 977 "unread" or "in-progres" or "resolved" are displayed,
 978 and only items with "topic" values including <em>both</em>
 979 "security" <em>and</em> "ui" are displayed.  The items
 980 are grouped by priority, arranged in ascending order;
 981 and within groups, sorted by activity, arranged in
 982 descending order.  The filter section shows filters
 983 for the "status" and "topic" properties, and the
 984 table includes columns for the "title", "status", and
 985 "fixer" properties.
 986
 987 <p>Associated with each item class is a default
 988 layout specifier.  The layout specifier in the above
 989 example is the default layout to be provided with
 990 the default bug-tracker schema described above in
 991 section 4.4.
 992
 993 <h4>Filter Section</h4>
 994
 995 <p>The template for a filter section provides the
 996 filtering widgets at the top of the index view.
 997 Fragments enclosed in <tt>&lt;property&gt;</tt>...<tt>&lt;/property&gt;</tt>
 998 tags are included or omitted depending on whether the
 999 view specifier requests a filter for a particular property.
1000
1001 <p>Here's a simple example of a filter template.
1002
1003 <blockquote><pre><small
1004 >&lt;property name=status&gt;
1005     &lt;display call="checklist('status')"&gt;
1006 &lt;/property&gt;
1007 &lt;br&gt;
1008 &lt;property name=priority&gt;
1009     &lt;display call="checklist('priority')"&gt;
1010 &lt;/property&gt;
1011 &lt;br&gt;
1012 &lt;property name=fixer&gt;
1013     &lt;display call="menu('fixer')"&gt;
1014 &lt;/property&gt;</small></pre></blockquote>
1015
1016 <p>
1017 The standard index generation code appends a section to the index pages
1018 which allows selection of the filters - from those which are defined in the
1019 filter template.
1020
1021 <h4>Index Section</h4>
1022
1023 <p>The template for an index section describes one row of
1024 the index table.
1025 Fragments enclosed in <tt>&lt;property&gt;</tt>...<tt>&lt;/property&gt;</tt>
1026 tags are included or omitted depending on whether the
1027 view specifier requests a column for a particular property.
1028 The table cells should contain <tt>&lt;display&gt;</tt> tags
1029 to display the values of the item's properties.
1030
1031 <p>Here's a simple example of an index template.
1032
1033 <blockquote><pre><small
1034 >&lt;tr&gt;
1035     &lt;property name=title&gt;
1036         &lt;td&gt;&lt;display call="plain('title', max=50)"&gt;&lt;/td&gt;
1037     &lt;/property&gt;
1038     &lt;property name=status&gt;
1039         &lt;td&gt;&lt;display call="plain('status')"&gt;&lt;/td&gt;
1040     &lt;/property&gt;
1041     &lt;property name=fixer&gt;
1042         &lt;td&gt;&lt;display call="plain('fixer')"&gt;&lt;/td&gt;
1043     &lt;/property&gt;
1044 &lt;/tr&gt;</small></pre></blockquote>
1045
1046 <h4>Sorting</h4>
1047
1048 <p>String and Date values are sorted in the natural way.
1049 Link properties are sorted according to the value of the
1050 "order" property on the linked nodes if it is present; or
1051 otherwise on the key string of the linked nodes; or
1052 finally on the node ids.  Multilink properties are
1053 sorted according to how many links are present.
1054
1055 <h3>Item Views</h3>
1056
1057 <p>An item view contains an editor section and a spool section.
1058 At the top of an item view, links to superseding and superseded
1059 items are always displayed.
1060
1061
1062
1063 <h4>Editor Section</h4>
1064
1065 <p>The editor section is generated from a template
1066 containing <tt>&lt;display&gt;</tt> tags to insert
1067 the appropriate widgets for editing properties.
1068
1069 <p>Here's an example of a basic editor template.
1070
1071 <blockquote><pre><small
1072 >&lt;table&gt;
1073 &lt;tr&gt;
1074     &lt;td colspan=2&gt;
1075         &lt;display call="field('title', size=60)"&gt;
1076     &lt;/td&gt;
1077 &lt;/tr&gt;
1078 &lt;tr&gt;
1079     &lt;td&gt;
1080         &lt;display call="field('fixer', size=30)"&gt;
1081     &lt;/td&gt;
1082     &lt;td&gt;
1083         &lt;display call="menu('status')&gt;
1084     &lt;/td&gt;
1085 &lt;/tr&gt;
1086 &lt;tr&gt;
1087     &lt;td&gt;
1088         &lt;display call="field('nosy', size=30)"&gt;
1089     &lt;/td&gt;
1090     &lt;td&gt;
1091         &lt;display call="menu('priority')&gt;
1092     &lt;/td&gt;
1093 &lt;/tr&gt;
1094 &lt;tr&gt;
1095     &lt;td colspan=2&gt;
1096         &lt;display call="note()"&gt;
1097     &lt;/td&gt;
1098 &lt;/tr&gt;
1099 &lt;/table&gt;
1100 </small></pre></blockquote>
1101
1102 <p>As shown in the example, the editor template can also
1103 request the display of a "note" field, which is a
1104 text area for entering a note to go along with a change.
1105
1106 <p>When a change is submitted, the system automatically
1107 generates a message describing the changed properties.
1108
1109 <p>If a note is given in the "note" field, the note is
1110 appended to the description.  The message is then added
1111 to the item's message spool (thus triggering the standard
1112 detector to react by sending out this message to the nosy list).
1113
1114 <p>
1115 The message also displays all of the property values on the
1116 item and indicates which ones have changed.
1117 An example of such a message might be this:
1118
1119 <blockquote><pre>
1120 Polly's taken a turn for the worse - this is now really important!
1121 -----
1122 title: Polly Parrot is dead
1123 priority: critical
1124 status: unread -&gt; in-progress
1125 fixer: terry
1126 keywords: parrot,plumage,perch,nailed,dead
1127 </pre></blockquote>
1128
1129 <h4>Spool Section</h4>
1130
1131 <p>The spool section lists messages in the item's "messages"
1132 property.  The index of messages displays the "date", "author",
1133 and "summary" properties on the message nodes, and selecting a
1134 message takes you to its content.
1135
1136 <p>The &lt;property&gt; tag used in the index may also be used here -
1137 it checks to see if the nominated Multilink property has any entries.
1138 This can be used to eliminate sections of the spool section if the
1139 property has no entries.
1140
1141 <blockquote><pre>
1142 &lt;property name="files"&gt;
1143  &lt;tr class="strong-header"&gt;
1144   &lt;td&gt;&lt;b&gt;Files&lt;/b&gt;&lt;/td&gt;
1145  &lt;/tr&gt;
1146
1147  &lt;tr&gt;
1148   &lt;td&gt;&lt;display call="list('files')"&gt;&lt;/td&gt;
1149  &lt;/tr&gt;
1150 &lt;/property&gt;
1151 </pre></blockquote>
1152
1153 <p><hr>
1154 <h1><a name="ack">Acknowledgements</a></h1>
1155
1156 Go Ping, you rock! Also, go Bizar Software for letting me implement this
1157 system on their time.
1158
1159 <p>&nbsp;</p>
1160 <hr>
1161 $Id: index.html,v 1.16 2001-10-22 03:25:01 richard Exp $
1162 <p>&nbsp;</p>
1163
1164 </body></html>
1165