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 Foswiki:Extensions.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 DataForms 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 Foswiki.

The Transition Table

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 $Foswiki::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 SitePreferences. 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 Foswiki:Support.ApprovalPlugin.

• The users in the transition table must have permission to change the controlled topic when they approve a state, otherwise Foswiki 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.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Plugin Info

Plugin Author(s):	Foswiki:Main.AndrewJones
Copyright:	© 2007 - 2009 Foswiki:Main.AndrewJones
License:	GPL (Gnu General Public License)
Plugin Release:	1.1
Plugin Version:	11605 (2011-05-03)
Change History:
03 May 2011	1.1: Foswikitask:Item2010 - configure settings should be under Extensions, not Plugins; Foswikitask:Item9298 - use Func API correctly; Foswikitask:Item8933 - Don't crash is definition topic does not exist
01 Apr 2009	Foswikitask:Item8082 - Ported to Foswiki and released as 1.0
03 Feb 2009	Foswikitask:Item8056 - Small doc changes; tested on Foswiki/Compat
30 Oct 2008	Small improvements, better code
12 Sep 2008	Initial version
Dependencies:	None
Plugin Home:	http://foswiki.org/Extensions/ApprovalPlugin
Support:	http://foswiki.org/Support/ApprovalPlugin

Related Topics: DefaultPreferences, SitePreferences, Plugins