Foswiki 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 wiki.

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.

Upgrade note If you are upgrading from a version before 10 Nov 2008 please note that the format of the WORKFLOWHISTORYFORMAT preference has changed slightly, in that:
  1. enclosing double quotes are no longer removed from the value. This changes has been to bring this preference definition into line with other preference definitions.
  2. $n is interpreted as \n, not <br>, in line with the standard format tokens. If you want a <br> in the format string, then enter it as <br> or $percntBR$percnt.


A topic is under document control if the preference variable WORKFLOW is set in the topic page. WORKFLOW must be set to the wiki 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 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.

ALERT! 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*                        |
| APPROVED      | revise   | UNDERREVISION | QualityGroup                     |
| UNDERREVISION | complete | WAITINGFORQM  | QualityGroup                     |
| WAITINGFORQM  | approve  | WAITINGFORCTO | QualityManager                   |
| WAITINGFORQM  | reject   | UNDERREVISION | QualityManager,QualityGroup      |
| WAITINGFORCTO | approve  | APPROVED      | TechnicalDirector                |
| 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,
  • an optional Form column defines a form that is attached to the topic in this state.
  • an optional Notify column specifies who should be notified when this transition fires.

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

If a Notify column is given, that column can contain a comma-separated list of notification targets to be informed when the transition is fired. You can specify values in any combination of the following formats:
Format Example Notes
Email addresses  
User wiki names WikiGuest  
Wiki group names AdminGroup  
Email templates template(Web.MyTopic) Must be wrapped in parentheses and proceeded by the word template, all lowercase, no spaces.

When a transition is fired, any email addresses provided in the Notify column (or resolved from wiki/group names) will be notified, with a message formatted according to the default email template provided with the plugin. You can override this template by setting the WORKFLOWDEFAULTEMAILTEMPLATE preference in your workflow description topic. Set that to a topic that contains a valid email notification template (see example below), and all email addresses provided will receive messages formatted according to that template:

Subject: %WIKITOOLNAME%.%WEB%.%TOPIC% - transitioned to %TARGET_STATE%
MIME-Version: 1.0
Content-Type: text/plain
%WIKINAME% has moved the topic %WEB%.%TOPIC% to the %TARGET_STATE% state.  You can view the document here:

Email notification templates should be topics formatted like the example above, with the headers each on their own line, followed by a single colon, then their values, with the message body begining below the " Content-Type: text/plain " line. Also note the %EMAILTO% macro on the To: line; any email addresses pulled from the Notify column for a given transition will be expanded here. If you override the default email template using the WORKFLOWDEFAULTEMAILTEMPLATE preference, it must use the %EMAILTO% to pull in recipients, otherwise you'll need to provide your own macros, and any email addresses provided in the Notify column will be ignored. See the content-sensitive workflows section for more on how WorkflowPlugin expands macros.

For more sophisticated email notification, you can also write one or more custom email templates for each transition. Email notification templates are completely independent of both the default email template and other email adresses or usernames provided in the Notify column for their transition. Custom notification templates must provide valid headers that define their recipients, and they do not have access to the EMAILTO macro, so other email addresses provided will not be sent through custom templates (but they can still go out through the default email template).

For example, the Notify column in the transition below will email using the default template, and execute both the EmailOne and EmailTwo templates, sending the results to whatever email addresses are defined on their respective To, Cc, or Bcc lines:
| *State* | *Action* | *Next State* | *Allowed* |  *Notify*                                               |
| PENDING | approve  |   APPROVED   |           |, template(EmailOne), template(EmailTwo) |

Note: it's a good idea to avoid editing email notfication templates with a WYSIWYG editor, as they are somewhat fragile.

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.

WORKFLOW* -- macros associated with WorkflowPlugin

Controlling topics in the workflow
%WORKATTACHTOPIC% Expands to a link that lets you attach to the topic (if the user is not able to modify the topic, either in the workflow sense or according to the standard access controls, the link will be struck out).
%WORKFLOWEDITTOPIC% Expands to a link that lets you edit the topic (if the user is not able to modify the topic, either in the workflow sense or according to the standard access controls, the link will be struck out).
%WORKFLOWFORK{...}% Expands to a button that will create a copy of the current topic (see below for more details)
%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. You can change the format of the button using a CSS class (see WORKFLOWTRANSITIONCSSCLASS below)
Querying the workflow
%WORKFLOWHISTORY% Expands to the history of state transitions the topic has undergone. The format of the history is dictated by the WORKFLOWHISTORYFORMAT (described below).
%WORKFLOWLASTREV_State% Expands to the version number when the document was last in the state State.
%WORKFLOWLASTTIME_State% Expands to the timestamp when the document was last in the State last state. For example, %WORKFLOWLASTTIME_APPROVED% would be replaced by the timestamp when the document was last in the APPROVED state.
%WORKFLOWLASTVERSION_State% Expands to a link to the version of the document when it was last in the state State.
%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.
%WORKFLOWSTATEMESSAGE% Expands to the corresponding message in the state table.

(All the macros accept an optional default parameter, which is the name of a topic, a web and a rev parameter. If these are omitted, they will default to the current topic, latest revision)

Furthermore, the plugin replaces any macro starting with WORKFLOW that is defined in the workflow description file.

If the topic is not controlled, then any references to WORKFLOW macros are simply removed (you can use this behaviour to place these tags in the header or footer in your skin templates. They appear only if the currently displayed document is controlled. Otherwise, they are just removed and do not disturb the layout).

In addition there are two macros you can define in your topics (or WebPreferences)

WORKFLOWHISTORYFORMAT tells the plugin how to format each new line added to the WORKFLOWHISTORY. The format is used as a template for each new entry, and should include all the formatting necessary to make the history look nice when it is viewed.

In this example the history is formatted as a table:
  • Set WORKFLOWHISTORYFORMAT = $n| $state | $wikiusername | $date |
The leading $n expands to a newline character that separates each line of the history. You could also format the history as a bullet list:
  • Set WORKFLOWHISTORYFORMAT = $n * $state -- $wikiusername, $date
The standard format tokens are supported, as well as the following special tokens:
Token Expands to
$wikiusername Who triggered the transition
$state The target state of the transition
$date Date of the transition
$rev Version at the transition

The appearance of the button to change state can be configured by providing a CSS class. For example,
The default is foswikiChangeFormButton foswikiSubmit.

The WORKFLOWFORK macro is used to generate a button that will create a copy of a workflow topic. It accepts the following parameters:
Parameter Meaning Default
"TopicName" (Optional) name of the topic to fork current topic
web (Optional) name of the web containing the topic to fork current web
newnames="NameOne,NameTwo" Comma-separated list of name(s) of the new topic(s) to create, You can use a web specifier on the topic names. required, no default.
label="Fork" Label to use in the button "Fork"
lockdown="on" Set this if you want the forked topic to be set as uneditable after the fork off
This macro is used when you have a topic that has to be split to follow different routes through a workflow - for example, when a requirement is refined to create two new requirements that must follow their own lifecycles; or perhaps a problem report is found to affect two different components of a system, and the resolutions have to be separately tracked. Both the copied topic and the new topic will have workflow history entries added.

For example, %WORKFLOWFORK{"OriginalTopic" label="Divide and conquer" newnames="ForkPathOne,ForkPathTwo" lockdown="on"}% will create two copies of OriginalTopic, named ForkPathOne and ForkPathTwo and set the OriginalTopic as uneditable (using ALLOWTOPICCHANGE).

The histories in both the fork copies and the original topic record what happened.

The user has to be able to modify the topic (both in the workflow sense and according to the standard access controls) in order to fork.

ALERT! due to a bug in versions of the plugin prior to Oct 2009, the default "TopicName" parameter was interpreted as the name of the new topic to fork to. This has been corrected, but the macro will revert to the old meaning if you omit the newnames parameter.

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

Similarly, you can use %WORKFLOWATTACHTOPIC% in your skin templates to cross out the Attach link.

Content-sensitive workflows

Advanced Flows can be made sensitive to the content of the controlled topics. The 'Allow Edit' column in the state table, and the 'Next State' and 'Allowed' columns in the transition table, support the use of macros which are expanded when the topic is viewed. For example, you can use the META macro to pick up values for these fields from the form attached to the viewed topic:

State table
| *State*             | *Allow Edit*                         | *Message* |
| WAITINGFORAPPROVAL  | %META{"formfield" name="MayModify"}% | This document is waiting for approval |
Transition Table
| *State*            | *Action* | *Next State*                             | *Allowed*                        |
| WAITINGFORAPPROVAL | approve  | %META{"formfield" name="ApprovedState"}% | %META{"formfield" name="MayApprove"}% |

You can also define other macros 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.


A common requirement is to report on the status of topics that are in different states in the workflow. You can use the query search to search for topics in a specific state. For example, to search for all topics in state "APPROVED":
%SEARCH{"'APPROVED'" type="query"}%

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.

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 for more help.

Note: The script 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 to

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 wiki in such way that users have to log-in even if they just display a topic.


Author(s): Thomas Hartkens, Foswiki:Main.ThomasWeigert, Foswiki:Main.CrawfordCurrie
Version: 14978 (2012-06-13)
Release: 1.12.8
Change History:  
1.12.8 (13 Jun 2012) Foswiki:Main.PaulHarvey: Foswikitask:Item11941: fix mis-spelt %WORKFLOWEDITTOPIC% in docs
1.12.7 (08 Feb 2012) Foswiki:Main.GilmarSantosJr: Foswikitask:Item11513: fix WORKFLOWHISTORY date field
1.12.6 (31 Jan 2012) Foswiki:Main.GilmarSantosJr: Foswikitask:Item11489: fix SEARCH on WORKFLOWHISTORY
1.12.5 (20 Jan 2012) Foswiki:Main.CrawfordCurrie: Foswikitask:Item11459: fix bug when used with comment plugin.
1.12.4 (11 Jan 2012) Foswiki:Main.MichaelDaum: Foswikitask:Item11430, Foswikitask:Item11419: fixed error in save handler that prevented any edit change to a topic under workflow control
1.12.3 (10 Jan 2012) Foswiki:Main.MichaelDaum: Foswikitask:Item11405: fixed performance issue editing topics that are not under workflow control
1.12.2 (12 Dec 2011) Foswiki:Main.GilmarSantosJr: Foswikitask:Item10309, Foswikitask:Item9088, Foswikitask:Item11338: make WORKFLOWLAST* accept topic and rev parameters and report the correct version number. Foswikitask:Item11343: fix WORKFLOWTRANSITIONCSSCLASS default value. Foswikitask:Item8002: store WORKFLOWHISTORY as 'list' META instead of preformatted string.
1.12.1 (01 Mar 2011) Foswikitask:Item10356: Correct parsing of trailing spaces in state and transition tables
1.12 (23 Feb 2011) Foswiki:Tasks.Item10008: Implement support for custom email templates on state transition notifications.
1.11.1 (25 Aug 2010) Foswiki:Tasks.Item8908: fix obscure error that caused apparently inexplicable crashes; hint: never use $_ as an iterator control variable in your perl code.
1.11 (15 Jun 2010) Foswiki:Tasks.Item9142: make the access controls checks more thorough
1.10 (01 Jun 2010) Foswiki:Tasks.Item9086: ensure t= is set on all edit links; also validate the workflow name.
1.9 (31 May 2010) Crawford Currie: Foswiki:Tasks.Item9072: add WORKFLOWLASTREV_State to show topic revision number Foswiki:Tasks.Item9081: force new topic revision on each state transition to avoid history loss
1.8.1 (27 May 2010) Crawford Currie: Foswiki:Tasks.Item9048: Minor doc update
1.8 (26 May 2010) Crawford Currie: Foswiki:Tasks.Item2425: allow cancellation of state transitions that involve an edit step. Foswiki:Tasks.Item8321: allow non-wikiword topic names Foswiki:Tasks.Item8320: added $rev to WORKFLOWHISTORYFORMAT Foswiki:Tasks.Item8297: a topic parameter to the view url could bork the transition button Foswiki:Tasks.Item9048: use the Allow Edit control to check and limit general saves, such as those done from CommentPlugin
1.7.1 (03 Feb 2010) Foswiki:Tasks.Item8462: Andrew Jones made some minor doc fixes
1.7 (04 Nov 2009) Foswiki:Tasks.Item2092: Link fork topics mentioned in history Foswiki:Tasks.Item8268: added topic control to WORKFLOWTRANSITION Foswiki:Tasks.Item8306: support fork to multiple topics, changed WORKFLOWFORK parameters for compatibility with other macros
1.6 (02 Sep 2009) Foswiki:Tasks.Item1828: Dean Spicer added support for macro expansion of the next state. Foswiki:Tasks.Item1828: Crawford Currie documented his work, and added support for topic forking. Foswiki:Tasks.Item1828: fixed the defect example. Foswiki:Tasks.Item8172: Dean Spicer added support for cross-topic state and history queries
1.5.2 (29 Apr 2009) Foswiki:Tasks.Item8147: fix version recording
1.5.1 (23 Apr 2009) Foswiki:Tasks.Item1503: fix collection of notify addresses
1.5 (09 Apr 2009) Foswiki:Tasks.Item8107: block transition if topic is being edited by another user
1.4 (21 Mar 2009) Dean Spicer/Crawford Currie: Foswiki:Tasks.Item8080: finish porting to Foswiki and support %WORKFLOWATTACHTOPIC
1.3 (03 Mar 2009) Crawford Currie: Foswiki:Tasks.Item8069: deny attach on a controlled topic Foswiki:Tasks.Item8070: expand macros in Allow and AllowEdit fields
1.2 (11 Dec 2008) Crawford Currie: Foswiki:Tasks.Item8029: support notification of a list of people on state changes
1.1 (15 Nov 2008) Crawford Currie: Foswiki:Tasks.Item6114: Fixed format of history Foswiki:Tasks.Item6119: added InProcessForm and increased defensiveness in a couple of places
1.0 (10 Nov 2008) Crawford Currie: Heavily refactored to OO style to ease maintenance. Ensure form is saved when state changes. Support use of '. Split off VarWORKFLOW documentation. Removed 'back door' call that was causing issues, Work supported by
23 Apr 2008 Crawford Currie: Removed last of the core calls, fixed user management. Work supported by
28 Jan 2008: Kenneth Lavrsen: Fixed his typo in code. Renamed the to as most installs do 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
05 Aug 2006: Crawford Currie: Converted from ApprovalPlugin to WorkflowPlugin.
16 Feb 2005: Thomas Hartkens: Initial version of ApprovalPlugin
05 Feb 2004: Thomas Weigert Initial version of WorkFlowAddOn

Topic revision: r1 - 02 Nov 2013, UnknownUser
This site is powered by FoswikiCopyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Hades Wiki? Send feedback