Workflow Reports Contrib Package
Supports report generation for workflow topics (see
WorkflowPlugin)
Summary
This package is an add-on to the Workflow Plugin.
See
WorkflowPlugin
for an overwiew of Workflows in TWiki.
TWiki/Contrib/WorkflowReportsContrib
code library
The main part of the package is the
WorkflowReportsContrib.pm
module.
It provides the services for the script (and other applications of course) to
update a WebWorkflowReport. This allows (for example) TWiki users to add
a "Update Report" button to topics.
The main interface is the
workflowReports
method described below.
bin/workflowreports
script
The
workflowreports
script is an application of the workflowreports contrib package.
It is designed to be run from 'cron' (or an equivalent offline job scheduler)
to update the workflow report topics regularly.
Acknowledgments
This contrib package is inspired by the following contributions
I would like to express my gratitude to:
PeterThoeny,
ThomasWeigert,
DetlefMarxsen,
CrawfordCurrie
Static Method workflowReports
The workflow reports query and command handler.
This method supports invocation through a cgi query and via the
TWiki::UI::run
method.
It updates one workflow report topic for each 'user' web except webs that
do have the NOSEARCHALL preference set to 'on' OR for web(s) specified
in the query parameter 'webs'. It does not
create the topic, it only updates
the content of an existing workflow report topic.
During execution some messages are output as a sign of activity. Output may be
sent from cron to an e-mail recipient. No topic content is disclosed.
But web and topic names may be disclosed in case of failures.
Process description
Workflow report topics are updated for each web separately.
The report topic name can be defined through the web preference setting
WEBWORKFLOWREPORT. In case the setting is missing 'WorkflowReport' is used as a
default topic name.
The report topic must exist before executing this script. Create this topic
manually. If the report topic does not exist the web is skipped even if topics
under workflow control exist. This can be used to suspend reporting on a web temporarily.
For debug purposes a topic named 'DebugWorkflowReport' is used. Create this topic
manually before debugging. Use the query parameter 'debug' to enter debug mode.
Any previous content will be replaced by the report information. Meta information
is preserved. TWikiAdminGroup is the report topic author if the script is run from cron.
The topic changes are saved as minor changes without logging.
Report description
The command handler scans all the web topics and collects topic and
workflow information from topics under workflow control.
The following topic and workflow information is available:
- $topic (topic link)
- from meta data WORKFLOW
- $status (current workflow status)
- $lasttime (date - time of status assignment)
- from meta data WORKFLOWHISTORY
- $history (workflow history as verbatim history information)
- from meta data TOPICINFO
- $revision (current revision)
- $date (last modified date - time)
- $author (last editor)
- from meta data TOPICPARENT
The report format can be defined through the web preference setting
WEBWORKFLOWREPORTFORMAT. In case the setting is missing a default format
is used (a table row defined as: |$topic|$status|$lasttime|$history|)
The table header is using the following MAKETEXT items
- $topic : "Topic"
- $status : "Status"
- $lasttime : "Date"
- $history : "History:"
- $revision : "Revision"
- $date : "Last modified time"
- $author : "Last editor"
- $parent : "Topic parent:"
For each topic under workflow control (whenever meta data 'WORKFLOW' is available)
a table row is added. The row gets populated with the information matching
the defined format. Missing information is represented as a dash '-'.
The table is sorted alphabetically by topic name. Locale is used if enabled.
Sample Report:
Missing Features
- Add application programming interface
- Add workflow name to report data items
- Optionally create separate reports for different workflows (e.g. '%WorkflowName%Report')
- Select workflow(s) to report on (query param 'workflows')
Vote on or add your own missing features in
TWiki:Codev/WorkflowReportsContribDev.
Bugs
- Subwebs return undefined report rows
Settings
Settings are stored as preferences variables. To reference a setting
write
%<plugin>_<setting>%
, e.g.
%WORKFLOWREPORTSCONTRIB_STUB%
- One line description:
- Set SHORTDESCRIPTION = Supports report generation for workflow topics (see WorkflowPlugin)
- Topic name and format of the workflow report:
- Set WEBWORKFLOWREPORT = WebWorkflowReport
- Set WEBWORKFLOWREPORTFORMAT = |$topic|$status|$lasttime|$history|$revision|$author|$date|$parent|
Usage samples
Setting up a cron job
You may set up a
cron
(or equivalent) job to run
workflowreports
regularly.
Usage: /usr/bin/perl -I <bin> <bin>workflowreports
- <bin> is the absolute path to the TWiki bin directory (usually
/home/<user>/public_html/<twiki>/bin
), so that the script can find the rest of TWiki.
- add
>/dev/null 2>&1
at the end if activity messages are to be supressed
For example,
/usr/bin/perl -I /home/myuser/public_html/twiki/bin /home/myuser/public_html/twiki/bin/workflowreports >/dev/null 2>&1
Include the report into your topic
Insert the following line in your topic:
%INCLUDE{%WEBWORKFLOWREPORT%}%;
Update the report from you topic manually using a link
Insert the following line in your topic:
<a href="%SCRIPTURLPATH{workflowreports}%">Update workflow report</a>
Update reports from you topic manually using a button
Insert the following lines in your topic:
<form name="updateReport" action="%SCRIPTURLPATH{workflowreports}%/%WEB%/">
<input type="hidden" name="webs" value="Main, Sandbox" />
<input type="submit" class="twikiSubmit" value="Update Reports" />
</form>
License
This software is published under the terms of the GNU General Public License.
The software 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
Installation Instructions
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 where TWiki is running.
Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.
- If you have TWiki 4.1 or later, and Perl 5.8, you can install from the
configure
interface (Go to Plugins->Find More Extensions)
- If you have a permanent connection to the internet (and Perl 5.8), you are recommended to use the automatic installer script
- Just download the
WorkflowReportsContrib_installer
perl script and run it.
- If the $TWIKI_PACKAGES environment variable is set to point to a directory, the installer will try to get archives from there. Otherwise it will try to download from twiki.org or cpan.org, as appropriate.
- (Developers only: the script will look for twikiplugins/WorkflowReportsContrib/WorkflowReportsContrib.tgz before downloading from TWiki.org)
- If you don't have a permanent connection, you can still use the automatic installer, by downloading all required TWiki archives to a local directory.
- Point the environment variable
$TWIKI_PACKAGES
to this directory, and the installer script will look there first for required TWiki packages.
-
$TWIKI_PACKAGES
is actually a path; you can list several directories separated by :
- If you are behind a firewall that blocks access to CPAN, you can build a local CPAN mini-mirror, as described at http://twiki.org/cgi-bin/view/Codev/BuildingDakar#CPAN_local_minimirror
- The installer script will:
- Automatically resolve dependencies,
- Copy files into the right places in your local install even if you have renamed data directories,
- check in new versions of any installed files that have existing RCS histories files in your existing install.
- If you don't want to use the script, or have problems on your platform (e.g. you don't have Perl 5.8), then you can still install manually:
- Download and unpack one of the
.zip
or .tgz
archives to a temporary directory.
- Manually copy the contents across to the relevant places in your TWiki installation.
- Check in any installed files that have existing
,v
files in your existing install (take care not to lock the files when you check in)
- Manually edit LocalSite.cfg to set any configuration variables.
- Run
configure
and enable the module, if it is a plugin.
- Repeat from step 1 for any missing dependencies.
ZIP-Contents:
File: |
Description: |
bin/workflowreports |
Command script |
lib/TWiki/Contrib/WorkflowReportsContrib.pm |
Perl module |
data/TWiki/WorkflowReportsContrib.txt |
Documentation |
data/Sandbox/DebugWorkflowReport.txt |
Sample report |
data/Sandbox/Issue1.txt |
Sample topic |
data/Sandbox/Issue2.txt |
Sample topic |
data/Sandbox/WorkflowReport.txt |
Sample report |
- Test if the installation was successful:
Contrib Info
Related Topics: TWikiPreferences
--
TWiki:Main.PaulHoesli - 16:22:11 05 November 2006