Skip to main content.

! 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. ( Discussion in TWiki:Plugins/ActionTrackerPluginDev )

Features


Syntax Rules

Actions

Write the command %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 (i.e. you can only have one action per line). Standard attributes are

Name Value up Description
who See People The person or team responsible for completing the action. Auto-completed, current user
notify See People wikinames, or e-mail addresses, of people to notify when the action changes. See Notification for details on action notification.
creator See People Who created the action. Auto-completed, current user
closer See People Who closed the action. Auto-completed if state="closed", current user
due See Date Formats The due date Auto-completed, today
created See Date Formats Date the action was created. Auto-completed, today
closed See Date Formats Date the action was closed, if ever. Auto-completed if state="closed", today
state open or closed Set to open if the action is still open; set to closed if the action is closed. To extend the state set, see Non-standard attributes. Auto-completed, open
uid 6 digit number Unique ID of the action. See UIDs. Auto-completed, calculated

For example,

%ACTION{ who="TWikiGuest" due="2 Jan 2004" state="open" notify="AttillaTheHun" }% An action for TWikiGuest
The fields marked Auto-completed are automatically filled in, if they are missing, whenever someone saves the topic containing the action. The default values are as indicated in the table. You can override this behaviour by providing values for any of these attributes when you type the action. Note: you are not recommended to provide a value for the uid (see UIDs) field!

If the action description doesn't all fit on one line you can use shell-style here-document syntax to grab the next few lines. For example,

%ACTION{ who="LittleOysters" due="2 Jan 1884" state="open" }% <<EOF
The time has come, the walrus said,
To speak of many things.
Of shoes, and ships, and sealing wax,
Of cabbages and kings.
EOF
The delimiter must be a sequence of alphanumeric characters, and the closing delimiter must be on a line of its own.

Date formats

Date formats must be as recognised by Time::ParseDate. The following absolute date formats are recognised. Dates containing spaces must be enclosed in double-quotes.

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

People

People are identified to the action tracker using a wikiname (e.g. Main.WilliamWallace or simply WilliamWallace) or an e-mail address (e.g. a_einstein@pto.co.ch). The e-mail address is useful if you want to notify people who aren't registered in the wiki, but bear in mind that if they are outside your firewall, they'll get action notifications but the chances are they won't be able to edit pages and close actions. Very annoying!

E-mail addresses of people are found by the process described below.

You can also use the shorthand me for the currently logged-in user (this is TWikiGuest unless you have been prompted for a username and password). In actions, this will automatically be expanded when the topic is saved, and in searches it will match the currently logged in user.

Groups

You can assign an action to a group defined using a TWiki group topic (see TWikiDocumentation). Alternatively you can give a list of people as the value of the attribute. For example,

%ACTION{who=TWikiAdminGroup ...}%
%ACTION{who="KnutHaraldsen,MagnusMagnusson" ...}%
Note in general you should not use these mechanisms for assigning actions, because the actions so created are not specific. Actions should be assigned to one person only, so that it's clear who is responsible for them.

UIDs

Each action is assigned a Unique Identifier (UID) when it is created. This UID is a six-digit number, and is generated when the action is first saved by incrementing a number in a special file (data/atUidReg under the TWiki installation). If this file is accidentally deleted, or is not writable, then you will have problems and you may get duplicate UIDs. Normally this won't matter a hoot, as UIDs only have to be unique within a single topic, but if you are using UIDs for something else you will need to take care.

Action searches

Write the command %ACTIONSEARCH{ attributes }% anywhere in a TWiki topic. Standard attributes are

Name Value Description
who See People Person responsible for closing the action.
notify See People Persons who want to be notified of a change
state late, or any legal state value Set to late to search for late actions; set to any any legal state value to search for actions in that state. See Settings for details on how to extend the state set.
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. Webs marked NOSEARCHALL will not be searched.
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.
due See Date Formats Due date for the action.
creator See People Who created the action.
created See Date Formats Date the action was created.
closed See Date Formats Date the action was closed, if ever.
closer See People Who closed the action.
uid 6 digit number Unique ID of the action.
format Presentation format See Formatting tables
header Presentation format See Formatting tables
orient Presentation format See Formatting tables
sort Comma-separated list of field names Fields to sort the matched actions by. For example, sort="$who,$due" will sort by who first and then due. This field is optional; by default the table will be sorted by due date.
For example,
%ACTIONSEARCH{ who="me" state="late" }%
%ACTIONSEARCH{ who="me" open late }%
%ACTIONSEARCH{ who="TWikiGuest" state="open" within="7" }%
%ACTIONSEARCH{ web=".*" who="Genghis.Khan@mongol.empire.org" state="open" within="7" }%

Query-by-example action search

Who:
Notify:
State:
Within: days
Web:
Topic:
 
Result: %ACTIONSEARCH{ who="" notify="" state="" within="" web="" topic="" }%


Notification

ActionTrackerPlugin comes with a notifier script, like the mailnotify script used for WebNotify (see MonitoringSiteActivity? for more information on setting up mailnotify). This script allows you to:

The frequency with which actions are notified depends on how you set up your cron (or equivalent) jobs on the server.

The actionnotify script interprets its parameters as a search expression of the same type as that used in %ACTIONSEARCH%. All actions which match that expression will be notified to their owners. For example, you could set up the cron jobs as follows:

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\"
(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: At Wind River they notify folks three times a week on Mon, Wed and Fri for open action items due within 8 days. Crontab entry for geeks:

0 0 * * 1,3,5 (cd /twiki1/httpd/twiki-bin; ./actionnotify state=open within=8 'web=[CEIMPSW].*' > /twiki1/httpd/htdocs/pub/actionnotify.txt 2>&1)

You can configure the fields which are scanned to detect state changes; see Settings.

Translating names to e-mail addresses

The wikiname of the user to be notified is translated to a mail address according to the following rules:

Note: If a name cannot be translated to an e-mail address using the mechanisms described above, a warning will be output to data/warning.txt..

The actionnotify script is also used to notify users who have registered an interest in being notified when an action changes. This function of the script is activated when you use the changedsince parameter. changedsince is used to specify the time period within which changed actions are interesting. Any action which has changed in the given period will be notified to all users who have registered an interest in that action using notify. The changedsince value is a relative date string, which uses the following formats

where units may be minutes, days, hours, weeks, months or even years. count is just an integer. dow is the name of a day of the week. For example:
changedsince="last monday"
changedsince="now - 3 days"
changedsince="- 36 hours"
changedsince="3 days ago"

Obviously you have to be careful to synchronise your changedsince expression with the activation of your cron job. The ideal is to specify the same delta as the gap between cron activations. For example,

0 0 * * * /home/twiki/bin/actionnotify 'web="News" changedsince="yesterday"'
will notify registered users of action changes that occurred in the last 24 hours. Note the use of single quotes to prevent expansion in the shell.

Notes:

  1. Not all action changes get notified, only changes to certain sensitive fields. You can change the set of fields that are sensitive to changes by setting the NOTIFYCHANGES parameter, as described in Settings, below.
  2. Unlike all other search terms, changedsince works as an OR term rather than an AND term. If you use a compound expression like late,changedsince=yesterday, this will not give you all late actions that changed since yesterday. Instead, it will give you all late actions and all actions that changed since yesterday.
  3. If you give the parameter DEBUG to the actionnotify script, it will print out the mails that would have been sent to STDOUT. This is useful for debugging, and may be useful if you have some other processing in mind (such as piping to an alternative mail program).


Customisation

Formatting search tables

The header, format and orient parameters of %ACTIONSEARCH{}% support formatting of the action table using a similar syntax to that described in FormattedSearch. For example:

%ACTIONSEARCH{ web="Directors" state="open" format="|$who|$text|$edit|" header="|Director|Films||" orient="rows" }%

Name: Expands To:
$who Who is responsible for the action
$due When the action is due
$state Current state of the action (see also note below)
$notify Who to notify when the action state changes
$closed When the action was closed, and who closed it
$creator Who created the action
$created When the action was created
$edit A link to the action editor for this action
$uid Unique identifier for the action
$web Name of the web containing the action
$topic Topic name containing the action
$text Formatted action text
$n or $n() New line
$nop or $nop() Is a "no operation". This variable gets removed.
$quot Double quote (").
$percnt Percent sign (%)
$dollar Dollar sign ($)

A default format for actions and action search results can be defined in this topic or the WebPreferences topic of the current web. See Settings for more details.

Non-standard Attributes

As well as the standard attributes you can add non-standard attributes to actions, and use them in searches. For example:

%ACTION{ who="EmperorHadrian" due="1 Jan 0053" state="closed" legion="7th" cohort="6th" maniple="3rd" }% Build a wall to keep the Scots out of England

Non-standard attributes must be lower-case words. The following names may not be used for non-standard attributes: closed, closer, created, creator, dollar, due, edit, format, header, late, n, nop, notify, percnt, quot, sort, state, text, topic, uid, web, who, within.

To define non-standard attributes you need to set the value of EXTRAS in this topic (or to the WebPreferences topic of each web) - see Settings below. All attributes must be given a type, which is used by the formatter, the search engine and the action editor. For example,

   * Set EXTRAS = |plaintiffs,names,16|decision,text,16|sentencing,date|sentence,select,"life","5 years","community service"|
The following types are supported:
Type Format Description
select select, size, "option 1", "option 2", ... Can take one of the string values option1, option2,.... etc.
names names, size One or more wikinames or e-mail addresses.
text text, size An arbitrary text field
date date, size A date in one of the formats described above. See Date Formats
In the above, size is a single number, which is the width (in characters) of the text box in the action editor for text, names and date, and the number of options to show in select..

Note that there is one exception to the "no redefinition" rule above; the state attribute can be extended to take extra states. However if you want the closure functionality (closed, closer, and late actions) to work, the closed state must be retained. To extend the set of states, simply include a definition of state in the EXTRAS definition:

   * Set EXTRAS = |state,select,1,"open","fried","boiled","poached","closed"|

Searching for non-standard attributes

You can of course search for values of non-standard attributes. For example:
%ACTIONSEARCH{ sentence="life" }%
If a non-standard attribute is declared as type text you can use perl regular expressions in the search. Searches for values of type names will match any-to-any. For example,

%ACTIONSEARCH{ car="VolkswagenBeetle,MercedesCoupe" }%

will match both of the following actions:

%ACTION{ car="VolkswagenBeetle,AudiSport" ... }%
%ACTION{ car="ToyotaSupra,MercedesCoupe,ColtLancer" ... }%


ActionTrackerPlugin Settings

These settings can be overridden in the WebPreferences topic of the current web (by defining ACTIONTRACKERPLUGIN_TABLEHEADER or ACTIONTRACKERPLUGIN_TABLEFORMAT etc).


Plugin Installation Instructions

Note: These instructions are for the TWiki maintainer. No changes to your browser are required. This plugin makes extensive use of new features added to TWiki in the Feb 2003 release. Earlier versions lack all the features described here. Make sure you install using the zip appropriate to your TWiki installation. If you install an earlier version of the plugin with the Feb 2003 release, note that change notification will not function correctly.

Upgrade notes

Earlier versions of this plugin installed a number of files that are no longer required. Relative to the root of the TWiki installation these are:
File What's happened
data/Plugins/ActionTrackerPlugin.txt Moved to data/TWiki
templates/actionchangenotify.tmpl Merged with actionnotify.tmpl
bin/editaction Merged into plugin code, using hooks added in Feb 2003 TWiki release
bin/previewaction Merged into plugin code, using hooks added in Feb 2003 TWiki release

The mechanism for defining notification groups as lists of "EMail" lines in a topic in Main is no longer supported. Please upgrade to the mechanism described herein.


Known Issues

Use of unpublished functions

The following unpublished TWiki core functions are used:
TWiki::initialize()
TWiki::getGmDate()
TWiki::getTWikiLibDir()
TWiki::Net::sendEmail()

Corruption of action items with Mozilla browser

OLD - may be fixed.

Action lines are joined together if edited by a Mozilla browser, resulting in an odd display.

Behaviour of egrep

The output of the $egrepCmd in TWiki.cfg (with no switches) must be of the form:

   filename.txt: ...matched text...
   
While this is true for all UNIX grep implementations, it may be a potential issue for other operating systems.


Plugin Info

Plugin Author: TWiki:Main/CrawfordCurrie
Plugin Version: 2.0
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
  26 Sep 2002: Added changedsince notify support, added support for editing in a seperate window, incorporated attribute syntax corrections contributed by PeterThoeny, sorted ACTIONSEARCH output and action notifications
  30 Jan 2003: Query-by-example action search with notify field; notfication of change emails and actions email are sent as one; notify field was added to topic view and edit; various bug fixes by TWiki:Main/PaulineCheung
  30 Apr 2003: Version 2.0; Large sections rewritten to take advantage of improvements in Plugin support, eliminating two scripts in bin. Added UIDs and formattable action searches
  21 May 2003: Non-standard fields. Configurability of tables and action editor. Non-standard attributes. Eliminated chdir. Multi-line actions. Optimisation of notifies.
CPAN Dependencies: Time::ParseDate
Perl Version: 5.0
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/ActionTrackerPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/ActionTrackerPluginDev

Related Topics: TWikiPreferences, 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. Please, please, please run, and extend if necessary, the test set!

Some ideas:

  1. Make the go to action link in action text a button image.
  2. Fix the "close subwindow on save" functionality. See ActionTrackerPlugin.pm, search for $submitScript.
  3. Generalise the search to support within and late style searches on all date fields, including non-standard ones.
  4. A really brave soul might consider moving action change notification to where it belongs; in the beforeSaveHandler.
  5. You could turn this into a full-blooded issue tracker by constraining state transitions.
  6. Make it work for a PC server

Developer discussion is in TWiki:Plugins/ActionTrackerPluginDev.

Copyright

This code is a development of Motorola Inc. and is protected by the following copyrights:

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