Action Tracker

This plugin provides support for tracking actions embedded in TWiki topics. Actions captured this way can then be tracked from anywhere you want. For example, this capability is particularly useful for meeting minutes. As you write the minutes during the meeting, you simply enter the actions into the text and as soon as the topic is saved, the actions "go live". But that's not the only application. The action tracker can also be used:

• for personal to-do lists
• for highlighting things for attention
• for reminding you of important events

Actions are nicely formatted for display, and automatic notification of actions is supported using 'cron'.

Tags:

create new tag

Features

• Actions may be embedded in TWiki topics.
• Actions can be listed using searches.
• A script is provided for automatic action notification.
• Actions can be assigned to individuals, or to predefined groups of individuals.
• Fully configurable.

Syntax Rules

Actions

Write the command %ACTION{ attributes }% ...  %ENDACTION% anywhere in a TWiki topic, where ... represents the action description. Standard attributes are

Name	Value	Description	Auto-completed
who	See People	The person or team responsible for completing the action.	current user
due	See Date Formats	The due date	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.	open
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.	current user
created	See Date Formats	Date the action was created.	today
closer	See People	Who closed the action.	if (and only if) state="closed", current user
closed	See Date Formats	Date the action was closed, if ever.	if (and only if) state="closed", today
uid	6 digit number	Unique ID of the action.	calculated

For example,

%ACTION{ who="TWikiGuest" due="2 Jan 2004" state="open" notify="AttillaTheHun" }% An action for TWikiGuest %ENDACTION%
%ACTION{ who="LittleOysters" due="2 Jan 1884" state="open" }%
The time has come, the walrus said,
To speak of many things.
Of shoes, and ships, and sealing wax,
Of cabbages and kings.
%ENDACTION%

The fields with an entry in the 'Auto-completed' column 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!

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.
within	a number of days	Search for actions that are within a number of days of their due date. Usually used in conjunction with other attributes, such as state="open". Works in both directions, so you can use this to search for actions which are going to fall due within a certain number of days, or a negative number for actions that fell due between a time in the past and now.
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	Absolute or relative date expression. See Date Formats	Due date for the action.
creator	See People	Who created the action.
created	Absolute or relative date expression. See Date Formats	Date the action was created.
closed	Absolute or relative date expression. See Date Formats	Date the action was closed, if ever.
closer	See People	Who closed the action.
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" }%

When you are searching for fields containing dates (such as closed, created and due) you can prepend one of the conditions >, <, >= and <= to the date. For example, closed=">1-Jan-1999" will match all actions that have been closed at any time since 1-Jan-1999, and created=">= 1-Jan-2000" will match all actions created this century. You can also specify dates relative to the current date and time. See Date Formats for details of how to specify relative dates. For example,

%ACTIONSEARCH{ state="closed" closed="> 7 days ago"}%

will search for all actions closed in the last 7 days.

Date formats

Absolute date formats

Absolute dates are required in action specifications. 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.

• 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/yy or mm/dd/yyyy' formats, to avoid confusing users in Europe. Note that due to limitations in the Time::Parsedate module, dates before 1970 will not work as expected.

Relative date formats

When you are searching for fields containing dates (such as closed, created and due) you can specify dates relative to the current date and time. For example:

Syntax	Example	Notes
Dow after next	Tuesday after next
Dow	Tuesday	last Tuesday
next Dow	next Thursday
tomorrow	tomorrow
today	today
yesterday	yesterday
last dow	last wednesday
last week	last week	7 days ago
now	now
now + count units	now + 2 years
now - count units	now - 3 weeks
+ count units	+ 31 days
- count units	- 2 months
count units ago	10 days ago

Valid units are minutes, hours, days, weeks, years.

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.

Notification

Action Tracker comes with a notifier script, like the mailnotify script used for WebNotify. This script allows you to:

• examine all the actions in all webs (except those specified NOSEARCHALL) and notify owners of the state of actions,
• find actions that have changed state, and notify people who have registered an interest in that action.

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.

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:

• If the user has a personal page, and that personal page contains a line or lines matching
  spaces * Email: email address
  or
  spaces * E-mail: email address
  Alternatively if the topic is a group definition (the name ends in 'Group') then the line
  spaces * Set GROUP =
  is used to determine the wikinames of the people in the group. These are resolved to email addresses recursively. If that fails,
• If they appear in any WebNotify in any web, in the form of a line that gives an email address, then that address is used.
• If this fails and the 'who' name is a valid e-mail address, for example person@domainPLEASENOSPAM.co.uk, then that name is used.

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..

This Topic Is Referenced By These Topics:
Related Links: FindMyAssignedActions, HelpIndex, JimCrumCalendar, MeetingMinutesTemplate, PersonalCalendarTemplate, ProjectCalendarTemplate, ProjectTaskTemplate, WebStatistics

---

---

Was This Topic Useful to You?

Others rated this topic as shown. Please include your rating.

Choice

Select ...Very UsefulSomewhat UsefulNo OpinionNot Useful

-- JimCrum - 20 Feb 2008