%META:TOPICINFO{author="PaulHoesli" date="1160347731" format="1.1" reprev="1.1" version="1.1"}%
%META:TOPICPARENT{name="ContribPackage"}%

---+ Workflow Reports Contrib Package
%SHORTDESCRIPTION%

%TOC%

---++ Summary
This package is an add-on to the Workflow Plugin.
See [[TWiki:Plugins/WorkflowPlugin][WorkflowPlugin]]
for an overwiew of Workflows in TWiki.

---+++ <code>TWiki/Contrib/WorkflowReportsContrib</code> 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 <nop>WebWorkflowReport. This allows (for example) TWiki users to add
a "Update Report" button to topics.

The main interface is the =workflow<nop>Reports= method described below.

---+++ <code>bin/workflowreports</code> 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
   * [[TWiki:Plugins/WorkflowPlugin][WorkflowPlugin]]
   * WebStatistics module
   * [[TWiki:Plugins/MakeCtrlTopicsListAddOn][MakeCtrlTopicsListAddOn]]
   * [[TWiki:Plugins/MailerContrib][MailerContrib]]

I would like to express my gratitude to:
[[TWiki:Main/PeterThoeny][PeterThoeny]], [[TWiki:Main/ThomasWeigert][ThomasWeigert]],
[[TWiki:Main/DetlefMarxsen][DetlefMarxsen]], [[TWiki:Main/CrawfordCurrie][CrawfordCurrie]]

---++ Static Method workflow<nop>Reports
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 'Workflow<nop>Report' 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 'Debug<nop>WorkflowReport' 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. TWiki<nop>AdminGroup 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
      * $parent (parent topic)

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:
|*%MAKETEXT{"Topic"}%*|*%MAKETEXT{"Status"}%*|*%MAKETEXT{"Date"}%*|*%MAKETEXT{"History:"}%*|*%MAKETEXT{"Revision"}%*|*%MAKETEXT{"Last modified time"}%*|*%MAKETEXT{"Last editor"}%*|*%MAKETEXT{"Topic parent:"}%*|
|[[Issue1]]|ASSIGNED|08 Oct 2006 - 01:32|<verbatim>ASSIGNED -- 07 Oct 2006 - 23:46
CLOSED -- 08 Oct 2006 - 00:29</verbatim>|1.1|08 Oct 2006 - 01:32:50|%MAINWEB%.PaulHoesli|WebHome|
|[[Issue2]]|CONFIRMED|08 Oct 2006 - 01:24|<verbatim>REJECTED
CONFIRMED </verbatim>|1.1|08 Oct 2006 - 01:24:06|%MAINWEB%.PaulHoesli|WebHome|

---++ Missing Features
   * Add application programming interface
   * Add workflow name to report data items
   * Optionally create separate reports for different workflows (e.g. '%<nop>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 ==%<nop>&lt;plugin&gt;_&lt;setting&gt;%==, e.g. ==%<nop>WORKFLOWREPORTSCONTRIB_STUB%==

   * One line description:
      * Set SHORTDESCRIPTION = Supports report generation for workflow topics (see [[TWiki:Plugins/WorkflowPlugin][WorkflowPlugin]])

   * Name of the perl package
      * Set STUB = %$STUB%

   * Topic name and format of the workflow report:
      * Set WEBWORKFLOWREPORT = <nop>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.

<code>Usage: /usr/bin/perl -I &lt;bin&gt; &lt;bin&gt;workflowreports</code>
   * &lt;bin&gt; is the *absolute* path to the TWiki bin directory (usually =/home/&lt;user&gt;/public_html/&lt;twiki&gt;/bin=), so that the script can find the rest of TWiki.
   * add <code>>/dev/null 2>&1</code> 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:

%<nop>INCLUDE{%<nop>WEBWORKFLOWREPORT%}%;

---+++ Update the report from you topic manually using a link
Insert the following line in your topic:

<verbatim><a href="%SCRIPTURLPATH{workflowreports}%">Update workflow report</a></verbatim>

---+++ Update reports from you topic manually using a button
Insert the following lines in your topic:

<verbatim><form name="updateReport" action="%SCRIPTURLPATH{workflowreports}%/%WEB%/">
   <input type="hidden" name="webs" value="Main, Sandbox" />
   <input type="submit" class="twikiSubmit"  value="Update Reports" />
</form></verbatim>

---+++ 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 Build<nop>Contrib.
   * If you have TWiki 4.2 or later, you can install from the =configure= interface (Go to Plugins->Find More Extensions)
      * See the [[http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement][installation supplement]] on TWiki.org for more information.
   * If you have any problems, then you can still install manually from the command-line:
      1 Download one of the =.zip= or =.tgz= archives
      1 Unpack the archive in the root directory of your TWiki installation.
      1 Run the installer script ( =perl &lt;module&gt;_installer= )
      1 Run =configure= and enable the module, if it is a plugin.
      1 Repeat for any missing dependencies.
   * If you are *still* having problems, then instead of running the installer script:
      1 Make sure that the file permissions allow the webserver user to access all files.
      1 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)
      1 Manually edit !LocalSite.cfg to set any configuration variables.

%IF{"defined 'SYSTEMWEB'" else="<div class='twikiAlert'>%X% WARNING: SYSTEMWEB is not defined in this TWiki. Please add these definitions to your %MAINWEB%.TWikiPreferences, if they are not already there:<br><pre>   * <nop>Set SYSTEMWEB = %<nop>TWIKIWEB%<br>   * <nop>Set USERSWEB = %<nop>MAINWEB%</pre></div>"}%


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:
      * _enter samples here_

---++ Contrib Info

|  Author: | TWiki:Main/PaulHoesli |
|  Copyright &copy;: | 2006, Logismatic <nop>GmbH, All Rights Reserved |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Dependencies: | None |
|  Version: | 15571 (12 Dec 2008) |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  04 Nov 2006: | Untainted webs param, some refactoring |
|  22 Oct 2006: | Initial version |
|  Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |

__Related Topics:__ %TWIKIWEB%.TWikiPreferences

-- TWiki:Main.PaulHoesli - 02:27:08 12 December 2008

