Quality Management and Workflow Plugin

Description

• strictly object oriented
• parallel approvals: multiple persons may have to sign off to a certain degree
• consistent access control: purely rely on Foswiki's access control mechanism to grant access to documents; no unapproved content is disclosed by any means, such as other plugins accessing or indexing the content
• approval rights: maintain approval rights separate to pure change rights to a topic, so people can approve content yet have no other rights to change it
• roles: a role concept eases workflow definitions a lot
• visual workflows: workflows are visualized using GraphvizPlugin
• workflow history: improved storage format of the workflow history of a topic; backwards compatible with WorkflowPlugin
• commands: implement an open command handling mechanism that can be customized and extended by other plugins (commands are executed during transitions)
• fork-merge: approved documents may be forked into a copy while working on a new revision; the previously approved content is still accessible while the forked version is work in progress; the newly approved revision may then be merged back onto its origin where it was initially forked from
• conditions: additional checks may be put in place to limit or extend the set of edges that may be transitioned at a certain point in the workflow (e.g. when estimated costs are below a certain threshold can a product be acquired directly without extra approval by a responsible person)

Terminology

net

a net consists of nodes and directed edges connecting them; a net may be traversed by switching from one node to the next as long as they are connected by an edge and all conditions are met

node

identifies a set of properties at this position in the net

edge

connects two nodes in the net: a source node with a target node (we only consider directed graphs here)

workflow

a kind of net that defines a progression of steps that comprise a process involving one or more persons

role

one or more persons or groups that have specific responsibilities while acting on the workflow process

state

a document can be in a certain state by refering to a current node in the workflow; the state inherits properties from the current node

transition

a document may change its state by traversing one of the outgoung edges of the current node

activation

an edge is active when a document is in the state of the source node and all of the edge's constraints are met

acl

access control lists describe the set of persons or roles that are allowed to carry out a specific action

parallel approval

a document state change needs to be approved by multiple persons; the number of required approvals is specified by a sign-off percentage

• id: (required) unique identifier among all nodes of a workflow (e.g. draft, approved, submitted, ...)
• title: (optional) display title (e.g. Draft, Approved, Waiting for Approval, ...)
• message: (optional) verbose description (e.g. “This document is being worked on”, ''This document is waiting for approval.'', “This document is approved.'', ...)
• allowEdit: (optional) acl controling edit rights on the document
• allowView: (optional) acl controling view rights
• class: (optional) a css class to be added to the status box being rendered when the document is in that state
• viewTemplate: (optional) the VIEW_TEMPLATE setting that a topic inherits being in that state
• editTemplate: (optional) the EDIT_TEMPLATE setting that a topic inherits being in that state
• printTemplate: (optional) the PRINT_TEMPLATE setting that a topic inherits being in that state

• from: (required) id of the source node (or incoming node) of the edge
• action: (optional) id of the action performed on the source node, defaults to to
• title: (optional) display title of the action to be performed, defaults to =action
• to: (required) id of the target node (or outgoing node)
• allowed: (optional) acl controling the set of persons that are allowed to transition the state of the document
• enabled: (optional) a boolean constraint implemented as a TML expression to control if the edge's is allowed to be traversed
• notify: (optional) list of roles that are notified when the edge is transitioned
• mailTemplate: (optional) name of an email template to be used in a notification, defaults to QMPluginNotifyTemplate
• command: (optional) list of commands that are executed when this edge is traversed; see the list below for a description of known actions and their parameters
• signOff: (optional) minimum percentage of participants required to transition the state, default to 0%; as long as the sign-off is not reached yet will the document remain in the current state; only when all participants (specified in the “allowed” property) performed the same action on the node will the transition be carried out and the document reaches the target state

• id: (required) unique identifier among all roles of a workflow (e.g. Creator, Approver, Interested Party, ...)
• members: (required) list of persons, wiki groups or other roles
• description: (optional) a text to describe what this role is about
• notify: (optional) list of email addresses to be notified when required; if undefined will email addresses be extracted fom the wiki account of the listed persons; notification will be suppressed if defined as nobody.

| *ID* | *Members* | *Description* | 
| Creator  | %IF{"istopic '%WEB%.%TOPIC%'" then="$percntREVINFO{\"$username\" rev=\"1\"}$percnt" else="%USERNAME%"}% | %TRANSLATE{"Person that created this topic."}% | 
| Admin* | WorkflowAdminGroup | %TRANSLATE{"People with admin rights on the workflow."}% | 

Usage

---++ Nodes
| *ID*      | 
| created   |
| inprogress |
| submitted |
| approved*  |
| rejected  |

---++ Edges
| *From*    | *To*      | 
| created   | submitted | 
| inprogress | submitted | 
| submitted | approved  | 
| submitted | rejected  | 
| approved  | inprogress | 
| rejected  | inprogress | 

---++ Roles 
| *ID*     | *Members*                          | *Description* | *Notify* | 
| Creator  | %IF{"istopic '%WEB%.%TOPIC%'" then="$percntREVINFO{\"$username\" rev=\"1\"}$percnt" else="%USERNAME%"}% | %TRANSLATE{"Person that created this topic."}% | |
| Approver | %FORMFIELD{"ResponsiblePersons"}%  | %TRANSLATE{"People to approve this topic."}% |  |
| Admin*   | AdminGroup                         | %TRANSLATE{"People with admin rights on the workflow."}% |  |

---++ Nodes 
| *ID*       | *Title*              | *Allow Edit* | *Allow View*      | *Message* | *Attributes* | *View Template* | 
| created    | Created              | Creator      | Creator           | %TRANSLATE{"This document has just been created."}% | fillcolor="#ffb3b2", penwidth=0 | | 
| inprogress | In Progress          | Creator      | Creator           | %TRANSLATE{"This document is being worked on."}% | | | 
| submitted  | Waiting for Approval | Nobody       | Creator, Approver | %BLUE%%TRANSLATE{"This document is waiting for approval."}%%ENDCOLOR% | | | 
| approved*  | Approved             | Nobody       |                   | %GREEN%%TRANSLATE{"This document is approved."}%%ENDCOLOR% | | | 
| rejected   | Rejected             | Creator      | Creator, Approver | %RED%%TRANSLATE{"Approval for this document has been rejected."}%%ENDCOLOR% | | | 

---++ Edges 
| *From*     | *Action*          | *Icon*             | *Title*          | *To*       | *Allowed* | *Notify* | *Enabled* | *Trigger* | *Command* | *Sign Off* | *Attributes* | *Rank* | *Mail Template* |
| created    | request approval  | fa-question-circle | Request approval | submitted  | Creator   | Approver | | | | | penwidth=3 | | |
| inprogress | request approval  | fa-question-circle | Request approval | submitted  | Creator   | Approver | | | | | penwidth=3 | | |
| submitted  | approve           | fa-thumbs-o-up     | Approve          | approved   | Approver  | | | | merge | 100% | penwidth=3 | | |
| submitted  | reject            | fa-thumbs-o-down   | Reject           | rejected   | Approver  | Creator | | | | | | | |
| approved   | start revision    | fa-pencil          | Start revision   | inprogress | Approver, Admin | Creator | | | fork | | penwidth=3 | | |
| rejected   | resume            | fa-pencil          | Resume           | inprogress | Creator   | | | | | | | | |

%QMSTATE{workflow="SimpleApprovalWorkflow"}%

Custom Properties

%QMSTATE{
  format="<div class='$class'>
              $message
              Foo has got the value $foo, Bar is $bar
          </div>"
}%

Transition Commands

copy()

• topic="<targetTopic>"
• web="<targetWeb>"

• copy(web="Public")
• copy(topic="SomeOtherTopic")
• copy(topic="%TOPIC%Published")

createTopic()

• topic="<newTopic>" or "<newTopic": topic name to be created, can be a full web.topic
• web="<newWeb>: web to create the topic in, defaults to the current state's web
• overwrite="on/off": boolean switch to overwrite any existing topic, defaults to off thus warning when the same topic is about to be created again
• template="<templateTopic>": topic name of a template topic to be used
• form="<formTopic>": topic name of a template topic to be used
• parent="<parentTopic>"
• redirect="on/off": boolean switch to redirect to the newly created topic
• redirectto="...": web.topic name to redirect to after the topic has been created, can be a full http url as well
• <fieldName="..." value for the given field

createWeb()

deleteMeta()

• <name>

• deletemeta(CustomMeta)

fork()

• suffix="Copy"

formfield()

• topic="<targetTopic>"
• "<fieldName>"
• name="<fieldName>"
• value="<...>"

• formfield("TopicTitle" value="%FORMFIELD{"TopicTitle"}% (published)" topic="QMPluginPublished")

merge()

move()

• topic="<topic>" (default current topic)
• to="<web-topic>" target web-topic
• totopic="<topic>" target topic
• toweb="<web>" target web
• redirect="<web-topic>" where to redirect to after the topic has been renamed
• overwrite="on/off" boolean switch to overwrite a topic already existing, (default off)

pref()

• topic="<targetTopic>"
• "<prefName>"
• name="<prefName>"
• value="<...>"

• pref("token" value="1")
• pref("token" value="")
• pref("counter" value="%CALCULATE{"$EVAL(%counter{default="0"}%+1)"}%")

rest()

• <id>: ID of a predefined REST configuration = <key>=<value>: optional key-value pairs to be patched into the REST's url parameters, http header or body content

$Foswiki::cfg{QMPlugin}{RestConfig} = {
  notifyUser => {
    url => 'https://mycompany.com/bin/view/Applications/LocalApps/NotifyUser',
    method => "GET",
    params => {
      section => "test",
      skin => "text",
      user => "%val%",
    },
  },
  postMessage => {
    url => 'https://mycompany.com/bin/view/Applications/LocalApps/PostMessage',
    method => "POST",
    body => {
      foo => "%val%",
      bar => "%val%",
      baz => "%val%",
    },
  }
};

%notifyUser_response%

%postMessage_response%

rest("postMessage" foo="val1" bar="val2" baz="var3"), pref("result" value="%postMessage_response%") |

trash()

• "<sourceTopic>
• topic="<sourceTopic>"

• trash(topic="%TOPIC%Published")

QMSTATE

• $action: last action that lead to the current state
• $actionTitle: title of the last action that lead to the current state
• $actions: list of possible actions of outgoing edges from the given state
• $edges: list of possible transitions from the given state
• $nodes: list of possible target nodes from the given state to transition to
• $adminRole: id of the admin role
• $approvalID: id of node flag as being the approval node
• $approvalIDs: ids of nodes flag as being the approval node
• $approvalRev: most recently approved revision
• $approvalTime: time in epoch seconds of the most recent approval
• $approvalDuration: time since since the last approval
• $author: user that performed the last action
• $comment: comment provided by performing the last action
• $comments: all comments of people participating in a parallel approval
• $date: date of the recent change of the state
• $datetime: date-time of the recent change
• $defaultNode: starting node in the workflow net
• $duration: time since the last change in seconds
• $emails: list of emails to notify when this state has been reached
• $epoch: epoch seconds of the recent change
• $hasComments: boolean flag indicating the existence of comments
• $hasPending: boolean flag indicating the existence of pending reviews in a parallel approval
• $id or $state: current state id
• $isAdmin: boolean indicating whether the current user is an admin
• $notify: list of people to notify when this state has been reached
• $numActions: number of next actions that the current user can perform on the current state
• $numEdges: number of possible transitions that the current user can follow from the current state
• $numReviews: number of reviews of the current state; in general this is one, but could be more on parallel reviews
• $numComments: number of reviews that have comments
• $origin: if the current state is a fork, then this property points back to the original topic from which this one has been forked from.
• $pendingAction: action that has been already performed by other reviewers of a parallel approval
• $pendingReviewers: list of users that still require to review the state change in a parallel approval
• $possibleReviewers: list of all users that may perform an action on any outgoing edge from the current state on
• $previousState, $previousNode: id of the node that lead to the current workflow state
• $rev: revision of the topic that the current workflow state is attached to
• $reviewFrom: state that has been reviewed
• $reviewAction: action of the last review
• $reviewTo: target state of the last review
• $reviewers: list of users that already reviewed the state change in a parallel approval
• $reviews: list of reviews that led to this state; this is composed by iterating over all reviews using the following review... format strings
• $roles: list of available roles in a workflow definition
• $signOff: percentage ratio of number of users that already reviewed the current state change
• $topic: topic name
• $to: node id to which the latgest review is targeting to
• $toTitle: title of the node to which the latest review is targeting to
• $web: web name
• $workflow: topic of the workflow definition

QMBUTTON

• $class: css class
• $icon: button icon, see VarJQICON
• $rev: revision of the topic that the current workflow state is attached to
• $text: button label
• $topic: topic name
• $web: web name
• $workflow: topic of the workflow definition

QMNET

• $count: number of items in the list
• $workflow: the topic defining the workflow

QMNODE

• $allowEdit, $allowView: list of roles that are allowed to edit/view a document in this node state
• $isParallel: true when there are next actions that must be signed off by multiple users
• $message: message string part of this node
• $rev: revision of the topic that the current workflow state is attached to
• $state, $id: the id of the current node
• $text: button label
• $title: title of this node
• $topic: topic name
• $web: web name

QMEDGE

• $action: action carried out while traversing the edge
• $from: source node id
• $rev: revision of the topic that the current workflow state is attached to
• $text: button label
• $topic: topic name
• $to: target node id
• $web: web name

QMROLE

• $id: id of the role
• $members: list of role members
• $isMember, $isMember(...): returns 1 if the current user (or the one given in brackets) is a member of this role, or 0 otherwise
• $description: text in the description column of a role definition
• $notify: list of people to notify when an action is performed using this role; if left empty the system email information will be used
• $rev: revision of the topic that the current workflow state is attached to
• $topic: topic name
• $web: web name

QMHISTORY

• $count: the total number of states found in the history filters applied
• $title: the value of the title parameter

QMGRAPH

Parameter	Description	Default
"..." or topic		current topic
warn	alernative to ignoreerror	on
ignoreerror	boolean switch to disable any possible error message that might occur	off
template	template being used when to render the dot graph	value of the qm::graph template
workflow	workflow definition	current topic's workflow

Helper Functions

• $emails(<list of user(s)>): get all emails of all given user strings
• $formatDateTime(<epoch>): format datetime of epoch seconds
• $formatTime(<epoch>, <format>): format date of epoch seconds
• $edgeTitle(<from>, <action>[, <to>]): get the title of an edge
• $nodeTitle(<node-id>): get the title of a node
• $userName(<list of user(s)>): get usernames of all given user strings
• $wikiName(<list of user(s)>): get wikinames of all given user strings
• $wikiUserName(<list of user(s)>): get wikiusernames of all given user strings
• $wikiUserTitle(<list of user(s)>): get wiki user title of all given user strings

Email Notifications

%TMPL:INCLUDE{"QMPluginNotify"}%

%TMPL:DEF{"qm::notify::header::subject"}%Subject: [WIKI-NOTIFICATION] - %TMPL::PREV%%TMPL:END%

• qm::notify: entry point of the template, everything else hangs off this definition
• qm::notify::init: an optional init stage while creating the email, empty by default
• qm::notify::header: email header composed by the following definitions
  • qm::notify::header::from
  • qm::notify::header::to
  • qm::notify::header::subject
  • qm::notify::header::priority
  • qm::notify::header::misc
• qm::notify::body: the email body is split up into two parts
  • qm::notify::body::text::header: mime separator
  • qm::notify::body::text email in text format
  • qm::notify::body::html::header: mime separator
  • qm::notify::body::html email in html format
• qm::notify::body::text contains a standard text as well sub-definitions:
  • qm::notify::greeting::text
  • qm::notify::closing::text
  • qm::notify::body::reviews: this is shared in both text and html versions
• qm::notify::body::html is structured similarly with
  • qm::notify::greeting::html
  • qm::notify::closing::html
  • qm::notify::body::reviews: this is shared in both text and html version

DataForms Integration

qmstate formfield

| *Name:*| *Type:* | *Size:* | *Values:*      | *Description:*          | *Attributes:* | *Default:* |
| State  | qmstate | 1       | workflow="..." | current workflow state  |               |            |

qmworkflow formfield

| *Name:*   | *Type:*    | *Size:*  | *Values:*                 | *Description:*           | *Attributes:*  | *Default:* |
| Workflow  | qmworkflow | 30       | web="..." TopicType="..." | workflow for this topic  |                |            |

WikiWorkbench Integration

• WorkflowDefinition
• ControlledTopic
• ClassifiedControlledTopic

Perl API

Support for SolrPlugin

Installation Instructions

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

Dependencies

Change History