ApprovalPlugin

Defines a set of states for one or more topics, with each state requiring approval by one or more users

Introduction

This plugin is a rewrite of the TWiki:Plugins.WorkflowPlugin by TWiki:Main.ThomasWeigert, which supports much the same functionality except a couple of the macros (%WORKFLOWLASTTIME_State%, %WORKFLOWLASTVERSION_State%) and the use of TWikiForms in states. However, it does support concurrent reviewing and notifications on state change, which is not supported by the Workflow plugin. It was decided to spin this off seperatly as it is not backwords compatible.

Usage

This plugin only applies if the topic is under approval control. This means the preference setting APPROVALDEFINITION must be set. This should point to a topic that describes the approval flow (the approval definition topic).

The Approval Definition Topic

The approval definition topic must contain one state table and one transition table. The state table must be before the transition table. Both tables are described below.

The State Table

The state table must come before the transition table, and has three columns:

State Allow Edit Message
REJECTED   This document is waiting to be sent to the Stage Reviewers for review.
WAITINGFORREVIEW Main.UserTwo, Main.UserThree This document is waiting to be reviewed by the Stage Reviewers.
REVIEWED   This documented has been reviewed. It is now waiting to be sent to the Stage Approvers for approval.
WAITINGFORAPPROVAL Main.UserTwo, Main.UserThree This document is waiting to be approved by the Stage Approvers.
APPROVED Main.UserOne This document has been approved! No more actions can be carried out on this document.

Each row in the table defines a state where:

  • the State column specifies a name for the state,
  • the Allow Edit column specifies who is permitted to edit the topic when it is in the state (can be a %SEARCH%, %INCLUDE%, etc), and
  • the Message column defines a message which can be displayed on the document page when the document is in this state.

In our example we have defined five states. REJECTED is the default state, as it is first in the table.

Everyone is allowed to edit the topic in the REJECTED or the REVIEWED state. WAITINGFORREVIEW and WAITINGFORAPPROVAL are resricted to Main.UserTwo and Main.UserThree, and APPROVED is rescrited to just Main.UserOne.

Note: Admins will always be able to edit the topic, as with any topic in TWiki.

The Transition Table

Approval flow

The transition table consists of five columns, and an example is shown below:

State Action Next State Allowed Notify Sign Off's (%)
REJECTED Send For Review WAITINGFORREVIEW Main.UserOne yes  
WAITINGFORREVIEW Reviewed REVIEWED Main.UserTwo, Main.UserThree, Main.UserFour   50%
WAITINGFORREVIEW Rejected REJECTED Main.UserTwo, Main.UserThree, Main.UserFour   0%
REVIEWED Send For Approval WAITINGFORAPPROVAL Main.UserOne    
WAITINGFORAPPROVAL Approved APPROVED Main.UserTwo, Main.UserThree, Main.UserFour   50%
WAITINGFORAPPROVAL Rejected REJECTED Main.UserTwo, Main.UserThree, Main.UserFour   0%

Each row in this table defines a transition from one state to another state:

  • the State column contains the name of a state in the state table,
  • the Action column describes a possible action when the topic is in this state,
  • the Next State column defines the new state of the document after the specified action is performed,
  • the Allowed column specifies who is allowed to perform the corresponding action (can be a %SEARCH%, %INCLUDE%, etc),
  • the Notify column specifies whether email notifications should be sent out when this action is performed, and
  • the Sign Off's column defines the percentage of users in the allowed column that are required to perform this action.

The example defines the flow as pictured to the right. When the topic is in either the 'REJECTED' state or the 'REVIEWED' state, only Main.UserOne can push the topic through to the next state. If the topic is in the state 'WAITINGFORREVIEW', there will be two actions that can be carried out on the topic. The first is 'Reviewed', which pushes the topic into the 'REVIEWED' state. This has a sign off percentage of 50%, which in this case requires two of the users to review this state before the topic can go to the 'REVIEWED' state. The second action is 'Rejected', which only requires one person to push the topic back to the 'REJECTED' state. This is the same situation for 'WAITINGFORAPPROVAL'.

When the state of the topic is changed from 'REJECTED' to 'WAITINGFORREVIEW', an email notification will be sent to Main.UserTwo, Main.UserThree and Main.UserFour, letting them know that the state has changed and that they are next to approve the state. A copy of the email will also be sent to Main.UserOne, and to anyone listed in the ADDITIONALNOTIFY preference (see ApprovalPlugin#Preferences).

Note: Admins may disable all notifications by setting the $TWiki::cfg{Plugins}{ApprovalPlugin}{DisableNotify} setting to 1.

Preferences

The ADDITIONALNOTIFY preference can also be set in the definition topic. This can be a comma-seperated list of people who should be notified on each state change (if the 'Notify' column contains a 'yes'). For example:

  • Set ADDITIONALNOTIFY = Main.TheProjectManager

You may also set your own preferences in the definition topic, which can be referenced in the controlled topic by using %APPROVAL{"pref" name="..."}%. For example, in the definition topic set:

  • Set APPROVALNOTICE = This topic is under document control.

You can then use %APPROVAL{"pref" name="APPROVALNOTICE"}% in any topic under control.

The Controlled Topic

The controlled topic must have the APPROVALDEFINITION set to a approval definition topic (see ApprovalPlugin#The_Approval_Definition_Topic).

Settings

As well as the APPROVALDEFINITION setting, the topic may also contain the APPROVALHISTORYFORMAT setting. The defines the format of the history, which is updated after each state change. This may also be set in a WebPreferences topic, or in TWikiPreferences. The format will expand the variables $state, $wikiusername, $date, $quot and $n, with the same meaning as in FormattedSearch. The default setting is:

  • Set APPROVALHISTORYFORMAT = "$n$state -- $date"

Tags

The plugin will expand any %APPROVAL{"action"}% tags found in the controlled topic. The tag must have one of the actions listed below:

Parameters Comment
"statemessage" This will display the message for the current state, as defined in the state table.
"transition" Displays the transition form, which is used to change the state.
"history" Displays the approval history of the topic.
"pref" name="..." Displays the named preference set in the approval topic (see ApprovalPlugin#Preferences).
"reviewedby" Shows who has already reviewed the current state.

Examples

There is an example of an approval definition topic and a document under control in the Sandbox web. The links are below:

  • ApprovalDefinitionExample?
    • Example definition topic
  • ControlledTopicExample?
    • Example controlled topic

Note The examples will only work if the plugin is installed and enabled.

Notes

  • This plugin should work with groups defined in the transition table, but this is currently untested. If you want to use groups, please let us know your findings in TWiki:Plugins.ApprovalPluginDev.

  • The users in the transition table must have permission to change the controlled topic when they approve a state, otherwise TWiki will throw an access control exception. There is a message to the user if this is the case.

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.2 or later, you can install from the configure interface (Go to Plugins->Find More Extensions)
  • If you have any problems, then you can still install manually from the command-line:
    1. Download one of the .zip or .tgz archives
    2. Unpack the archive in the root directory of your TWiki installation.
    3. Run the installer script ( perl <module>_installer )
    4. Run configure and enable the module, if it is a plugin.
    5. 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.
    2. 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)
    3. Manually edit LocalSite.cfg to set any configuration variables.

Plugin Files

File: Description:
data/TWiki/ApprovalPlugin.txt Documentation
data/Sandbox/ControlledTopicExample.txt Example controlled topic
data/Sandbox/ApprovalDefinitionExample.txt Example definition topic
lib/TWiki/Plugins/ApprovalPlugin.pm Perl module
lib/TWiki/Plugins/ApprovalPlugin/Approval.pm Perl Module
lib/TWiki/Plugins/ApprovalPlugin/State.pm Perl Module
lib/TWiki/Plugins/ApprovalPlugin/Transition.pm Perl Module
lib/TWiki/Plugins/ApprovalPlugin/Config.spec Spec file for configure
templates/approvalnotify.tmpl Notification template
tools/convert.pl Coverts topics from TWiki:Plugins.WorkflowPlugin to the ApprovalPlugin (see comments in script)
pub/TWiki/ApprovalPlugin/ApprovalFlow.png Approval flow diagram

Plugin Info

Plugin Author(s): TWiki:Main.AndrewRJones
Copyright: © 2007-2009 TWiki:Main.AndrewRJones
© 2008-2010, TWiki:TWiki.TWikiContributor
License: GPL (Gnu General Public License)
Plugin Release: 1.0
Plugin Version: 19415 (2010-09-01)
Change History:  
2010-09-01: TWikibug:Item6530: Doc improvements; changed TWIKIWEB to SYSTEMWEB
01 Apr 2009 Released as 1.0
03 Feb 2009 Small doc changes; tested on TWiki
30 Oct 2008 Small improvements, better code
12 Sep 2008 Initial version
Dependencies: None
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/ApprovalPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/ApprovalPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/ApprovalPluginAppraisal

Related Topics: TWikiPreferences, TWikiPreferences, TWikiPlugins

Topic attachments
I Attachment Action Size Date Who Comment
pngpng ApprovalFlow.png manage 20.5 K 01 Sep 2010 - 06:15 TWikiAdminGroup Saved by install script
Topic revision: r2 - 01 Sep 2010 - 15:00:28 - TWikiAdminGroup

 
This site is powered by the TWiki collaboration platformCopyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback