Skip to content

Commit

Permalink
Item14048: parking remaining work
Browse files Browse the repository at this point in the history
  • Loading branch information
@MichaelDaum
MichaelDaum committed Sep 18, 2017
1 parent a876a24 commit 39f77ad
Show file tree
Hide file tree
Showing 7 changed files with 525 additions and 335 deletions.
14 changes: 7 additions & 7 deletions .gitignore
View file
@@ -1,9 +1,9 @@
*.swp
igp_*
WorkflowPlugin.md5
WorkflowPlugin.sha1
WorkflowPlugin.tgz
WorkflowPlugin.txt
WorkflowPlugin.zip
WorkflowPlugin_installer
WorkflowPlugin_installer.pl
/WorkflowPlugin.md5
/WorkflowPlugin.sha1
/WorkflowPlugin.tgz
/WorkflowPlugin.txt
/WorkflowPlugin.zip
/WorkflowPlugin_installer
/WorkflowPlugin_installer.pl
185 changes: 167 additions & 18 deletions data/System/VarWORKFLOW.txt
View file
@@ -1,23 +1,170 @@
%META:TOPICINFO{author="ProjectContributor" date="1407507830" format="1.1" version="1"}%
#VarWEB
---+++ WORKFLOW* -- macros 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>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 <strike>struck out</strike>).|
| =%<nop>WORKFLOWFORK{...}%= | Expands to a button that will create a copy of the _current_ topic (see below for more details) |
| =%<nop>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* ||
| =%<nop>WORKFLOWHISTORY%= | Expands to the history of state transitions the topic has undergone. The format of the history is dictated by the =WORKFLOWHISTORYFORMAT= (described below). |
| =%<nop>WORKFLOWLASTREV{"State"}%= | Expands to the version number when the document was last in the state _State_. |
| =%<nop>WORKFLOWLASTTIME{"State"}%= | Expands to the timestamp when the document was last in the _State_ state. For example, =%<nop>WORKFLOWLASTTIME{"APPROVED"}%= would be replaced by the timestamp when the document was last in the =APPROVED= state. |
| =%<nop>WORKFLOWLASTUSER{"State"}%= | Expands to the last user who transitioned the document into the state _State_. |
| =%<nop>WORKFLOWLASTVERSION{"State"}%= | Expands to a link to the version of the document when it was last in the state _State_. |
| =%<nop>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. |
| =%<nop>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.
---+++ WORKFLOWSTATE

Render information about the current state of the documentation

Syntax =%<nop>WORKFLOWSTATE{"&lt;<topic>" &lt;parameters>"}%=

| *Parameter* | *Description* | *Default* |
| =&lt;topic>= | topic to return the state of | current topic |
| =rev= | revision of the topic | latest revision |
| =state= | specify the state to render information about | current workflow state of the topic |
| =hidenull= | boolean to hide any output in case the revision to render is not the latest one | off |
| =format= | format string to render state information | =$state= |

The =format= parameter may take a couple of variables that expand to the properties of the given topic, revision and state:

* =$web=: the web name of the current topic
* =$topic=: the topic name
* =$state=: the state label as specified in the state table
* =$message=: the state message of the current topic's state
* =$rev=: the revision of the topic when it last was in the given state
* =$user=: the user last user who transitioned the topic to the state
* =$time=: the timestamp when the topic was last in the state
* =$comment=: the comment provided when transitioning into the state
* =$numactions=: the number of possible transitions that may follow up to the current state
* =$actions=: comma-separated list of possible actions starting from this state
* =$allowedit=: edit rights of the topic in the current state
* =$allowview=: view rights of the topic in the current state
* =$prevstate=: previous state before the topic transitioned into the current one
* =$prevaction=: action being used to transition the topic into the current state
* =$defaultstate=: label of the default starting state of the workflow

---+++ 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) |

Note that you may also create a custom UI to transition a document. Below an example to render a button to trigger a modal transition dialog.

<verbatim class="tml">
%JQREQUIRE{"ui::dialog"}%

%IF{"$'URLPARAM{rev}'='' and '%WORKFLOWSTATE{format="$numactions"}%'>0"
then="$percntBUTTON{
\"Change State\"
href=\"#changeStateDialog\"
class=\"jqUIDialogLink\"
}$percnt"
}%

<div id="changeStateDialog" title="Change State" class="jqUIDialog foswikiHideOnPrint" style="display:none" data-modal="true" data-position="center" data-width="540" data-cached="true">
<form class="workflowChangeStateForm" action="%SCRIPTURLPATH{"rest"}%/WorkflowPlugin/changeState" method="post">
<div class="foswikiFormSteps">
<div class="foswikiFormStep">
<h3>New State:</h3>
%FORMATLIST{
"%WORKFLOWSTATE{format="$actions"}%"
split="\s*,\s*"
selection="^(%FORMATLIST{"%WORKFLOWSTATE{format="$actions"}%" split="\s*,\s*" limit="1"}%)$"
marker="checked='checked'"
format="<label><input type='radio' name='WORKFLOWACTION' $marker value='$1'>$1</label>"
separator="$n"
}%
</div>
<div class='foswikiFormStep'>
<h3>Comment:</h3>
<input type="text" name="WORKFLOWCOMMENT" size="60" class="foswikiInputField" />
</div>
<a class="jqUIDialogButton jqUIDialogSubmit {icon:'ui-icon-circle-check'}">%MAKETEXT{"Submit"}%</a>
<a class="jqUIDialogButton jqUIDialogClose {icon:'ui-icon-cancel'}">%MAKETEXT{"Cancel"}%</a>
</div>
</form>
</div>
</verbatim>

---+++ WORKFLOWFORK

Expands to a button that will create a copy of the _current_ topic (see below for more details)

---+++ WORKFLOWHISTORY

Expands to the history of state transitions the topic has undergone. The format of the history is dictated by the =WORKFLOWHISTORYFORMAT= (described below).

---++ Deprecated WORKFLOW* macros

Below macros are still provided for backwards compatibility but are superseded by the =%WORKFLOWSTATE= and =%WORKFLOWTRANSITION= macros.

---+++ WORKATTACHTOPIC, WORKFLOWEDITTOPIC
Expands to a link that lets you attach or edit 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>.

Change access to a topic controlled by a workflow is properly controlled by Foswiki's own access control mechanisms. Use below expression to display or suppress an edit link if needed:

<verbatim class="tml">
%IF{"'%TOPIC%' allows 'change'"
then="<a href='%SCRIPTURLPATH{"edit"}%/%WEB%/%TOPIC%?t=%GMTIME{"$epoch"}%>edit</a>"
else="<a href='#'><del>edit</del></a>"
}%
</verbatim>

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

Use below expression instead:

<verbatim class="tml">
%WORKFLOWSTATE%
</verbatim>


---+++ WORKFLOWSTATEMESSAGE

Expands to the corresponding message in the state table.

Use below expression instead:

<verbatim class="tml">
%WORKFLOWSTATE{state="..." format="$message"}%
</verbatim>

---+++ WORKFLOWLASTUSER

Expands to the last user who transitioned the document into the state.

Use below expression instead:

<verbatim class="tml">
%WORKFLOWSTATE{state="..." format="$user"}%
</verbatim>

---+++ WORKFLOWLASTTIME
Expands to the timestamp when the document was last in the given state.

Use below expression instead:

<verbatim class="tml">
%WORKFLOWSTATE{state="..." format="$time"}%
</verbatim>

For example, =%<nop>WORKFLOWSTATE{state="APPROVED" format="$time"}%= would be replaced by the timestamp when the document was last in the =APPROVED= state.

---+++ WORKFLOWLASTREV

Expands to the version number when the document was last in the state.

Use below expression instead:

<verbatim class="tml">
%WORKFLOWSTATE{state="..." format="$rev"}%
</verbatim>

---+++ WORKFLOWLASTVERSION

Expands to a link to the version of the document when it was last in the state

Use below expression instead:

<verbatim class="tml">
%WORKFLOWSTATE{
state="..."
format="<a href='%SCRIPTURLPATH{"view"}%/$web/$topic?rev=$rev'>Display topic last time in state '$state'</a>"
}%
</verbatim>


---++ Further notes on WORKFLOW* macros
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).

Expand Down Expand Up @@ -59,3 +206,5 @@ The histories in both the fork copies and the original topic record what happene
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.

%X% 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.

%JQREQUIRE{"chili"}%
65 changes: 36 additions & 29 deletions data/System/WorkflowPlugin.txt
View file
@@ -1,12 +1,12 @@
%META:TOPICINFO{author="ProjectContributor" date="1407507830" format="1.1" version="1"}%
%META:TOPICINFO{author="micha" date="1446804144" format="1.1" version="2"}%
%META:TOPICPARENT{name="ReferenceManual"}%
---+ %TOPIC%
<!--
* Set SHORTDESCRIPTION = %$SHORTDESCRIPTION%
-->
<div style="float:right">
%ATTACHURL%/Flow.gif
</div>
<img src="%ATTACHURL%/Flow.gif" align="right" width='291' height='369' alt='Flow.gif' />
%FORMFIELD{"Description"}%

%TOC%

---++ Description
Foswiki provides a flexible system of Access Control Lists that can be used to control who can modify a topic. Sometimes this isn't quite enough, and the access control depends on the state that a topic is in.

For example,
Expand All @@ -26,8 +26,12 @@ A workflow can be associated with a single topic, or with an entire web.

---++ 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_).
A topic is under document control if the workflow name is set

* in a preference variable =WORKFLOW= in the topic page or
* in a form field named "Workflow" in the attached [[%SYSTEMWEB%.DataForms][data form]]

The workflow name 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.

Expand All @@ -37,19 +41,20 @@ The workflow description topic must contain one state table and one transition t

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 table with four columns:

<verbatim>
| *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.|
| *State* | *Allow Edit* | *Allow View* | *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.|
</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 *Allow Edit* column specifies who is permitted to edit the topic when it is in the state,
* the *Allow View* column specifies who is permitted to view 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
Expand Down Expand Up @@ -92,6 +97,7 @@ If a form name is given in the *Form* column, this form will be attached to the
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 | webmaster@example.com | |
| User wiki names | Main.WikiGuest | |
Expand All @@ -114,7 +120,7 @@ Content-Type: text/plain
%SCRIPTURL{"view"}%/%WEB%/%TOPIC%
</verbatim>

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 beginning below the first blank 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 [[%%BASETOPIC%#Content_45sensitive_workflows][content-sensitive workflows]] section for more on how !WorkflowPlugin expands macros.
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 beginning below the first blank 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_45sensitive_workflows][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. Custom notification templates can either provide valid headers that define their recipients or access the =EMAILTO= macro, so other email addresses provided will be sent exclusively through custom templates.

Expand All @@ -130,12 +136,6 @@ For example, the *Notify* column in the transition below will email =jim@example

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.

%INCLUDE{VarWORKFLOW}%

If you replace =%<nop>EDITTOPIC%= with =%<nop>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 =%<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'
Expand Down Expand Up @@ -164,12 +164,16 @@ 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.

---++ Reporting
---+++ 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"}%
</verbatim>

---++ Syntax
%INCLUDE{VarWORKFLOW}%


---++ History and Acknowledgements

This plugin was motivated by [[Foswiki:Main.ThomasWeigert][Thomas Weigert]]'s [[Foswiki:Extensions.WorkFlowAddOn][WorkFlowAddOn]] and its first version (then called !ApprovalPlugin) was written by Thomas Hartkens, albeit it was focused on document approval and control. [[Foswiki:Main.ThomasWeigert][Thomas Weigert]] then merged the functionality of the [[Foswiki:Extensions.WorkFlowAddOn][WorkFlowAddOn]] into this plugin.
Expand All @@ -187,11 +191,14 @@ __Note:__ For strict access control, the plugin should know who is looking at th

%META:FORM{name="PackageForm"}%
%META:FIELD{name="Author" title="Author" value="Thomas Hartkens, Foswiki:Main.ThomasWeigert, Foswiki:Main.CrawfordCurrie"}%
%META:FIELD{name="Version" title="Version" value="%$VERSION%"}%
%META:FIELD{name="Release" title="Release" value="%$RELEASE%"}%
%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:FIELD{name="Version" title="Version" value="%25$VERSION%25"}%
%META:FIELD{name="Release" title="Release" value="%25$RELEASE%25"}%
%META:FIELD{name="Description" title="Description" value=""}%
%META:FIELD{name="Repository" title="Repository" value="https://github.com/foswiki/WorkFlowPlugin"}%
%META:FIELD{name="Copyright" title="Copyright" value=""}%
%META:FIELD{name="License" title="License" value=""}%
%META:FIELD{name="Home" title="Home" value="https://foswiki.org/Extensions/WorkflowPlugin"}%
%META:FIELD{name="Support" title="Support" value="http://foswiki./org/Support/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"}%

0 comments on commit 39f77ad

Please sign in to comment.