Motivation
There are cases where you want to do some TWiki operation automatically.
This is about user level operations usually conducted manually through a web browser such as:
- rename a topic within the same web or to a different web
- create a new topic
- set TWikiForm field values
This is an idea for an add-on, not a core enhancement.
So it's not required to be discussed before implementation, I suppose.
Still, getting feedback at an early stage should be valuable. Hence I'm writing this.
Description and Documentation
The add-on allows TWiki users to register automated tasks.
This is somewhat related to
TasksFramework and
CronCentre (implementation in progress:
SchedulerContrib), but quite different in scope.
This add-on can do the same thing as
RunTopicsAddOn.
So in a sense, this is a generalized and liberalized (in a sense that not requiring command line access) version of
RunTopicsAddOn.
Use case 1: archiving topics
You have a bulletin board web, on which each article is a topic, and a list of articles is shown by
%SEARCH{...}%
.
It's a high traffic bulletin board, so it accumulates a lot of articles and gets sluggish.
To keep its responsiveness at a certain level, you want to archive old articles to a subweb.
Specifically, articles having no update for the past 180 days will be archived.
And you want to do it automatically rather than manually.
Use case 2: creating topics
You have a web of your project team, in which there are weekly report topics. A team weekly report
%INCLUDE{...}%
members' weekly reports so that all members' reports can be seen at a glance.
Every week, a new team weekly report page needs to be created based on the member list.
You want to automate it.
Use case 3: refresh cached topics
You are using
VarCachePlugin and you have topics taking long to be rendered.
So you want to have those pages "view"ed periodically.
RunTopicsAddOn can do it, but this add-on can it too.
bin/automation
This add-on introduces a script named
automation
.
It's somewhat like the
statistics
script in the sense that
automation
and
statistics
can be used both interactively and in a batch job. When they are invoked from a web browser, they do their jobs for the current web, and when they are invoked from a command line, they traverses all webs and do their jobs for each web.
The
automation
script is intended to be invoked daily from cron or other similar mechanism.
It walks through all webs including subwebs and see if a WebAutomation topic exists. If it does,
automation
executes automation tasks described on WebAutomation.
If
bin/automation
is invoked interactively from a web browser, it refers to WebAutomation of the current web and execute tasks in the topic.
WebAutomation
A WebAutomation topic has one or more tables written in TWiki markup.
On the bulletin board web mentioned above, it would look like:
Operation |
Topic |
Parameter |
rename |
Article2014x05x08x00 |
newweb=BulletinBoard/Archive |
rename |
Article2014x05x08x01 |
newweb=BulletinBoard/Archive |
On the team web mentioned above, it would look like:
On a web having heavy-to-render topics, it would look like:
You may think that if tables need to be edited manually, it's not automation.
That's true.
So those tables tend to be dynamic.
The first one would be the result of:
%SEARCH{"d2n(info.date) < d2n('%DATETIME{"$year-$mo-$day" incdays="-180"}%')"
type="query"
topic="Article*"
nonoise="on"
separator="$n"
header="| *Operation* | *Topic* | *Parameter* |"
format="| rename | $topic | newweb=%WEB%/Archive |"
}%
The second one would be the result of:
| *Operation* | *Topic* | *Parameter* |
%IF{"'%GMTIME{$wday}%' = 'Fri'" then="| save | Report%GMTIME{$yearx$mox$day}% | templatetopic=ReportTemplate |"}%
The
automation
script expands TWiki variables on WebAutomation before picking up tasks from tables.
As you see, the third and following columns are for parameters -- one column for one parameter.
As of this writing, only operations intended to be implemented are "rename", "save", and "view".
There parameters are same the corresponding scripts.
Not to step on others' toes
Before executing an operation, the topic name and the parameters are sanitized to prevent you from bothering others.
Specifically:
- The topic must not contain slash (/) or dot (.). If it does, the first character of the topic name to the last occurrence of slash or dot are removed
- The templatetopic and newtopic parameter values are the same as the topic value
- The newweb parameter value must share the top level web as the current web or Trash. UserSubwebs are exceptions. They are technically second level webs, but they are treated as if they were top level. For example, you cannot move a topic from Main/JoeSchmoe to Main/JaneDoe even though they share the top level web "Main".
Access control implication
When executed in batch, the
automation
script runs with the administrator privilege.
There is no other practical ways.
- If it runs as the guest user, it cannot do anything interesting -- new topic creation, topic renaming, both needs a real user
- If it runs as the user who last edited, an automated task can stop working either by
- WebAutomation is edited by somebody else
- The permission of the last edit user changes
- The last edit user is removed from the TWiki's user registration
This leads to that WebAutomation needs to be readable and writable only by privileged users.
For this, an enhancement to
TWiki::Access::checkAccessPermission()
such as
this is required.
Examples
Impact
Implementation
--
Contributors: Hideyo Imazu - 2014-05-08
Discussion
Scheduled tasks that are configurable in TWiki topics is definitely a feature that helps strengthen TWiki as an app platform.
We had discussions and alpha code in the past, see
TasksFramework,
CronCentre,
SchedulerContrib.
I'll provide more feedback...
--
Peter Thoeny - 2014-05-09
Thank you for the feedback, Peter. I clarified the initial part of the proposal. So please take a look.
--
Hideyo Imazu - 2014-05-10
I see a useful case to archive reports in regular intervals, such as a weekly status report that takes a snapshot of a dynamic report that pulls data from multiple status report topics.
--
Peter Thoeny - 2014-05-15
I've realized that this add-on can provide the feature provided by
RunTopicsAddOn. So I added it.
--
Hideyo Imazu - 2014-07-04
Also related is the relatively new
ExecutePlugin.
--
Peter Thoeny - 2016-01-28