ApprovalPlugin

<--
  Contributions to this plugin are appreciated. Please update the plugin page at
  http://twiki.org/cgi-bin/view/Plugins/ApprovalPlugin or provide feedback at
  http://twiki.org/cgi-bin/view/Plugins/ApprovalPluginDev.
  If you are a TWiki contributor please update the plugin in the SVN repository.

One line description, required for plugins repository catalog. 

 Set SHORTDESCRIPTION = 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:

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

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

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:

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)
  • See the 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
  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

Plugin Info

<-- versions below in reverse order -->

Related Topics: TWikiPreferences, TWikiPreferences, TWikiPlugins