GordonBrown agreed to a zero tax rate for all self-employed software engineers, to make up for past unfair treatment. %ACTION{who="GordonBrown" due="5th April 2008"}% Repay all unfairly levied taxes %ENDACTION% %ACTION{who="AlistairDarling" due="25th Dec 2007"}% Contact Santa to find out who is going to pay for it %ENDACTION% AlistairDarling observed that this might adversely impact the government hors d'ouvres budget.But that's not the only application. The action tracker can also be used for:
%ACTION{
attributes }% ... %ENDACTION%
anywhere in a 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 | |
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. See UIDs. | calculated |
%ACTION{ who="WikiGuest" due="2 Jan 2004" state="open" notify="AttillaTheHun" }% An action for WikiGuest %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 must not provide a value for the
uid
(see UIDs) field!
Note that the due
field is not auto-completed. If you don't specify a due date for an action, the action is treated as due on a 'to be decided' (TBD) date. TBD actions are always shown in action searches, to help encourage you to timeframe them.
%ACTIONSEARCH{
attributes }%
anywhere in a 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. You can also use a Perl regular expression, which must match the entire state name e.g. state="open|closed" will match either open or closed states, but no other states, and state="(?!closed).*" will match every state except closed . Google for perlre for help with Perl regular expressions. |
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" . If you give it a simple number N, it will match actions that are due within N days either side of the current date. If you give N with a leading '+', this restricts the search to N days in the future. If you give N with a leading '-', it matches only actions that fell due in the last N days. |
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. |
uid |
6 digit number | Unique ID of the action. |
format |
Presentation format | See Formatting tables |
nohtml |
Presentation control | See Formatting tables |
header |
Presentation format | See Formatting tables |
footer |
Presentation format | See Formatting tables |
orient |
Presentation format | See Formatting tables |
separator |
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. Columns containing only numeric data will be sorted numerically, all other data by alphabetic order. |
%ACTIONSEARCH{ who="me" state="late" }% %ACTIONSEARCH{ who="WikiGuest" 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.
Time::ParseDate
.
The following absolute date formats are recognised. Dates containing spaces must be enclosed in double-quotes.
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 |
minutes
, hours
, days
, weeks
, years
.
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 the guest user 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.
You can assign an action to a group. Alternatively you can give a list of people as the value of the attribute. For example,
%ACTION{who=AdminGroup ...}% %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.
pub/_work_areas/ActionTrackerPlugin/UIDRegister
under the 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 the file is persistantly inaccessible it could be a bit of a nuisance.
mailnotify
script used for WebNotify. 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.
Be careful what user you use to run this script. It will write the Foswiki log files, and if these log files are left in a state where they can't be written to by the Foswiki server, you may break your site. Theactionnotify
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:
actionnotify "header=\"| Assigned to | Due ||\"" format=\"'| $who | $due | $edit |'\" state="open"Note that the
actionnotify
script must be run from the bin
directory. This is so it can pick up the path configuration file, setlib.cfg
.
For example, you could set up the cron jobs as follows:
0 * * * * cd /home/foswiki/bin && ../tools/actionnotify "state=\"late\"" 0 8,16 * * * cd /home/foswiki/bin && ../tools/actionnotify "state=\"open\" within=\"3\"" 0 0 * * * cd /home/foswiki/bin && ../tools/actionnotify "state=\"open\" within=\"7\" 0 0 * * 1 cd /home/foswiki/bin && ../tools/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:
0 0 * * 1,3,5 (cd .../bin; ../tools/actionnotify state=open within=8 'web=[CEIMPSW].*' > .../logs/actionnotify.txt 2>&1)You can configure the fields which are scanned to detect state changes; see Settings.
The wikiname of the user to be notified is translated to a mail address according to the following rules:
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
yesterday
last
dow
last week
now
- count units
-
count units
ago
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 * * * cd /home/foswiki/bin && ../tools/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:
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.
changedsince
requires RCS, and will not work with RcsLite.
header
, footer, =format
, separator
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*||" footer="|*Director*|*Films*|" separator="$n" orient="rows" }%The available
$formattingtokens
are:
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 |
$link |
An icon that links to tha actual action |
$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 ($ ) |
$statebutton(name,state) |
Displays a button that will change the current state of the action to the named state. If the action is already in that state, nothing is displayed. name is the string used in the button and state is the name of the target state e.g. $statebutton(Close,closed) |
The header and format parameters can also be used with the actionnotify script.
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. Because it is useful most of the time to format the output using HTML for links and highlighting, this is the default. If you just want a plain TML table (for example, if you are going to post-process the output) then setnohtml="on"
.
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 %ENDACTION%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 ACTIONTRACKERPLUGIN_EXTRAS - see Settings below. This is a wiki-table format list of attribute names, each with a type, a size, and optional additional data. For example, to define the non-standard attributes plaintiffs
, decision
, and sentencing
, we might define ACTIONTRACKERPLUGIN_EXTRAS
as follows:
* Set ACTIONTRACKERPLUGIN_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 option 1, option 2,.... 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 |
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 ACTIONTRACKERPLUGIN_EXTRAS definition:
* Set ACTIONTRACKERPLUGIN_EXTRAS = |state,select,1,"open","fried","boiled","poached","closed"|
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" ... }% ... %ENDACTION% %ACTION{ car="ToyotaSupra,MercedesCoupe,ColtLancer" ... }% ... %ENDACTION%
The following preferences control different aspects of the action tracker's behaviour. You can override the defaults for these preferences in Main.SitePreferences, the WebPreferences topic of the current web, or in individual topics, using the standard 'Set' syntax e.g:
* Set ACTIONTRACKERPLUGIN_EDITORIENT = rows
Preference | Default | Description |
---|---|---|
ACTIONTRACKERPLUGIN_EXTRAS |
none | Non-standard attributes - see Non-standard attributes above. |
ACTIONTRACKERPLUGIN_NOTIFYCHANGES |
$who,$due,$state,$text |
The fields to scan to detect changes for actionnotify. Changes in other fields are ignored. |
Preference | Default | Description |
---|---|---|
ACTIONTRACKERPLUGIN_TABLEHEADER |
| Assigned to | Due date | Description | State | Notify || |
The default format of an action output, unless overridden by format , header etc. The following fields can be output: web , topic , text , who , due , notify , uid , creator , state , edit , and any ACTIONTRACKERPLUGIN_EXTRAS you may have. TABLEHEADER defines the column headings, TABLEFORMAT defines the contents of the columns, and if TABLEORIENT is set to rows , action tables will be aligned as rows of values instead of the default columns of values. |
ACTIONTRACKERPLUGIN_TABLEFORMAT |
| $who | $due | $text $link | $state | $notify | $edit | |
|
ACTIONTRACKERPLUGIN_TABLEORIENT |
cols |
|
ACTIONTRACKERPLUGIN_TEXTFORMAT |
Action for $who, due $due, $state$n$text$n$link$n |
The alternative text format of an action, as seen by a mail recipient who doesn't accept HTML in mail. Used when mailing action or change notifications. |
ACTIONTRACKERPLUGIN_CSS |
%PUBURL%/%SYSTEMWEB%/ActionTrackerPlugin/styles.css |
Full URL of the CSS to use in formatting actions. This file is also called from the mail generated by the actionnotify script, so you have to use an absolute URL here, and the URL has to be visible to anyone who might receive an action notification. |
ACTIONTRACKERPLUGIN_DEFAULTDUE |
9999999999 |
If an action has no due date defined when it is created, then it is treated (for sorting etc) as if it was due at this time. This is a number of seconds since 1st Jan 1970, and should be 0 to sort actions that have no due date to the start of a list, or a very large number to sort them to the end. |
ACTIONTRACKERPLUGIN_DISABLECONTROLS |
0 |
If set to 1, the action tracker will not display any active controls (edit link, goto link, state shrotcuts etc.). Implies ACTIONTRACKERPLUGIN_ENABLESTATESHORTCUT=0 |
ACTIONTRACKERPLUGIN_ENABLESTATESHORTCUT |
1 |
If set to 1, the action tracker will show action states using a drop-down menu, to allow viewers to quickly and easily change action states. You can disable this feature by setting this to 0. |
atpStateopen
) that is used to render the HTML 'select' element when ENABLESTATESHORTCUT
is on. If you extend the range of states, you will need to add new CSS classes as well.
Preference | Default | Description |
---|---|---|
ACTIONTRACKERPLUGIN_EDITHEADER |
| Assigned to | Due date | State | Notify | |
Format of the header |
ACTIONTRACKERPLUGIN_EDITFORMAT |
| $who | $due | $state | $notify | |
Format of the data |
ACTIONTRACKERPLUGIN_EDITORIENT |
cols |
Horizontal (rows) or vertical (cols) orientation |
ACTIONTRACKERPLUGIN_EDITBOXWIDTH |
70 |
Override default EDITBOXWIDTH for the action editor |
ACTIONTRACKERPLUGIN_EDITBOXHEIGHT |
22 |
Override default EDITBOXHEIGHT for the action editor |
%ACTIONNOTIFICATIONS{}%
and %ACTIONTRACKERPREFS%
features.
Preference | Default |
---|---|
ACTIONTRACKERPLUGIN_DEBUG |
0 |
You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.
Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results. You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)cd /path/to/foswiki perl tools/extension_installer <NameOfExtension> installIf you have any problems, or if the extension isn't available in
configure
, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.
Assigned to | Due date | Description | State | Notify | |
---|---|---|---|---|---|
WikiGuest | 01 Jan 2003 | Example action | open | edit |
Who | WikiGuest |
---|---|
Due | 01 Jan 2003 |
State | open |
Description | Example action |
action
template shipped with the Foswiki:Extensions.CommentPlugin to create actions, then you must put the CommentPlugin before the ActionTrackerPlugin in the {PluginsOrder}
configuration option.
Thanks are due to the following sponsors, who have helped make this plugin possible:
Change History: | ||||||||||||||||
2.4.12 (5 Sep 2018) | Foswiki:Tasks/Item14757: fix indirect "Unescaped left brace in regex..." warnings | |||||||||||||||
2.4.11 (7 May 2017) | Foswiki:Tasks/Item12315: add missing Config.spec; Foswiki:Tasks/Item12823: add "auto-generated" email header; Foswiki:Tasks/Item14382: fix unescaped braces; Foswiki:Tasks/Item14231: set REST options; Foswiki:Tasks/Item11587: eliminate calls to readTopicText, rework tests | |||||||||||||||
2.4.10 (27 Feb 2013) | Foswiki:Tasks/Item11832: restored link targets; Foswiki:Tasks/Item12315: recoded JS for more recent jQuery version; now minimum 1.7.0 required; added checker for jquery version; Foswiki:Tasks/Item8894: after edit, redirect back to the linking topic | |||||||||||||||
2.4.9 (21 Dec 2011) | Foswiki:Tasks/Item11380: add better message for lease conflict | |||||||||||||||
2.4.8 (8 Dec 2011) | Foswiki:Tasks/Item11340: Fix ACTIONTRACKERPLUGIN_CSS as per documentation | |||||||||||||||
2.4.7 (27 Oct 2011) | Foswiki:Tasks/Item11155: Use Foswiki date format settings for rendering the pop-up calendar dates instead of hardcoding them - Foswiki:Main.RaulFRodriguez | |||||||||||||||
2.4.6 (24 Sep 2011) | Foswiki:Tasks/Item11141: corrected problem with rendering $link in view | |||||||||||||||
2.4.5 (26 May 2011) | Foswiki:Tasks/Item2021: added a ink to the text mail notification format | |||||||||||||||
2.4.4 (18 May 2011) | Foswiki:Tasks/Item10615: fix pop-up editing when an extra select field is not included in the editor. Improve the presentation when a state field changes. | |||||||||||||||
2.4.3 (19 Apr 2011) | Foswiki:Tasks/Item10613: Fix for calendar popup in action edit form | |||||||||||||||
2.4.2 (4 Feb 2011) | Foswiki:Tasks/10281: Correct handling of parallel edits. | |||||||||||||||
2.4.0 (28 Jan 2011) | Foswiki:Tasks/Item8263: Merged Kent Dozier's enhancement for display of select-type fields. Foswiki:Tasks/Item10282: Ensure a link to a missing action gives a meaningful error. Foswiki:Tasks/Item9636: correct parsing of manually-entered dates to default to international standards. Foswiki:Tasks/Item8564: numeric-sort in columns containing numeric data. Foswiki:Tasks/Item10190: support plain-text output from ACTIONSEARCH. Foswiki:Tasks/Item868: Use JQueryPlugin to streamline action editing (including refreshing the topic when an edited action is saved). Foswiki:Tasks/Item1946: The name search is now able to search for orphaned actions. Foswiki:Tasks/Item9687: relative dates in search expressions fixed. | |||||||||||||||
2.3.2 (04 Nov 2010) | Foswiki:Tasks/Item1187: Improved the fix for unwanted date changes when you create or edit an action. Now it should also work for servers west of Greenwich. | |||||||||||||||
2.3.1 (03 Nov 2010) | Foswiki:Tasks/Item9083: Ensure there's at least one newline at the end of the topic text after an action edit, and always one empty line between topic content and meta; otherwise attachment meta-data may get eaten | |||||||||||||||
2.3.0 (17 Oct 2010) | Foswiki:Tasks/Item9825: Update for Foswiki 1.1.0 compatibility. No other fixes in this revision | |||||||||||||||
2.2.3 (07 Feb 2010) | Foswiki:Tasks/Item8362: fix table separator in IE -- Foswiki:Main.AndrewJones | |||||||||||||||
2.2.2 (20 Jan 2010) | Foswiki:Tasks/Item8400: fix for editing in the plugin topic page | |||||||||||||||
2.2.1 (04 Jan 2010) | Foswiki:Tasks/Item8376: doc fix | |||||||||||||||
Foswiki:Tasks/Item2467: fix stylesheet. Foswiki:Tasks/Item2474: doc updates | ||||||||||||||||
2.2.0 (05 Nov 2009) | Foswiki:Tasks/Item8322: documentation improvements Foswiki:Tasks/Item8092: add CSS classes for different table orientations Foswiki:Tasks/1187: standardised entry fields as accepting GMT times only, fixed the test cases | |||||||||||||||
2.1.0 (15 May 2009) | Foswikitask:Item1627: Add horizontal grid lines to separate tasks as it was too difficult to see where one task ends and the next begins. Foswikitask:Item1187 If the server was east of Greenwich the dates in ActionTrackerPlugin were displayed as one day earlier and each time you edited an action the dates would decrement by one day. Foswikitask:Item1364 ActionTrackerPlugin handles actions without uid very badly. Foswikitask:Item1482 actionnotify referred to old name space. | |||||||||||||||
2.0.0 (29 Jan 2009) | Foswikitask:Item455: port to foswiki Foswikitask:Item5974: correct CSS for search results table Foswikitask:Item5938: load CSS for ACTIONSEARCH Foswikitask:Item5606: Foswikitask:Item5915: respect global settings for time format Foswikitask:Item4312: finished support for header, footer etc. Foswikitask:Item412: added reverse Foswikitask:Item5962: removed apparently spurious newline |
|||||||||||||||
1.0.0 (09 Jan 2002) | First version | |||||||||||||||
Dependencies: |
|
|||||||||||||||
Home page: | http://foswiki.org/Extensions/ActionTrackerPlugin |
Author | CrawfordCurrie |
Version | 2.4.12 |
Release | 2018-09-05 |
Description | Adds support for action tags in topics, and automatic notification of action statuses |
Repository | https://github.com/foswiki/ActionTrackerPlugin |
Copyright | Copyright © 2002-2003 Motorola. All Rights Reserved. Copyright © 2004-2013 Crawford Currie |
License | GPL (GNU General Public License) |
Home | http://foswiki.org/Extensions/ActionTrackerPlugin |
Support | http://foswiki.org/Support/ActionTrackerPlugin |