r2 - 2006-09-07 - 15:52:37 - TWikiGuestYou are here: NTP >  TWiki Web > WorkflowPlugin
NTP users are strongly urged to take immediate action to ensure that their NTP daemons are not susceptible to being used in distributed denial-of-service (DDoS) attacks. Please also take this opportunity to defeat denial-of-service attacks by implementing Ingress and Egress filtering through BCP38.

ntp-4.2.8p15 was released on 23 June 2020. It addresses 1 medium-severity security issue in ntpd, and provides 13 non-security bugfixes over 4.2.8p13.

Please see the NTP Security Notice for vulnerability and mitigation details.

Are you using Autokey in production? If so, please contact Harlan - he's got some questions for you.


TWiki benefits from the fact that every user can modify a topic instantly without restrictions. However, sometimes it is desirable that one can control the content of the TWiki, or the work flow that a topic progresses through as content is added to this topic.

For example, if TWiki is used in a Quality System as a document server compliant with ISO 9000 (e.g. for the quality manual), it is essential that these documents are approved by the management before they can be applied by the employees. Similarly, when TWiki is used for a defect tracking data base, defects typically transition through a work flow from submission to resolution, with different actions available depending on the state of the defect.

This plugin enables you to associate a complex work flow with a single topic or with an entire web, in order to control the content in your TWiki. If a topic is under work flow 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 users or user groups which 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.

This plugin was motivated by ThomasWeigert 's TWiki:Plugins.WorkFlowAddOn plugin and was written by ThomasHartkens , albeit it was focused on document approval and control. ThomasWeigert then merged the functionality of the WorkFlowAddOn into this plugin.

In order to print a list which topics are under document control, have a look at the add-on MakeCtrlTopicsListAddOn .


A topic is under document control if the preference variable

appears on its page while the topic Sandbox.DocumentApprovalWorkflow describes your specific workflow.

Settings in the workflow description topic

A topic must contain one state and one transition table (see, for example, DocumentApprovalWorkflow ). The state table could look like this, for example:

State Allow Edit Message
UNDERREVISION Main.User1, QualityGroup This document is under revision.
APPROVED nobody  
WAITINGFORQM nobody This document is waiting for approval by the Quality Manager.
WAITINGFORCEO nobody This document is waiting for approval by the CEO.

Each row in this table defines a state whereby

  • the State column contains an unique identifier for the state,
  • the Allow Edit column specifies the user(s) which are permitted to edit the topic 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 this example, we have defined four states and only the users Main.User1 and Main.QualityGroup are permitted to make changes to the document in the state UNDERREVISION. In all other states the document can not be edited by any user.

Note, that the first state in this table defines always the initial/default state.

The transition table consists of 4 columns. For example:

State Action Next State Allowed Form
APPROVED revise UNDERREVISION QualityGroup ApprovedForm
UNDERREVISION send to Quality Manager for approval WAITINGFORQM QualityGroup InProcessForm
WAITINGFORQM approve and send to CEO for approval WAITINGFORCEO QualityManager  
WAITINGFORQM reject and keep revising UNDERREVISION QualityManager  
WAITINGFORCEO approve APPROVED TechnicalDirector  
WAITINGFORCEO reject and keep revising UNDERREVISION TechnicalDirector  

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

  • the State column contains the identifier of the current state of the document (of course, this must correspond to a state in the state table!),
  • the Action column defines a possible action for this current state,
  • the Next State column defines the resulting state after the specified action is performed, and
  • the Allowed column specifies the user(s) which are allowed to perform the corresponding action.
  • the optional Form column defines a form that is attached to the topic in this state.

Thus, in our example the Quality Group is allowed to revise the document. After finishing the revision, first, the document is approved by the Quality Manager and after that by the Technical Director. Even though they can't edit the document by themself (see state table above), they can reject the revision and put the document back into the UNDERREVISION state.

If a form is given in the last column, this form will be attached to the topic, and the topic is put in edit mode to allow information to be provided in the form. If no form is given, the existing form is left in place, if any. A typical usage would be to collect additional information, as the topic walks through the work flow, or to make information in the form not changeable (by setting it to a label field), once a given state is reached. This column can safely be omitted. An example of a workflow that also controls the form information can be found in DefectWorkflow , where a simple defect tracking system is implemented.

NOTE: The state table needs to be defined before the transition table!

Besides these both tables you can define any kind of variable starting with %WORKFLOW ...% in this file, e.g.

  • Set WORKFLOWNOTICE = This topic is under document control. Last approval on %WORKFLOWLASTTIME_APPROVED%
  • Set WORKFLOWBUTTON = You are permitted to change the status of this document: %WORKFLOWTRANSITION%

which can be used then in the controlled document.

Settings in your controlled document/topic

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

Now you can place the tag %WORKFLOWTRANSITION% in your document which will be expanded 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.

Additionally, you can place the tag %WORKFLOWSTATEMESSAGE% in your document which will be replaced by the corresponding message in the state table.

The approval keeps track when the document was in a specific state last time. The tag

  • %WORKFLOWLASTTIME_State% will be replaced by the timestamp when the document was in the state State last time and
  • %WORKFLOWLASTVERSION_State% will be replaced by the version when the document was in the state State last time.

For instance, in our example above the tag =%WORKFLOWLASTTIME_APPROVED% is replaced by the timestamp when the document was in the state APPROVED last time.

The tag %WORKFLOWHISTORY% is replaced by the history of state transitions the topic has undergone. The format of the history is dictated by the preference value below:

  • #Set WORKFLOWHISTORYFORMAT = " * $state -- $wikiusername, $date"
  • Set WORKFLOWHISTORYFORMAT = "$n$state, $wikiusername, $date"

The first line tells 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.

Furthermore, the plugin replaces any variable starting with %WORKFLOW...% defined in the workflow file. Finally, it removes all other tags in the document which start with %WORKFLOW...%. (You can use this behaviour to place these tags in the header or footer. They appear only if the currently displayed document is controlled! Otherwise, these tags are just removed and do not disturb the layout)

Remark: If you replace the tag %EDITTOPIC% with %WORKFLOWEDITTOPIC% in your templates, then the Edit link is crossed out when the user is not allowed to edit the page in a state (Note, that the topic is still write protected even if you don't replace the tag).

The topics DefectOne and DefectTwo give examples of how to use these tags to create workflow controlled topics (the latter also shows the use of custom views to change the appearance of the topic).


Currently, I am aware of the following shortcoming:

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

Plugin Settings

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

  • One line description, is shown in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Allows to associate work flows with topics

  • Debug plugin: (See output in data/debug.txt)
    • Set DEBUG = 0

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running.

Note: For strict access control, the plugin should know who is looking at the controlled document/topic at all times. To enable, you need to set up the TWiki in such way that users have to log-in even if they just display a topic (e.g., by leveraging an appropriate .htaccess file).

  • Download the ZIP file from the Plugin web (see below)
  • Unzip WorkflowPlugin.zip in your twiki installation directory. Content:
    File: Description:
    data/TWiki/WorkflowPlugin.txt Plugin topic
    lib/TWiki/Plugins/WorkflowPlugin.pm Plugin Perl module
    data/Sandbox/ControlledDocument.txt Example document
    data/Sandbox/DocumentApprovalWorkflow.txt Example workflow
    data/Sandbox/DefectWorkflow.txt Example workflow
    data/Sandbox/DefectOne.txt Example document
    data/Sandbox/DefectTwo.txt Example document, using custom views
    data/Sandbox/DefectViewTemplate.txt Custom view definition
    data/Sandbox/InitialForm.txt Forms for defect workflow
    data/Sandbox/SubmittedForm.txt Forms for defect workflow
    data/Sandbox/CompletedForm.txt Forms for defect workflow
    lib/TWiki/Plugins/WorkflowPlugin/convert.pl Conversion script
  • Look at examples in Sandbox.

Note: This plugin works on TWiki 4 and later only. For a version under Cairo, please download this version.

Note: The script convert.pl 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.

Plugin Info

Plugin Author: TWiki:Main/ThomasHartkens, Dakar port and changes from 24 Jul 2006 by TWiki:Main/ThomasWeigert
Plugin Version: 10 Aug 2006
Change History:  
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
CPAN Dependencies: none
Other Dependencies: none
Perl Version: 5.005
TWiki:Plugins/Benchmark: GoodStyle nn%, FormattedSearch nn%, WorkflowPlugin nn%
Plugin Home: https://TWiki.org/cgi-bin/view/Plugins/WorkflowPlugin
Feedback: https://TWiki.org/cgi-bin/view/Plugins/WorkflowPluginDev
Appraisal: https://TWiki.org/cgi-bin/view/Plugins/WorkflowPluginAppraisal

Related Topics: TWikiPreferences, TWikiPlugins

-- TWiki:Main/ThomasWeigert - 10 Aug 2006

Edit | WYSIWYG | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r2 < r1 | More topic actions
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 NTP? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.WorkflowPlugin