Menu
▾
▴
[TWiki-Dev] [SVN] PeterThoeny r19428 - twiki/trunk/WorkflowPlugin/data/TWiki
|
From: <de...@de...> - 2010-09-04 09:22:48
|
Author: PeterThoeny Date: 2010-09-04 04:22:41 -0500 (Sat, 04 Sep 2010) New Revision: 19428 Trac url: http://develop.twiki.org/trac/changeset/19428 Modified: twiki/trunk/WorkflowPlugin/data/TWiki/VarWORKFLOW.txt twiki/trunk/WorkflowPlugin/data/TWiki/WorkflowPlugin.txt Log: Item6577: Major plugin update - doc improvements Modified: twiki/trunk/WorkflowPlugin/data/TWiki/VarWORKFLOW.txt =================================================================== --- twiki/trunk/WorkflowPlugin/data/TWiki/VarWORKFLOW.txt 2010-09-04 08:29:10 UTC (rev 19427) +++ twiki/trunk/WorkflowPlugin/data/TWiki/VarWORKFLOW.txt 2010-09-04 09:22:41 UTC (rev 19428) @@ -1,5 +1,7 @@ -#VarWEB ----+++ WORKFLOW* -- macros associated with WorkflowPlugin +%META:TOPICINFO{author="TWikiContributor" date="1283590767" format="1.1" version="$Rev$"}% +%META:TOPICPARENT{name="TWikiVariables"}% +#VarWORKFLOW +---+++ WORKFLOW* -- variables associated with !WorkflowPlugin | *Controlling topics in the workflow* || | =%<nop>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 <strike>struck out</strike>).| | =%<nop>WORKEDITTOPIC%= | 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 <strike>struck out</strike>).| Modified: twiki/trunk/WorkflowPlugin/data/TWiki/WorkflowPlugin.txt =================================================================== --- twiki/trunk/WorkflowPlugin/data/TWiki/WorkflowPlugin.txt 2010-09-04 08:29:10 UTC (rev 19427) +++ twiki/trunk/WorkflowPlugin/data/TWiki/WorkflowPlugin.txt 2010-09-04 09:22:41 UTC (rev 19428) @@ -1,17 +1,32 @@ ----+ %TOPIC% +%META:TOPICINFO{author="TWikiContributor" date="1283590767" format="1.1" version="$Rev$"}% +---+!! <nop>%TOPIC% <!-- + Contributions to this plugin are appreciated. Please update the plugin page at + http://twiki.org/cgi-bin/view/Plugins/WorkflowPlugin or provide feedback at + http://twiki.org/cgi-bin/view/Plugins/WorkflowPluginDev. + If you are a TWiki contributor please update the plugin in the SVN repository. + * Set SHORTDESCRIPTION = Associate a "state" with a topic and then control the work flow that the topic progresses through as content is added. --> +%SHORTDESCRIPTION% +<sticky> <div style="float:right"> %ATTACHURL%/Flow.gif </div> -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, +<div style="background-color:#eeeeee; margin:0 20px 20px 0; padding: 0 10px 0 10px"> +%TOC{title="Page contents"}% +</div> +</sticky> + +---++ Introduction + +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 wiki. +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. @@ -24,7 +39,7 @@ ---++ Usage 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_). +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. @@ -34,7 +49,7 @@ This is easiest illustrated using an example (available as Sandbox.DocumentApprovalWorkflow if the plugin is installed). -The state table is a table with three columns: +The state table is a TWiki table with three columns: <verbatim> | *State* | *Allow Edit* | *Message* | @@ -45,18 +60,16 @@ </verbatim> 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 *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. -%X% The state table must be defined *before* the transition table! +%X%i __Note:__ The state table must be defined *before* the transition table! The transition table consists of four columns, as in this example: <verbatim> @@ -70,22 +83,21 @@ </verbatim> 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 + * 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 Approved<nop>Form 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 people who are to be notified when the transition is fired. You can specify individual user wiki names, group names, and even individual email addresses. @@ -101,14 +113,9 @@ Similarly, you can use =%<nop>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 =[[VarMETA][META]]= -macro to pick up values for these fields from the form attached to the -viewed topic: +*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 variables which are expanded when the topic is viewed. For example, you can use the =[[VarMETA][META]]= variable to pick up values for these fields from the form attached to the viewed topic: + *State table* <verbatim> | *State* | *Allow Edit* | *Message* | @@ -120,13 +127,16 @@ | WAITINGFORAPPROVAL | approve | %META{"formfield" name="ApprovedState"}% | %META{"formfield" name="MayApprove"}% | </verbatim> -You can also define other macros starting with =WORKFLOW= in the workflow +You can also define other 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. + + * Set WORKFLOWNOTICE = This topic is under document control. + will define =WORKFLOWNOTICE= in any topic that uses the workflow. ---++ Reporting + 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": <verbatim> %SEARCH{"META:WORKFLOW.name='APPROVED'" type="query"}% @@ -134,57 +144,64 @@ ---++ History and Acknowledgements -This plugin was motivated by [[TWiki:Main.ThomasWeigert][Thomas Weigert]]'s [[TWiki:Extensions.WorkFlowAddOn][WorkFlowAddOn]] and its first version (then called !ApprovalPlugin) was written by Thomas Hartkens, albeit it was focused on document approval and control. [[TWiki:Main.ThomasWeigert][Thomas Weigert]] then merged the functionality of the [[TWiki:Extensions.WorkFlowAddOn][WorkFlowAddOn]] into this plugin. +This plugin was motivated by [[TWiki:Main.ThomasWeigert][Thomas Weigert]]'s [[TWiki:Plugins.WorkFlowAddOn][WorkFlowAddOn]] and its first version (then called !ApprovalPlugin) was written by Thomas Hartkens, albeit it was focused on document approval and control. [[TWiki:Main.ThomasWeigert][Thomas Weigert]] then merged the functionality of the [[TWiki:Plugins.WorkFlowAddOn][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. +%$INSTALL_INSTRUCTIONS% -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://twiki.org/Support/ManuallyInstallingExtensions for more help. - - __Note:__ The script =[[%ATTACHURL%/convert.pl.txt][convert.pl.txt]]= 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 wiki in such way that users have to log-in *even if they just display a topic*. +__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 TWiki in such way that users have to log-in *even if they just display a topic*. ----++ Info +---++ Plugin Info -| Author(s): | Thomas Hartkens, TWiki:Main.ThomasWeigert, TWiki:Main.CrawfordCurrie | -| Version: | 8761 (2010-08-25) | -| Release: | 25 Aug 2010 | +| Authors: | TWiki:Main.ThomasHartkens, TWiki:Main.ThomasWeigert, TWiki:Main.CrawfordCurrie | +| Copyright: | © 2005 TWiki:Main.ThomasHartkens %BR% © 2005 TWiki:Main.ThomasWeigert %BR% © 2008-2010 TWiki:Main.CrawfordCurrie %BR% © 2005-2010, TWiki:TWiki.TWikiContributor | +| License: | [[http://www.gnu.org/licenses/gpl.html][GPL (Gnu General Public License)]] | +| Plugin Version: | %$VERSION% | | Change History: | <!-- versions below in reverse order --> | -| 25 Aug 2010 | TWiki:Tasks.Item8908: fix obscure error that caused apparently inexplicable crashes; hint: _never_ use $_ as in iterator control variable in your perl code. | -| 15 Jun 2010 | TWiki:Tasks.Item9142: make the access controls checks more thorough | -| 1 Jun 2010 | TWiki:Tasks.Item9086: ensure t= is set on all edit links; also validate the workflow name. | -| 31 May 2010: | Crawford Currie: TWiki:Tasks.Item9072: add WORKFLOWLASTREV_State to show topic revision number TWiki:Tasks.Item9081: force new topic revision on each state transition to avoid history loss | -| 26 May 2010: | Crawford Currie: TWiki:Tasks.Item2425: allow cancellation of state transitions that involve an edit step. TWiki:Tasks.Item8321: allow non-wikiword topic names TWiki:Tasks.Item8320: added $rev to WORKFLOWHISTORYFORMAT TWiki:Tasks.Item8297: a topic parameter to the view url could bork the transition button TWiki:Tasks.Item9048: use the =Allow Edit= control to check and limit general saves, such as those done from CommentPlugin | -| 03 Feb 2010: | TWiki:Tasks.Item8462: Andrew Jones made some minor doc fixes | -| 19 Oct 2009: | TWiki:Tasks.Item2092: Link fork topics mentioned in history TWiki:Tasks.Item8268: added topic control to WORKFLOWTRANSITION TWiki:Tasks.Item8306: support fork to multiple topics, changed WORKFLOWFORK parameters for compatibility with other macros | -| 2 Sep 2009: | TWiki:Tasks.Item1828: Dean Spicer added support for macro expansion of the next state. TWiki:Tasks.Item1828: Crawford Currie documented his work, and added support for topic forking. TWiki:Tasks.Item1828: fixed the defect example. | -| 3 Jun 2009: | TWiki:Tasks.Item8172: Dean Spicer added support for cross-topic state and history queries | -| 29 Apr 2009: | TWiki:Tasks.Item8147: fix version recording | -| 23 Apr 2009: | TWiki:Tasks.Item1503: fix collection of notify addresses | -| 9 Apr 2009: | TWiki:Tasks.Item8107: block transition if topic is being edited by another user | -| 21 Mar 2009: | Dean Spicer/Crawford Currie: TWiki:Tasks.Item8080: finish porting to TWiki and support %WORKFLOWATTACHTOPIC | -| 20 Mar 2009 | Crawford Currie: TWiki:Tasks.Item8069: deny attach on a controlled topic TWiki:Tasks.Item8070: expand macros in Allow and AllowEdit fields | -| 11 Dec 2008 | Crawford Currie: TWiki:Tasks.Item8029: support notification of a list of people on state changes | -| 15 Nov 2008 | Crawford Currie: TWiki:Tasks.Item6114: Fixed format of history TWiki:Tasks.Item6119: added !InProcessForm and increased defensiveness in a couple of places | +| 2010-09-04: | TWikibug:Item6577: Major import of plugin improvements; doc enhancements | +| 25 Aug 2010 | F8908: fix obscure error that caused apparently inexplicable crashes; hint: _never_ use $_ as in iterator control variable in your perl code. | +| 15 Jun 2010 | F9142: make the access controls checks more thorough | +| 1 Jun 2010 | F9086: ensure t= is set on all edit links; also validate the workflow name. | +| 31 May 2010: | Crawford Currie: F9072: add WORKFLOWLASTREV_State to show topic revision number F9081: force new topic revision on each state transition to avoid history loss | +| 26 May 2010: | Crawford Currie: F2425: allow cancellation of state transitions that involve an edit step. F8321: allow non-wikiword topic names F8320: added $rev to WORKFLOWHISTORYFORMAT F8297: a topic parameter to the view url could bork the transition button F9048: use the =Allow Edit= control to check and limit general saves, such as those done from CommentPlugin | +| 03 Feb 2010: | F8462: Andrew Jones made some minor doc fixes | +| 19 Oct 2009: | F2092: Link fork topics mentioned in history F8268: added topic control to WORKFLOWTRANSITION F8306: support fork to multiple topics, changed WORKFLOWFORK parameters for compatibility with other variables | +| 2 Sep 2009: | F1828: Dean Spicer added support for variable expansion of the next state. F1828: Crawford Currie documented his work, and added support for topic forking. F1828: fixed the defect example. | +| 3 Jun 2009: | F8172: Dean Spicer added support for cross-topic state and history queries | +| 29 Apr 2009: | F8147: fix version recording | +| 23 Apr 2009: | F1503: fix collection of notify addresses | +| 9 Apr 2009: | F8107: block transition if topic is being edited by another user | +| 21 Mar 2009: | Dean Spicer/Crawford Currie: F8080: finish porting to TWiki and support %WORKFLOWATTACHTOPIC | +| 20 Mar 2009 | Crawford Currie: F8069: deny attach on a controlled topic F8070: expand variables in Allow and AllowEdit fields | +| 11 Dec 2008 | Crawford Currie: F8029: support notification of a list of people on state changes | +| 15 Nov 2008 | Crawford Currie: F6114: Fixed format of history F6119: added !InProcessForm and increased defensiveness in a couple of places | | 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 http://micralyne.com | | 23 Apr 2008 | Crawford Currie: 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 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 | +| 10 Dec 2006: | Add =%<nop>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: | Crawford Currie: Converted from !ApprovalPlugin to %TOPIC%. | +| 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. | +| 05 Aug 2006: | Crawford Currie: Converted from !ApprovalPlugin to %TOPIC%. | | 16 Feb 2005: | Thomas Hartkens: Initial version of !ApprovalPlugin | | 05 Feb 2004: | Thomas Weigert Initial version of !WorkFlowAddOn | -| Home: | http://twiki.org/Extensions/%TOPIC% | -| Support: | http://twiki.org/Support/%TOPIC% | +| TWiki Dependency: | $TWiki::Plugins::VERSION 1.1 | +| Dependencies: | None | +| TWiki:Plugins/Benchmark: | %TWIKIWEB%.GoodStyle nn%, %TWIKIWEB%.FormattedSearch nn%, %TOPIC% nn% | +| Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% | +| Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev | +| Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal | -<!-- Do _not_ attempt to edit this topic; it is auto-generated. --> - -%META:FILEATTACHMENT{name="convert.pl.txt" attr="h" comment="" date="1159057355" path="convert.pl.txt" size="355" user="ProjectContributor" version="1"}% -%META:FILEATTACHMENT{name="Flow.draw" attr="h" comment="" date="1159056685" path="Flow.draw" size="5504" user="ProjectContributor" version=""}% -%META:FILEATTACHMENT{name="Flow.gif" attr="h" comment="" date="1159056685" path="Flow.gif" size="3252" user="ProjectContributor" version=""}% +%META:FILEATTACHMENT{name="convert.pl.txt" attr="h" comment="" date="1159057355" path="convert.pl.txt" size="355" user="TWikiContributor" version="1"}% +%META:FILEATTACHMENT{name="Flow.draw" attr="h" comment="" date="1159056685" path="Flow.draw" size="5504" user="TWikiContributor" version=""}% +%META:FILEATTACHMENT{name="Flow.gif" attr="h" comment="" date="1159056685" path="Flow.gif" size="3252" user="TWikiContributor" version=""}% |