WorkflowPlugin

TWiki benefits from the fact that every user can modify a topic instantly without restrictions. However sometimes you want to be able to associate a "state" with a topic and then control the work flow that the topic progresses through as content is added. For example,

• When writing documents compliant with ISO 9000 (e.g. a quality manual), it is essential that documents are approved by the management before they may be applied by the employees.
• In a defect tracking data base, defects typically transition through a series of states from submission to resolution, with different actions available depending on the state of the defect.
• In a journal database, papers must be reviewed and approved by several experts in the field before being allowed to be published.

This plugin lets you associate a complex work flow with topics in your TWiki.

A workflow can be associated with a single topic, or with an entire web. If a topic is under workflow control, you can define a set of states for this topic (e.g. "under revision", "waiting for approval", "approved") and transitions (e.g. "revise", "approve") between these states. Furthermore, you can define which users/groups are permitted to perform specific transistions. In this way, you can control, for example, who is allowed to "approve" a topic and who is not.

Usage

A topic is under document control if the preference variable WORKFLOW is set in the topic page. WORKFLOW must be set to the TWiki name of a topic that describes your specific workflow (the workflow description topic).

Note: you can hide the setting in a normal view using HTML comments, or better, you can put these settings into the local topic settings, accessible from the "more" screen.

Settings in the workflow description topic

The workflow description topic must contain one state table and one transition table. The state table describes the possible states a document may be in (nodes in the flow diagram above), and the transition table describes how documents move between states (arcs in the flow diagram).

This is easiest illustrated using an example (available as DocumentApprovalWorkflow if the plugin is installed).

The state table is a TWiki table with three columns:

| *State*       | *Allow Edit* | *Message* |
| UNDERREVISION | QualityGroup | This document is being revised. |
| APPROVED      | nobody       | This document has been approved for release. |
| WAITINGFORQM  | nobody       | This document is waiting for approval by the Quality Manager. |
| WAITINGFORCTO | nobody       | This document is waiting for approval by the CTO.|

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, and
• the Message column defines a message which can be displayed on the document page when the document is in this state.

In the example we have defined four states. Members of the QualityGroup are permitted modify documents can make changes to the document in UNDERREVISION state. In all other states, nobody is allowed to edit the controlled document.

The first state in the table is the initial/default state.

NOTE: The state table must be defined before the transition table!

The transition table consists of four columns, as in this example:

| *State*        | *Action* | *Next State*  | *Allowed*                        | *Form*        |
| APPROVED       | revise   | UNDERREVISION | QualityGroup                     | ApprovedForm  |
| UNDERREVISION  | complete | WAITINGFORQM  | QualityGroup                     | InProcessForm |
| WAITINGFORQM   | approve  | WAITINGFORCTO | QualityManager                   |               |
| WAITINGFORQM   | reject   | UNDERREVISION | QualityManager,QualityGroup      |               |
| WAITINGFORCTO  | approve  | APPROVED      | TechnicalDirector                | ApprovedForm  |
| WAITINGFORCTO  | reject   | UNDERREVISION | TechnicalDirector,QualityManager |               |

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

• the State column contains the name of a state from 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 has been performed,
• the Allowed column specifies who is allowed to perform the corresponding action,
• the optional Form column defines a form that is attached to the topic in this state.

In our example, anyone is allowed to revise the document when it is in UNDERREVISION state. After finishing the revision, the document can be transitioned to the WAITINGFORQM state by any member of the QualityGroup. It must then be approved by the QualityManager, and after that by the TechnicalDirector. Even though they can't edit the document themselves (see state table above), they can reject the revision and put the document back into the UNDERREVISION state. The TechnicalDirector can transition the document to APPROVED state where it rests until a member of the QualityGroup puts it under revision again.

If a form name is given in the last column, this form will be attached to the topic, and the topic will put in edit mode to allow information to be provided in the form when that state transition happens. In the example above, a form of type ApprovedForm will be attached to the topic when the CTO transitions the topic into APPROVED state.

• if there is already a form of a different type attached to the topic, then any fields that have the same name in the new form will be preserved.
• If no form is given, the existing form (if any) is left in place.

A typical usage of the form would be to collect additional information as the topic walks through the work flow, or to make information in the form unchangeable (by setting it to a label field) once a given state is reached.

You can also define other TWiki variables starting with WORKFLOW in the workflow description topic. These will be expanded to their defined values in any topic that uses the workflow. For example:

• Set WORKFLOWNOTICE = This topic is under document control.

will define WORKFLOWNOTICE in any topic that uses the workflow.

Settings in your controlled document/topic

As described above the topic needs to contain a definition for the variable WORKFLOW for it to be controlled under the approval workflow. This is best set as a document-specific preference setting in the More topic actions screen.

The plugin defines a number of TWikiVariables that can be used in the topic under flow control:

Variable	Description
%WORKFLOWTRANSITION%	Expands to either (a) a pull-down menu if the user can perform more than one transition, (b) a button if the current user can only perform one transition, or (c) empty space if the current user is not allowed to perform any action.
%WORKFLOWSTATEMESSAGE%	Expands to the corresponding message in the state table.
%WORKFLOWLASTTIME_State%	Expands to the timestamp when the document was last in the State last state. For example, in our example above %WORKFLOWLASTTIME_APPROVED% would be replaced by the timestamp when the document was last in the APPROVED state.
%WORKFLOWLASTVERSION_State%	Expands to topic version when the document was last in the state State.
%WORKFLOWHISTORY%	Expands to the history of state transitions the topic has undergone. The format of the history is dictated by the WORKFLOWHISTORYFORMAT (described below).
%WORKFLOWSTATE%	Expands to the current state of the document. It can also be given a topic parameter (default), in which case the state of that topic is returned.

Furthermore, the plugin replaces any variable starting with WORKFLOW that is defined in the workflow description file. If the topic is not controlled, then any references to WORKFLOW variables are simply removed (you can use this behaviour to place these tags in the header or footer in your TWikiTemplates. They appear only if the currently displayed document is controlled. Otherwise, they are just removed and do not disturb the layout)

If you replace %EDITTOPIC% with %WORKFLOWEDITTOPIC% in your TWikiTemplates, then the Edit link is crossed out when the user is not allowed to edit the page in a state.

Bugs

• You can attach a file to a contolled topic even if the state of the topic does not allow the user to edit it. In general, the plugin should prevent any changes to the topic in such case.
• If a transition attaches a form, the initial values are not taken from the form definition, due to the TWiki form initialization algorithm.

History and Acknowledgements

This plugin was motivated by Thomas Weigert 's WorkFlowAddOn and its first version (then called ApprovalPlugin) was written by Thomas Hartkens, albeit it was focused on document approval and control. Thomas Weigert then merged the functionality of the WorkFlowAddOn into this plugin. Crawford Currie enhanced the documentation and installation procedure.

Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, i.e. %WORKFLOWPLUGIN_SHORTDESCRIPTION%

• History format. In this example, the first line tells the plugin to format the history as a bullet list, the second just writes a newline separated list. The variables $state, $wikiusername, $date, $quot, and $n (or $n()) can be used in the format statement, with the same meaning as in FormattedSearch.
  • #Set WORKFLOWHISTORYFORMAT = " * $state -- $wikiusername, $date"
  • Set WORKFLOWHISTORYFORMAT = "$n$state, $wikiusername, $date"

• Appearance of the button to change state can be configured by providing a sytle element, either defining a class for the control, or a local style:
  • Set STYLE = class="twikiChangeFormButton twikiSubmit"
  • #Set STYLE = style="padding:0; margin:0; color:#888; text-decoration:underline; background-color:transparent; border:none;"

Plugin 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.

Note: The script convert.pl.txt? supplied will convert topics written for the ApprovalPlugin to the WorkflowPlugin. The script takes a topic at the standard input and outputs the converted topic on standard output. Rename the file from convert.pl.txt to convert.pl.

Look at the examples in the Sandbox web.

Note: For strict access control, the plugin should know who is looking at the controlled document/topic at all times. To enable this, you may want to set up the TWiki in such way that users have to log-in even if they just display a topic.

Plugin Info

Plugin Author:	TWiki:Main/ThomasHartkens, Dakar port and changes from 24 Jul 2006 by TWiki:Main/ThomasWeigert
Plugin Version:	28 Jan 2008
Change History:
23 Apr 2008:	Crawford Currie: TWikibug:Item5369: removed last of the core calls, fixed user management. Work supported by http://www.productbox.co.uk/
28 Jan 2008:	Kenneth Lavrsen: Fixed his typo in code. Renamed the convert.pl to convert.pl.txt as most TWiki's including twiki.org does not allow .pl as extension and this creates problems when you want to update attachments
27 Jan 2008:	Markus Ueberall: Fixed for compatibility with TWiki 4.2.0
10 Dec 2006:	Add %WORKFLOWSTATE%.
25 Sep 2006:	Restored ability to put workflow related tags into templates. Support the visual customization of the generated controls.
11463	Crawford Currie rewrote the doc and corrected the install procedure
10 Aug 2006:	Added conversion script.
05 Aug 2006:	Converted from ApprovalPlugin to WorkflowPlugin.
26 Jul 2006:	Minor bug fix. Additional examples provided.
25 Jul 2006:	Added state-based forms and history from TWiki:Plugins/WorkFlowAddOn. Changed time stamp format to be more wiki like.
24 Jul 2006:	Ported to Dakar. Fixed problem in referencing previous versions. Fixed error messages. Fixed Documentation errors.
16 Feb 2005:	Initial version of ApprovalPlugin
05 Feb 2004:	Initial version of WorkFlowAddOn
TWiki Dependency:	$TWiki::Plugins::VERSION 1.1
Dependencies:	None
TWiki:Plugins/Benchmark:	GoodStyle nn%, FormattedSearch nn%, WorkflowPlugin nn%
Plugin Home:	http://TWiki.org/cgi-bin/view/Plugins/WorkflowPlugin
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/WorkflowPluginDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/WorkflowPluginAppraisal

Related Topics: TWikiPreferences, TWikiPlugins

-- TWiki:Main/ThomasWeigert - 25 Sep 2006