%META:TOPICINFO{author="pthoeny" date="1026518625" format="1.0" version="1.7"}%
---++ Action Tracker Plugin

This plugin provides support for action tracking and notification in meeting minutes. It can also be used for private reminders, for example TODO lists and diary entries.

---+++ Features

	* Action tags may be added to TWiki topics that will be displayed formatted in-line.
	* Actions in a web can also be listed using searches.
	* A script is provided for automatic action notification.
	* Actions can be assigned to individuals, or to predefined groups of individuals.

---++ Syntax Rules

---+++ Actions

Write the command =%<nop>ACTION{ attributes }%= anywhere in a TWiki topic. All the text following the final % up to the next end-of-line is taken as the action description. Supported attributes are
	| *Name* | *Value* | *Description* |
	| who | a wiki name, or an e-mail address | The person or team responsible for completing the action |
	| due | A valid date as understood by Time::ParseDate | The due date |
	| state | "open" or "closed" | Set to "open" if the action is still open;<br />Set to "closed" if the action is closed |

For example,
<pre>
%<nop>ACTION{ who="TWikiGuest" due="2 Jan 2004" state="open" }% An action for TWikiGuest
</pre>

#DateFormats
---++++ Date formats
The following absolute date formats are recognised. Dates containing spaces must be enclosed in double-quotes.
	* Dow, dd Month yy
	* Dow, dd Month yyyy
	* Dow, dd Month
	* dd Month yy
	* dd Month yyyy
	* Month day{st,nd,rd,th}, year
	* Month dd yyyy
	* yyyy/mm/dd
	* yyyy/mm
	* mm/dd/yy
	* mm/dd/yyyy
	* mm/yy
	* yy/mm		(only if year > 12)
	* yy/mm/dd	(only if year > 12 and day < 32)

You are *strongly* recommended never to use the 'mm/dd/yyyy or mm/dd/yyyy' formats, to avoid confusing users in Europe (like me).

---+++ Action searches

Write the command =%<nop>ACTIONSEARCH{ attributes }%= anywhere in a TWiki topic. Supported attributes are
	| *Name* | *Value* | *Description* |
	| who | a wiki name or an e-mail address, or 'me' for the currently logged-in user (this is 'TWikiGuest' unless you have been prompted for a username and password) | The name of the person responsible |
	| state | "late", "open" or "closed" | Set to "late" to search for late actions;<br /> Set to "open" to search for open actions;<br /> Set to "closed" to search for closed actions |
	| within | a number of days | Search for actions that are within a number of days of their due date |
	| web | Perl regular expression | A regular expression that matches the names of all the webs to search. If this attribute is omitted, the default is to search only the current web. Searching many webs is much slower, especially in a large installation. | 
	| topic | Perl regular expression | A regular expression that matches the names of all the topics to search. If this attribute is omitted, the default is to search all the topics in the selected webs. | 

For example,
<pre>
%<nop>ACTIONSEARCH{ who="me" state="late" }%
%<nop>ACTIONSEARCH{ who="TWikiGuest" state="open" within="7" }%
%<nop>ACTIONSEARCH{ web=".*" who="Genghis.Khan@mongol.empire.org" state="open" within="7" }%
</pre>

#QueryByExample
---+++ Query-by-example action search

<form name="searchaction" action="%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%#QueryByExample">
|  Who: | <input type="text" name="qwho" value="%URLPARAM{"qwho"}%" size="20" /> |
|  State: | <select name="qstate"> <option>%URLPARAM{"qstate"}%</option> <option>open</option> <option>late</option> <option>closed</option> <option></option> </select> |
|  Within: | <input type="text" name="qwithin" value="%URLPARAM{"qwithin"}%" size="3" /> days |
|  Web: | <input type="text" name="qweb" value="%URLPARAM{"qweb"}%" size="20" /> |
|  Topic: | <input type="text" name="qtopic" value="%URLPARAM{"qtopic"}%" size="20" /> |
| | <input type="submit" value="Go" /> |
</form>
%ACTIONSEARCH{ who="%URLPARAM{"qwho"}%" state="%URLPARAM{"qstate"}%" within="%URLPARAM{"qwithin"}%" web="%URLPARAM{"qweb"}%" topic="%URLPARAM{"qtopic"}%" }%

---+++ Assigning actions to groups

To assign an action to a group you must set up a pseudo-user that represents the group. Create a new topic in the '%MAINWEB%' web with the name of the group as the name of the page, and then add lines using the format<br />
	_three spaces_ * Email:<br />
or<br>
	_three spaces_ * E-mail:<br />
one per member of the group. For example, you might have the topic Main.<nop>EmpireBuilders with contents:
<pre>
	* Email: Atilla@huns.com
	* E-mail: Genghis.Khan@mongol.empire.org
</pre>
You can then assign actions using =who="EmpireBuilders"=. Note that this technique allows you to assign actions to groups of people who are *not* registered with your TWiki (and may not wish to be).

---+++ Notification

%TOPIC% comes with a notifier script, like the =mailnotify= script used for WebNotify (see TWiki.MonitoringSiteActivity for more information on setting up mailnotify). This script examines all the actions in all webs and notifies owners of actions. The frequency with which actions are notified depends on how you set up your cron (or equivalent) jobs on the server. The mailer script takes a single parameter, which is a search expression of the same type as that used in %<nop>ACTIONSEARCH%. All actions which match that expression will be notified. For example, you could set up the cron jobs as follows:
<pre>
0 * * * * /home/twiki/bin/actionnotify state=late
0 8,16 * * * /home/twiki/bin/actionnotify state=open within=3
0 0 * * * /home/twiki/bin/actionnotify state=open within=7
0 0 * * 1 /home/twiki/bin/actionnotify state=open within=30
</pre>
(If you don't know cron, the first 5 fields are minute, hour, day of month, month and day of week. * means 'every'). This crontab will notify actions according to the schedule:
	1 Actions that are late will be notified every hour, on the hour
	2 Actions that are still open within three days of their due date will be notified twice a day, at 8am and 4pm
	3 Actions that are still open within seven days of their due date will be notified once a day, at midnight.
	4 Actions that are still open within thirty days of their due date will be notified once a week, at midnight on monday.
A rather aggressive schedule!

__Note:__ Here at Wind River we notify folks twice a week (Mon &amp; Wed) for open action items due within 8 days. <br /><font size="-2">Crontab entry for geeks: =0 0 * * 1,3 (cd /twiki1/httpd/twiki-bin; ./actionnotify state=open within=8 'web=<nop>[CEIMPSW].*' &gt; /twiki1/httpd/htdocs/pub/actionnotify.txt 2&gt;&amp;1)= </font>

The wiki name of the user to be notified is translated to a mail address according to the following rules:
	* If they are listed in WebNotify *in any web*, the mail address given there is used.
	* If this fails and they have a personal page, and that personal page contains a line or lines matching<br />
	_three spaces_ * Email: _email address_ <br />
	or<br>
	_three spaces_ * E-mail: _email address_ <br />
	then the notification is sent to *all* those e-mail addresses. This is how you assign actions to groups.
	* If this fails and the 'who' name is a valid e-mail address, for example person@domain.co.uk, then that name is used.

---++ <nop>%TOPIC% Settings

	* Set SHORTDESCRIPTION = Adds support for action tags in topics, and automatic notification of action statii
	* Set DEBUG = 0

---++ Plugin Installation Instructions

	* Make sure you have Time::ParseDate installed in your perl installation (available from www.cpan.org)
	* Download the ZIP file from the Plugin web (see below). Contents:
	| *File:* | *Description:* |
	| ==%TOPIC%.xml== | Ant build file |
	| ==data/Plugins/%TOPIC%.txt== | Plugin topic |
	| ==bin/actionnotify== | Mailer script |
	| ==bin/editaction== | Action editor |
	| ==bin/previewaction== | Edit preview script |
	| ==templates/actionnotify.tmpl== | Applet page template |
	| ==templates/editaction.tmpl== | Edit page template |
	| ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
	| ==lib/TWiki/Plugins/%TOPIC%/Action.pm== | Perl support module |
	| ==lib/TWiki/Plugins/%TOPIC%/ActionNotify.pm== | Perl support module |
	| ==lib/TWiki/Plugins/%TOPIC%/ActionSet.pm== | Perl support module |
	| ==lib/TWiki/Plugins/%TOPIC%/Attrs.pm== | Perl support module |
	| ==lib/TWiki/Plugins/%TOPIC%/test.zip== | Test scripts |
	* Unzip ==%TOPIC%.zip== in your twiki installation directory.
	* If the plugin is installed and enabled correctly you should see a formatted action below: %ACTION{who=TWikiGuest,due="1 Jan 2003",open}% Example action

---+++ Known issues

---++++ Behaviour of egrep

The output of the =$egrepCmd= in TWiki.cfg (with no switches) must be of the form:
	<pre>
	filename.txt: ...matched text...
	</pre>
	While this is true for all UNIX grep implementations, it may be a potential issue for other operating systems.

---+++ Plugin Info

|  Plugin Author: | Main.CrawfordCurrie |
|  Plugin Version: | 1.1 |
|  Change History: | 4 Jan 2002: Initial version |
|			| 9 Jan 2002: Bugfix version |
|			| 11 Jan 2002: Added ACTIONSEARCH for selected webs and topics; Changed action editor to use a template; Eliminated UNIX dependencies; Fixed formatting of actions in bulleted lists |
|			| 14 Feb 2002: Sorted ACTIONSEARCH results by due date; Fixed bugs editaction kills form data, Actions flagged as late the day before, TWiki table and bullet formatting doesn't work within action text |
|  CPAN Dependencies: | Time::ParseDate |
|  Perl Version: | 5.0 |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |

__Related Topics:__ %TWIKIWEB%.TWikiPreferences, %TWIKIWEB%.TWikiPlugins

---++++ Further development

Further development of this code is welcomed. It is recommended that you unpack the distribution into a development directory and use the supplied Ant (http://jakarta.apache.org) build file which provides targets to run the test suite, and install and uninstall your development code into a test installation.

---++++ Copyright

This code is a development of the Architectures and System
Platforms group of Motorola Inc. and is protected by the following
copyrights:
	* Copyright (C) 2002 Motorola. All Rights Reserved.

---++++ License

As required for the publication of all extensions to TWiki, this
software is published under the terms of the GNU General Public
License.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details, published at
http://www.gnu.org/copyleft/gpl.html
