summaryrefslogtreecommitdiff
path: root/Architecture_and_Design
diff options
context:
space:
mode:
authorJeroen van Meeuwen (Kolab Systems) <vanmeeuwen@kolabsys.com>2012-03-12 13:47:10 (GMT)
committerJeroen van Meeuwen (Kolab Systems) <vanmeeuwen@kolabsys.com>2012-03-12 13:47:10 (GMT)
commitce54e162d41737a4a4d121ec2d83bb6129956649 (patch)
treed2c7ccb8f64ff49f9d91719b1518e5f2ceaec45b /Architecture_and_Design
parent66fe3f141c9092e3b61343d5e5caebaccd3a8b18 (diff)
downloadkolab-docs-ce54e162d41737a4a4d121ec2d83bb6129956649.tar.gz
Update Kolab Content Filters
Diffstat (limited to 'Architecture_and_Design')
-rw-r--r--Architecture_and_Design/en-US/Groupware_Overview.xml115
-rw-r--r--Architecture_and_Design/en-US/Kolab_Content_Filters.xml243
2 files changed, 352 insertions, 6 deletions
diff --git a/Architecture_and_Design/en-US/Groupware_Overview.xml b/Architecture_and_Design/en-US/Groupware_Overview.xml
index 590636e..ca6dad1 100644
--- a/Architecture_and_Design/en-US/Groupware_Overview.xml
+++ b/Architecture_and_Design/en-US/Groupware_Overview.xml
@@ -6,6 +6,121 @@
<chapter id="chap-Architecture_and_Design-Groupware_Overview">
<title>Groupware Overview</title>
<para>
+ Groupware is collaborative software designed to allow people with a common task to achieve goals. Aspects in an infrastructure providing such functionality include;
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Email,
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Calendaring,
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Task Management,
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Journalling,
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Contacts,
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Address Books,
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Notebooks &amp; Notes
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+ <para>
+ All of the former are capabilities provided by Kolab Groupware itself.
+ </para>
+ <para>
+ Collaboration also includes, however;
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Voice- and Video Communications,
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Message boards,
+ </para>
+ <remark> Also known as bulletin boards, forums, news groups. </remark>
+
+ </listitem>
+ <listitem>
+ <para>
+ Knowledge bases,
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Enterprise bookmarking,
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Instant Messaging,
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Document Management,
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Project Management,
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Work-flow Management
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+ <para>
+ While each of the aforementioned aspects of groupware and collaboration is available as Free Software, integration is another topic.
+ </para>
+ <para>
The following is a list of items that somehow, to some extent, relate to a groupware environment;
</para>
<para>
diff --git a/Architecture_and_Design/en-US/Kolab_Content_Filters.xml b/Architecture_and_Design/en-US/Kolab_Content_Filters.xml
index dc173d6..904632b 100644
--- a/Architecture_and_Design/en-US/Kolab_Content_Filters.xml
+++ b/Architecture_and_Design/en-US/Kolab_Content_Filters.xml
@@ -187,6 +187,29 @@ modules=conversations,optout
</section>
+ <section id="sect-Architecture_and_Design-The_Wallace_Content_Filter-Module_Spool_Directories">
+ <title>Module Spool Directories</title>
+ <para>
+ Modules maintain their own spool directories in order to be able to maintain state. The directory tree for a given module may look as follows:
+ </para>
+ <para>
+
+<screen><filename>/var/spool/pykolab/wallace/<replaceable>$module</replaceable>/</filename>
+<filename>/var/spool/pykolab/wallace/<replaceable>$module</replaceable>/incoming/</filename>
+<filename>/var/spool/pykolab/wallace/<replaceable>$module</replaceable>/ACCEPT/</filename>
+<filename>/var/spool/pykolab/wallace/<replaceable>$module</replaceable>/DEFER/</filename>
+<filename>/var/spool/pykolab/wallace/<replaceable>$module</replaceable>/DISCARD/</filename>
+<filename>/var/spool/pykolab/wallace/<replaceable>$module</replaceable>/DUNNO/</filename>
+<filename>/var/spool/pykolab/wallace/<replaceable>$module</replaceable>/HOLD/</filename>
+<filename>/var/spool/pykolab/wallace/<replaceable>$module</replaceable>/REJECT/</filename></screen>
+
+ </para>
+ <para>
+ This means a module is required to copy and/or move (part of) the message into the correct queue before placing a callback to Wallace. For example, when the <literal>optout</literal> is executed, the first thing it should to is pick up the message from <filename>/var/spool/pykolab/wallace/incoming/</filename> and move the message file to <filename>/var/spool/pykolab/wallace/optout/incoming/</filename>.
+ </para>
+
+ </section>
+
<section id="sect-Architecture_and_Design-The_Wallace_Content_Filter-Module_API_Requirements">
<title>Module API Requirements</title>
<para>
@@ -286,7 +309,7 @@ def execute(*args, **kw):
<formalpara id="form-Architecture_and_Design-Available_Wallace_Module_Callbacks-cb_action_DEFERmodulefilepath">
<title><literal>cb_action_DEFER(module,filepath)</literal></title>
<para>
- Modules place a callback to this function when a module could not successfully execute (a part of) its tasks.
+ Modules place a callback to this function when a module could not successfully execute (a part of) its tasks. It is to be interpreted as a "try again later" callback.
</para>
</formalpara>
@@ -299,7 +322,7 @@ def execute(*args, **kw):
<formalpara id="form-Architecture_and_Design-Available_Wallace_Module_Callbacks-cb_action_DISCARDmodulefilepath">
<title><literal>cb_action_DISCARD(module,filepath)</literal></title>
<para>
- para
+ The message in <literal>filepath</literal> is to be discarded in its entirety. A callback to this function is placed when a message needs to be discarded only to allow other modules to hook in to this part of the process.
</para>
</formalpara>
@@ -312,7 +335,7 @@ def execute(*args, **kw):
<formalpara id="form-Architecture_and_Design-Available_Wallace_Module_Callbacks-cb_action_DUNNOmodulefilepath">
<title><literal>cb_action_DUNNO(module,filepath)</literal></title>
<para>
- para
+ A callback to this function is to indicate that the module placing the callback does not care what happens to the message in <literal>filepath</literal>. Since modules can apply rules that enable them to determine whether or not they need to be executed in full for a given message, this callback indicates that the module has found it should not be executed for the particular message.
</para>
</formalpara>
@@ -325,12 +348,12 @@ def execute(*args, **kw):
<formalpara id="form-Architecture_and_Design-Available_Wallace_Module_Callbacks-cb_action_HOLDmodulefilepath">
<title><literal>cb_action_HOLD(module,filepath)</literal></title>
<para>
- para
+ A callback to this function puts the processing and delivery for the message in <literal>filepath</literal> on hold, awaiting (manual) review.
</para>
</formalpara>
<para>
- A callback to this function is never considered final. Wallace will stop processing the message when this callback function is called, though, pending review. Review procedures could include inserting the message back into either of the configured modules, or accepting, rejecting or discarding (parts of) the message.
+ Although Wallace will stop processing the message pending review, a callback to this function is never considered final. Review procedures could include inserting the message back into either of the configured modules, or accepting, rejecting or discarding (parts of) the message.
</para>
</listitem>
@@ -338,7 +361,7 @@ def execute(*args, **kw):
<formalpara id="form-Architecture_and_Design-Available_Wallace_Module_Callbacks-cb_action_REJECTmodulefilepath">
<title><literal>cb_action_REJECT(module,filepath)</literal></title>
<para>
- para
+ A callback to this function tells Wallace the message in <literal>filepath</literal> is to be rejected.
</para>
</formalpara>
@@ -539,6 +562,214 @@ def execute(*args, **kw):
</itemizedlist>
</para>
+ <section id="sect-Architecture_and_Design-List_of_Wallace_Modules-The_optout_Module">
+ <title>The <literal>optout</literal> Module</title>
+ <para>
+ The <literal>optout</literal> module for Wallace consults an external HTTP service that in turn is to determine whether or not to accept, hold or reject the message.
+ </para>
+ <para>
+ The <literal>optout</literal> module submits one or more POST requests to the configured URL, in succession. One request is made for each unique pair of the envelope sender address and a recipient address (meaning it iterates over the recipient addresses for the message and makes one request per recipient address). A single request contains the following information:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-The_optout_Module-unique_message_id">
+ <title><literal>unique-message-id</literal></title>
+ <para>
+ A unique identifier uniquely identifying the message.
+ </para>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-The_optout_Module-envelope_sender">
+ <title><literal>envelope_sender</literal></title>
+ <para>
+ The envelope sender address for the message.
+ </para>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-The_optout_Module-recipient">
+ <title><literal>recipient</literal></title>
+ <para>
+ The recipient address.
+ </para>
+
+ </formalpara>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+ <para>
+ The <literal>optout</literal> module encapsulates the payload in a JSON object.
+ </para>
+ <para>
+ It expects a result, again contained in a JSON object, that contains the same information as the request, and an additional "result".
+ </para>
+ <para>
+ A simplified example of such Opt-out Consult Service can be found at <ulink url="http://admin.klab.cc/~vanmeeuwen/optout/optout.phps" />.
+ </para>
+ <para>
+ The aforementioned example simply parses the recipient email address and attempts to find a particular action to take in the recipient address extension.
+ </para>
+ <note>
+ <para>
+ The <literal>optout</literal> module has no purpose for results DISCARD and DUNNO, and is only interested in results ACCEPT, DEFER, HOLD and REJECT.
+ </para>
+
+ </note>
+ <para>
+ The <literal>optout</literal> module stores the results for all requests made, until it runs out of recipient addresses to consult the OCS for. When it is done, it splits the original message into the parts for which the result was ACCEPT, DEFER, HOLD and REJECT, if any. Each part of the message contains only the recipient addresses for which that specific action had to be taken.
+ </para>
+ <example id="exam-Architecture_and_Design-The_optout_Module-Opt_out_Example">
+ <title>Opt-out Example</title>
+ <para>
+ Using the example optout consult service available through <ulink url="http://admin.klab.cc/~vanmeeuwen/optout/optout.php" /> (<ulink url="http://admin.klab.cc/~vanmeeuwen/optout/optout.phps">source code</ulink>), the following is an example interation through the <literal>optout</literal> module.
+ </para>
+ <procedure>
+ <step>
+ <para>
+ <ulink url="mailto:John.Doe@example.org">John.Doe@example.org</ulink> sends a message with recipient address <ulink url="mailto:John.Doe+REJECT@example.org">John.Doe+REJECT@example.org</ulink> in the To: header, and recipient address <ulink url="mailto:John.Doe+ACCEPT@example.org">John.Doe+ACCEPT@example.org</ulink> in the CC: header.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ Wallace spools the message in <filename>/var/spool/pykolab/wallace/incoming/tmpASD890</filename>.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ Wallace executes the <literal>optout</literal> module for this message.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ The <literal>optout</literal> module immediately renames the message to <filename>/var/spool/pykolab/wallace/optout/incoming/tmpASD890</filename>.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ The <literal>optout</literal> module reads the message, and consults the OCS with the first pair. The request payload looks as follows:
+ </para>
+ <para>
+
+<screen language="Python">{
+ "unique-message-id": "tmpASD890",
+ "envelope_sender": "John.Doe@example.org",
+ "recipient": "John.Doe+REJECT@example.org"
+ }</screen>
+
+ </para>
+
+ </step>
+ <step>
+ <para>
+ The OCS responds with the following result payload:
+ </para>
+ <para>
+
+<screen language="Python">{
+ "unique-message-id": "tmpASD890",
+ "envelope_sender": "John.Doe@example.org",
+ "recipient": "John.Doe+REJECT@example.org",
+ "result": "REJECT"
+ }</screen>
+
+ </para>
+
+ </step>
+ <step>
+ <para>
+ The <literal>optout</literal> module reads the message, and consults the OCS with the second pair. The request payload looks as follows:
+ </para>
+ <para>
+
+<screen language="Python">{
+ "unique-message-id": "tmpASD890",
+ "envelope_sender": "John.Doe@example.org",
+ "recipient": "John.Doe+ACCEPT@example.org"
+ }</screen>
+
+ </para>
+
+ </step>
+ <step>
+ <para>
+ The OCS responds with the following result payload:
+ </para>
+ <para>
+
+<screen language="Python">{
+ "unique-message-id": "tmpASD890",
+ "envelope_sender": "John.Doe@example.org",
+ "recipient": "John.Doe+ACCEPT@example.org",
+ "result": "ACCEPT"
+ }</screen>
+
+ </para>
+
+ </step>
+ <!-- <step>
+ <para>
+ The <literal>optout</literal> module renames the original message spool file to <filename>/var/spool/pykolab/wallace/optout/processed/</filename>.
+ </para>
+ <para>
+ This is to ensure that, should the daemon's operations be interrupted at this point, data is not lost.
+ </para>
+ </step>// --> <step>
+ <para>
+ The <literal>optout</literal> module creates a new spool file <filename>/var/spool/pykolab/wallace/optout/ACCEPT/tmpQWE123</filename> with the From: header intact, and the CC: header intact. It removes the To: header contents.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ The <literal>optout</literal> module calls callback function <literal>cb_action_ACCEPT('<replaceable>optout</replaceable>', <replaceable>/var/spool/pykolab/wallace/optout/ACCEPT/tmpQWE123</replaceable>)</literal>.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ As a result, Wallace either continues with the next module, or re-injects the message into the MTA for final delivery.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ The <literal>optout</literal> module creates a new spool file <filename>/var/spool/pykolab/wallace/optout/REJECT/tmpGHJ456</filename> with the From: header intact, and the To: header intact. It removes the CC: header contents.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ The <literal>optout</literal> module calls callback function <literal>cb_action_REJECT('<replaceable>optout</replaceable>', <replaceable>/var/spool/pykolab/wallace/optout/REJECT/tmpGHJ456</replaceable>)</literal>.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ As a result, Wallace sends out an NDR for the message, and unlinks the message from the filesystem.
+ </para>
+
+ </step>
+
+ </procedure>
+
+
+ </example>
+
+ </section>
+
</section>