From: richard Date: Thu, 18 Jul 2002 11:26:56 +0000 (+0000) Subject: better mailgw user docs X-Git-Url: https://git.tokkee.org/?a=commitdiff_plain;h=6d6e1304d311f35271c2f61e72a0317f795431b1;p=roundup.git better mailgw user docs git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@893 57a73879-2fb5-44c3-a270-3262357dd7e2 --- diff --git a/doc/user_guide.txt b/doc/user_guide.txt index 87c7373..fed58e1 100644 --- a/doc/user_guide.txt +++ b/doc/user_guide.txt @@ -2,10 +2,193 @@ User Guide ========== -:Version: $Revision: 1.4 $ +:Version: $Revision: 1.5 $ .. contents:: +Note: this document will refer to *issues* as the primary store of information +in the tracker. This is the default of the classic template, bubt may vary in +any given installation. + +Web Interface +------------- + +Index views may be modified by the following arguments: + ++-----------+--------------------------------------------------------------+ +| :sort | sort by prop name, optionally preceeded with '-' | +| | to give descending or nothing for ascending sorting. | ++-----------+--------------------------------------------------------------+ +| :group | group by prop name, optionally preceeded with '-' or | +| | to sort in descending or nothing for ascending order. | ++-----------+--------------------------------------------------------------+ +| :filter | selects which props should be displayed in the filter | +| | section. Default is all. | ++-----------+--------------------------------------------------------------+ +| :columns | selects the columns that should be displayed. | +| | Default is all. | ++-----------+--------------------------------------------------------------+ +| propname | selects the values the node properties given by propname | +| | must have (very basic search/filter). | ++-----------+--------------------------------------------------------------+ + +Searching +~~~~~~~~~ + +TODO: some information about how searching works + + +Access Controls +~~~~~~~~~~~~~~~ + + +Managing Issues +~~~~~~~~~~~~~~~ + +TODO: some mention of how the various widgets work + + +E-Mail Gateway +-------------- + +E-mail sent to Roundup is examined for several pieces of information: + +1. `subject-line information`_ identifying the purpose of the e-mail +2. `e-mail message content`_ which is to be extracted +3. e-mail attachments which should be associated with the message + +Subject-line information +~~~~~~~~~~~~~~~~~~~~~~~~ + +The subject line of the incoming message is examined to find one of: + +1. the item that the message is responding to, +2. the type of item the message should create, or +3. we default the item class and try some trickiness + +If the subject line contains a prefix in ``[square brackets]`` then we're +looking at case 1 or 2 above. Note that any "re:" or "fwd:" prefixes are +stripped off the subject line before we start looking for real information. + +If an item designator (class name and id number, for example ``issue123``) +is found there, a new "msg" node is added to the "messages" property for +that item, and any new "file" nodes are added to the "files" property for +the item. + +If just an item class name is found there, we attempt to create a new item of +that class with its "messages" property initialized to contain the new "msg" +node and its "files" property initialized to contain any new "file" nodes. + +The third case above - where no ``[information]`` is provided, the tracker's +``MAIL_DEFAULT_CLASS`` configuration variable defines what class of item +the message relates to. We try to match the subject line to an existing +item of the default class, and if there's a match, the message is related to +that matched item. If not, then a new item of the default class is created. + +Setting Properties +:::::::::::::::::: + +The e-mail interface also provides a simple way to set properties on items. At +the end of the subject line, propname=value pairs can be specified in square +brackets, using the same conventions as for the roundup set shell command. + +For example, + +- setting the priority of an issue:: + + Subject: Re: [issue1] the coffee machine is broken! [priority=urgent] + +- adding yourself to a nosy list:: + + Subject: Re: [issue2] we're out of widgets [nosy=+richard] + +- setting the nosy list to just you:: + + Subject: Re: [issue2] we're out of widgets [nosy=richard] + +- removing yourself from a nosy list:: + + Subject: Re: [issue2] we're out of widgets [nosy=-richard] + +In all cases, the message relates to issue 2. The ``Re:`` prefix is stripped +off. + + +E-Mail Message Content +~~~~~~~~~~~~~~~~~~~~~~ + +Roundup only associates plain text (MIME type ``text/plain``) as messages for +items. Any other parts of a message are associated as downloadable files. If +no plain text part is found, the message is rejected. + +To do this, incoming messages are examined for multiple parts: + +* In a multipart/mixed message or part, each subpart is extracted and + examined. The text/plain subparts are assembled to form the textual body + of the message, to be stored in the file associated with a "msg" class + node. Any parts of other types are each stored in separate files and + given "file" class nodes that are linked to the "msg" node. +* In a multipart/alternative message or part, we look for a text/plain + subpart and ignore the other parts. + +If the message is a response to a previous message, and contains quoted +sections, then these will be stripped out of the message if the +``EMAIL_KEEP_QUOTED_TEXT`` configuration variable is set to ``'no'``. + +Message summary +::::::::::::::: + +The "summary" property on message 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. + + +Address handling +~~~~~~~~~~~~~~~~ + +All of the addresses in the ``To:`` and ``Cc:`` headers of the incoming +message are +looked up among the tracker users, and the corresponding users are placed +in the +"recipients" property on the new "msg" 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 addresses mentioned in the ``To:``, ``From:`` and ``Cc:`` headers of +the message may be added to the `nosy list`_ depending on: + +``ADD_AUTHOR_TO_NOSY`` + Does the author of a message get placed on the nosy list automatically? + If 'new' is used, then the author will only be added when a message + creates a new issue. If 'yes', then the author will be added on followups + too. If 'no', they're never added to the nosy. + +``ADD_RECIPIENTS_TO_NOSY`` + Do the recipients (To:, Cc:) of a message get placed on the nosy list? + If 'new' is used, then the recipients will only be added when a message + creates a new issue. If 'yes', then the recipients will be added on + followups too. If 'no', they're never added to the nosy. + + +Nosy List +::::::::: + +The nosy list watches for additions to the "messages" property of items. +When a new message is added, it is sent to all the users +on the "nosy" list for the item that are not already on the "recipients" list +of the message. Those users are then appended to the "recipients" property on +the message, so multiple copies of a message are never sent to the same user. +The journal recorded by the hyperdatabase on the "recipients" property then +provides a log of when the message was sent to whom. + +If the author of the message is also in the nosy list for the item that the +message is attached to, then the config var ``MESSAGES_TO_AUTHOR`` is queried +to determine if they get a nosy list copy of the message too. + + Command Line Tool ----------------- @@ -175,124 +358,6 @@ If either the name or password is not supplied, they are obtained from the command-line. -Web Interface -------------- - -Index views may be modified by the following arguments: - -+-----------+--------------------------------------------------------------+ -| :sort | sort by prop name, optionally preceeded with '-' | -| | to give descending or nothing for ascending sorting. | -+-----------+--------------------------------------------------------------+ -| :group | group by prop name, optionally preceeded with '-' or | -| | to sort in descending or nothing for ascending order. | -+-----------+--------------------------------------------------------------+ -| :filter | selects which props should be displayed in the filter | -| | section. Default is all. | -+-----------+--------------------------------------------------------------+ -| :columns | selects the columns that should be displayed. | -| | Default is all. | -+-----------+--------------------------------------------------------------+ -| propname | selects the values the node properties given by propname | -| | must have (very basic search/filter). | -+-----------+--------------------------------------------------------------+ - -Not sure what to put in here... - -E-Mail Gateway --------------- - -Performing Actions -~~~~~~~~~~~~~~~~~~ - -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). -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. -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. - -Setting Properties -~~~~~~~~~~~~~~~~~~ - -The e-mail interface also provides a simple way to set properties on items. At -the end of the subject line, propname=value pairs can be specified in square -brackets, using the same conventions as for the roundup set shell command. - -For example, - -- setting the priority of an issue:: - - Subject: Re: [issue1] the coffee machine is broken! [priority=urgent] - -- adding yourself to a nosy list (both of these are equivalent):: - - Subject: Re: [issue2] we're out of widgets [nosy=+richard] - Subject: Re: [issue2] we're out of widgets [nosy=richard] - -- removing yourself from a nosy list:: - - Subject: Re: [issue2] we're out of widgets [nosy=-richard] - - -Message content -~~~~~~~~~~~~~~~ - -Incoming messages are examined for multiple parts: - -* In a multipart/mixed message or part, each subpart is extracted and - examined. The text/plain subparts are assembled to form the textual body - of the message, to be stored in the file associated with a "msg" class - node. Any parts of other types are each stored in separate files and - given "file" class nodes that are linked to the "msg" node. -* In a multipart/alternative message or part, we look for a text/plain - subpart and ignore the other parts. - -Message summary -::::::::::::::: - -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. - -Address handling -~~~~~~~~~~~~~~~~ - -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. - -Triggers -~~~~~~~~ - -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 - -Nosy Lists -:::::::::: - -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. - -----------------