Item14441: reworked example, improved tests, fixed promotion of acces…

…s controls

data/Sandbox/WorkflowPluginExample/ApproveForm.txt

@@ -0,0 +1,5 @@
+Example form used by the DocumentApprovalWorkflow. Topics get this form when they are moved to PLEASEAPPROVE state
+
+| *Name* | *Type* | *Size* | *Values* | *Tooltip messages* | *Attributes* | 
+| Summary of changes | text | 60 | | | | 
+

data/Sandbox/WorkflowPluginExample/ControlledDocument.txt

@@ -0,0 +1,25 @@
+This is an example document that demonstrates some of the features of
+the %SYSTEMWEB%.WorkflowPlugin. The document is controlled by the %WORKFLOW%
+workflow.
+
+The table below is part of the example content, and is generated by expanding
+some of the macros described in %SYSTEMWEB%.VarWORKFLOW
+
+| *Macro* | *Description* | *Expands to*|
+| =WORKFLOWSTATE= | Current state of the document | %WORKFLOWSTATE% |
+| =WORKFLOWSTATEMESSAGE= | State message | %WORKFLOWSTATEMESSAGE% |
+| =WORKFLOWTRANSITIONS= | Transitions available to you | %WORKFLOWTRANSITION% |
+| =WORKFLOWLAST= | Last time in APPROVED state | %WORKFLOWLAST{"APPROVED" format="$time by $author"}% |
+| =WORKFLOWLASTVERSION= | Link to version when it was last in APPROVED state | %WORKFLOWLASTVERSION{"APPROVED"}% |
+| =WORKFLOWHISTORY= | Workflow history | %WORKFLOWHISTORY% |
+| =WORKFLOWFORK= | Fork the document to a new topic 'ControlledDocumentFork' | %WORKFLOWFORK{"ControlledDocumentFork"}% |
+
+Other =WORKFLOW*= preferences defined in %WORKFLOW% are defined
+here too:
+| =WORKFLOWNOTICE= | %WORKFLOWNOTICE% |
+| =WORKFLOWSET= | %WORKFLOWSET% |
+| =WORKFLOWDEBUG= | %WORKFLOWDEBUG% |
+
+%META:PREFERENCE{name="WORKFLOW" value="DocumentApprovalWorkflow"}%
+%META:PREFERENCE{name="WORKFLOWDEBUG" value="1"}%
+%META:WORKFLOWHISTORY{name="1" state="APPROVED" date="123456789" author="WikiGuest"}%

data/Sandbox/WorkflowPluginExample/DocumentApprovalWorkflow.txt

@@ -0,0 +1,50 @@
+This is an example workflow description used with the %SYSTEMWEB%.WorkflowPlugin.
+
+See ControlledDocument for a document controlled by this workflow.
+
+Any topic using this workflow can use settings from this topic that start
+with =WORKFLOW= - for example,
+   * Set WORKFLOWNOTICE = This document is under workflow control
+
+The workflow is a very simple one, with only three states and four
+transitions:
+
+<verbatim>
+UNDERREVISION ------>-------- PLEASEAPPROVE --->--- APPROVED
+       ^      needs approval        |       approve    |
+       |                            |                  |
+       +------------<---------------'                  |
+       |         reject                                |
+       |                                               |
+       `-------------------------<---------------------'
+                               revise
+</verbatim>
+Anyone can make the =needs approval= and =revise= transitions, but
+only the (fictional) !QualityGroup can make the 'approve' and 'reject'
+transitions. Further,
+   * the document can only be edited in UNDERREVISION state. In all other states, it is locked for editing
+   * when a topic is moved to PLEASEAPPROVE state, it gets the ApproveForm
+   * when a topic is moved to UNDERREVISION state, it gets the RevisionForm
+   * the user who last moved a document to UNDERREVISION is not allowed to move it to APPROVED.
+   * WikiGuest is denied most actions unti lthe document is in approved state
+
+---++ States
+The first table describes the states a topic can be in.
+
+| *State*       | *Allow VIEW*   | *Allow CHANGE* | *Message*            |
+| UNDERREVISION | not(WikiGuest) | not(WikiGuest) | Under revision       |
+| PLEASEAPPROVE | not(WikiGuest) | nobody         | Waiting for approval |
+| APPROVED      |                | nobody         | Approved for release |
+
+--++ Transitions
+The second table describes the transitions available from each state.
+
+| *State*        | *Action*       | *Next State*  | *Allowed*      | *Form*       |
+| UNDERREVISION  | needs approval | PLEASEAPPROVE | not(WikiGuest) | ApproveForm  |
+| APPROVED       | revise         | UNDERREVISION | not(LASTUSER_UNDERREVISION) | RevisionForm |
+| PLEASEAPPROVE  | approve        | APPROVED      | QualityGroup   |              |
+| PLEASEAPPROVE  | reject         | UNDERREVISION | QualityGroup   | RevisionForm |
+
+%META:PREFERENCE{name="WORKFLOWDEBUG" value="1"}%
+%META:PREFERENCE{name="WORKFLOWSET" value="Example setting"}%
+

data/Sandbox/WorkflowPluginExample/RevisionForm.txt

@@ -0,0 +1,5 @@
+Example form used by the DocumentApprovalWorkflow. Topics get this form when they are moved to UNDERREVISION state
+
+| *Name* | *Type* | *Size* | *Values* | *Tooltip messages* | *Attributes* | 
+| Reason for revision | text | | | | | 
+

data/Sandbox/WorkflowPluginExample/WebHome.txt

@@ -0,0 +1,10 @@
+This web contains a working example of the %SYSTEMWEB%.WorkflowPlugin
+
+   * DocumentApprovalWorkflow contains the workflow
+   * ControlledDocument is an example document
+
+<form action="%SCRIPTURLPATH{edit}%/%WEB%/ControlledDocumentAUTOINC000">
+You can create a new document (based on ControlledDocument) that you can use with the workflow here:
+<input type="hidden" name="templatetopic" value="ControlledDocument"/>
+<input type="submit" value="Create new controlled document" />
+</form>

data/Sandbox/WorkflowPluginExample/WebLeftBarExample.txt

@@ -0,0 +1,3 @@
+%WIKIUSERNAME%
+| *Controlled Documents* |
+%SEARCH{"ControlledDocument" scope="topic" nonoise="on" format="| [[$topic]] |"}%

data/Sandbox/WorkflowPluginExample/WebPreferences.txt

@@ -0,0 +1,25 @@
+---+!! <nop>%WEB% Web Preferences
+
+%TOC%
+
+---++ Appearance
+
+   * Set WEBBGCOLOR = #EBABEFAC
+      * <sticky>web-specific background color, <span style='background-color: %WEBBGCOLOR%'> current color </span></sticky>
+
+   * Set SITEMAPLIST = on
+      * set to =off= to hide this web from the [[%SYSTEMWEB%.SiteMap][SiteMap]]
+
+   * Set WEBSUMMARY = Working example for the WorkflowPlugin
+      * description what this web is used for
+
+   * Set NOSEARCHALL = on
+      * if set to =on=, this web will be exclude web from a global search
+
+   * Set WEBFORMS = RevisionForm, ApproveForm
+      * Comma separated list of forms that can be attached to topics in this web. See [[%SYSTEMWEB%.DataForms][DataForms]] for more information.
+
+---
+%INCLUDE{"%SYSTEMWEB%.WebPreferencesHelp"}%
+
+

data/System/WorkflowPlugin.txt

@@ -1,4 +1,4 @@
-%META:TOPICINFO{author="ProjectContributor" date="1407507830" format="1.1" version="1"}%
+%META:TOPICINFO{author="ProjectContributor" date="1501261498" format="1.1" version="1"}%
 %META:TOPICPARENT{name="ReferenceManual"}%
 ---+ %TOPIC%
 <!--
@@ -48,7 +48,8 @@ transition table describes how documents move between states (arcs in
 the flow diagram).
 
 This is easiest illustrated using an example (available as
-Sandbox.DocumentApprovalWorkflow if the plugin is installed).
+Sandbox.DocumentApprovalWorkflow / Sandbox.ControlledDocument if the
+plugin is installed).
 
 Each row of the state table defines a state that a topic can be in:
 
@@ -121,6 +122,10 @@ 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.  See #TransitionNotification below for more information.
 
+Any [[%SYSTEMWEB%.PreferenceSettings][preference settings]] in the workflow
+description topic that start with =WORKFLOW= are automatically available
+when topics that use that workflow are viewed.
+
 ---++ Transition Notification
 If a *Notify* column is given in the transition table, then that column
 should contain a comma-separated list of notification targets to be emailed
@@ -200,7 +205,7 @@ attached to the viewed topic:
 | WAITINGFORAPPROVAL | approve  | %META{"formfield" name="ApprovedState"}% | %META{"formfield" name="MayApprove"}% |
 </verbatim>
 
-If you want to exclude the user who changed a specific state last, even though the user is generally allowed to, you can add =not(LASTUSER_{State})= to the =Allowed= column of the transition table and the last user for the specified state will be excluded.
+See #AccessControl for more information.
 
 You can also define other macros starting with =WORKFLOW= in the workflow
 description topic. These will be expanded to their defined values in any
@@ -217,8 +222,8 @@ A common requirement is to report on the status of topics that are in different
 ---++ Access Control
 The plugin uses extended Foswiki permissions to manage access to topics.
 
-In the state table, you can have any number of "Allow" columns, for example
-"Allow CHANGE" or "Allow VIEW". These columns dictate the Foswiki permissions
+In the state table, you can have any number of 'Allow' columns, for example
+'Allow CHANGE' or 'Allow VIEW'. These columns dictate the Foswiki permissions
 that are applied when a topic is transitioned to that state by the plugin. For
 example, if the state table contains:
 <verbatim>
@@ -231,18 +236,13 @@ will automatically be removed, and the permissions:
    * Set ALLOWTOPICVIEW = *
 will be added to the topic.
 
-Empty 'Allow' columns in the state table are taken as meaning no restriction.
-The special entry =nobody= can be used to restrict access for everyone (except
-admins).
-
-The ability to change the state of a topic is controlled by the *Allowed*
-column of the state table. If you leave the *Allowed* column empty,
-then anyone will be able to perform that transition.
-
-The *Allow* columns in the state table and the *Allowed* column in the
-state table support the use of Foswiki macros. The special entry
-=nobody= can be used to restrict access for everyone (except
-admins).
+Similarly the 'Allowed' column in the transition table controls who is allowed to perform that transition.
+Normally entries in 'Allow' columns are user (or group) names, such as %WIKINAME%. However:
+   * Empty 'Allow*' columns are taken as meaning no restriction.
+   * The special entry =nobody= can be used to restrict access for everyone (except admins).
+   * You can _exclude_ a specific user (or group) from access using =not(%WIKINAME%)=.
+   * You can explicitly exclude the user who last transitioned the topic to a specific state using =not(LASTUSER_{State})=.
+   * You can use Foswiki macros. These will be expanded in the context of the controlled topic.
 
 %X% For historical reasons, *Allow Edit* is mapped to *Allow CHANGE*.
 
@@ -359,6 +359,6 @@ __Note:__ For strict access control, the plugin should know who is looking at th
 %META:FIELD{name="Repository" attributes="" title="Repository" value="https://github.com/foswiki/WorkFlowPlugin"}%
 %META:FIELD{name="Support" attributes="" title="Support" value="http://foswiki.org/Support/WorkflowPlugin"}%
 %META:FIELD{name="Home" attributes="" title="Home" value="http://foswiki.org/Extensions/WorkflowPlugin"}%
-%META:FILEATTACHMENT{name="convert.pl.txt" attr="h" comment="" date="1407507830" path="convert.pl.txt" size="355" user="ProjectContributor" version="1"}%
-%META:FILEATTACHMENT{name="Flow.draw" attr="h" comment="" date="1407507830" path="Flow.draw" size="5504" user="ProjectContributor" version="1"}%
-%META:FILEATTACHMENT{name="Flow.gif" attr="h" comment="" date="1407507830" path="Flow.gif" size="3252" user="ProjectContributor" version="1"}%
+%META:FILEATTACHMENT{name="convert.pl.txt" attr="h" comment="" date="1501261498" path="convert.pl.txt" size="355" user="ProjectContributor" version="1"}%
+%META:FILEATTACHMENT{name="Flow.draw" attr="h" comment="" date="1501261498" path="Flow.draw" size="5504" user="ProjectContributor" version="1"}%
+%META:FILEATTACHMENT{name="Flow.gif" attr="h" comment="" date="1501261498" path="Flow.gif" size="3252" user="ProjectContributor" version="1"}%