QMPlugin Perl API

internal package Foswiki::Plugins::QMPlugin

base class to hook into the foswiki core

initPlugin($topic, $web, $user) → $boolean

initialize the plugin, automatically called during the core initialization process

finishPlugin

finish the plugin and the core if it has been used, automatically called during the core initialization process

getCore() → $core

returns a singleton Foswiki::Plugins::QMPlugin::Core object for this plugin; a new core is allocated during each session request; once a core has been created it is destroyed during finishPlugin()

beforeSaveHandler($text, $topic, $web, $meta )

make sure the saved topic has got the right access control settings

afterSaveHandler($text, $topic, $web, $error, $meta )

make sure the saved topic has got the right access control settings

registerCommandHandler($id, $type, $handler)

register a function that can be refered to by the given id. there are two types of handler:

• beforeSave: function is called before a state is saved
• afterSave: function is called after a state is saved

internal package Foswiki::Plugins::QMPlugin::Core

core class for this plugin

an singleton instance is allocated on demand

ClassProperty TRACE

boolean toggle to enable debugging of this class

ClassProperty @defaultHandler

list of default handlers

ClassMethod new() → $core

constructor for a Core object

ObjectMethod finish()

called when this object is destroyed

ObjectMethod getUsers() → @users

get the list of all users known to the core up to this point

ObjectMethod getUser($id) → $user

get a user of a specific id

ObjectMethod getSelf() → $user

get the user for the currently logged in user

ObjectMethod getGroups() → @groups

get the list of all groups known to the core up to this point

ObjectMethod getGroup($id) → $group

get a group of a specific id

ObjectMethod saveMeta($meta)

save a meta by suppressing the beforeSaveHandler

ObjectMethod afterSaveHandler($web, $topic, $meta)

make sure the saved topic has got the right access control settings

ObjectMethod beforeSaveHandler($web, $topic, $meta)

• make sure the saved topic has got the right workflow
• trigger a state change when a qmstate formfield has been altered

ObjectMethod getFormfieldDefinition($meta, $type) → $fieldDef

returns a Foswiki::Form::FieldDefinition for the given formfield type. this is used to return the definitions of a qmstate or qmworkflow formfield.

returns undef if the form doesn't have a formfield of the requested type

ObjectMethod getQMStateFormfield($meta) → $field

return a formfield of a qmstate if it exists

ObjectMethod getQMWorkflowFormfield($meta) → $field

return a formfield of a qmworkflow if it exists

ObjectMethod jsonRpcCancelTransition($session, $request)

json-rpc handler for the cancelTransition procedure

ObjectMethod jsonRpcChangeState($session, $request)

json-rpc handler for the changeState procedure

ObjectMethod jsonRpcSendNotification($session, $request)

json-rpc handler for the sendNotification procedure

ObjectMethod restTriggerStates($session)

this handler searches for topics with a workflow attached to it and triggers any automatic transition found. Parameters

• webs: list of webs to search for controlled topics, defaults to all webs
• includeweb: regular expression of webs to include into the process (default all)
• excludeweb: regular expression of webs to exclude from the process (default none)
• includetopic: regular expression of topics to include into the process (default all)
• excludetopic: regular expression of topics to exclude from the process (default none)
• includeworkflow: regular expression of workflows to process (default all)
• excludeworkflow: regular expression of workflows to exclude from the process (default none)
• dry: boolean switch to enable a "dry run" not changing anything (defaults to "off")

WARNING: this handler is typically called by a cronjob, from the commandline or by admins.

ObjectMethod QMHISTORY($session, $params, $topic, $web)

macro implementation for %QMHISTORY

ObjectMethod QMNET($session, $params, $topic, $web)

macro implementation for %QMNET

ObjectMethod QMSTATE($session, $params, $topic, $web)

macro implementation for %QMSTATE

ObjectMethod QMNODE($session, $params, $topic, $web)

macro implementation for %QMNODE

ObjectMethod QMROLE($session, $params, $topic, $web)

macro implementation for %QMROLE

ObjectMethod QMEDGE($session, $params, $topic, $web)

macro implementation for %QMEDGE

ObjectMethod QMGRAPH($session, $params, $topic, $web)

macro implementation for %QMGRAPH

ObjectMethod QMBUTTON($session, $params, $topic, $web)

macro implementation for %QMBUTTON

ObjectMethod getState($web, $topic, $rev, $meta, $force) → $state

get the workflow state of the given topic

ObjectMethod getNet($web, $topic, $state) → $net

returns a Foswiki::Plugins::QMPlugin::Net object and assignes the given state.

ObjectMethod getStates($web, $topic, $rev, $params) → @states

get all workflow states of the given topic up to revision $rev

ObjectMethod registerCommandHandler($handler)

register a command handler. commands are executed when an edge is traversed.

The handler is a hash reference with the following properties:

• id: name of the command that may is executed, e.g. "fork", "merge" or "trash"
• type: type of the command: "beforeSave", "afterSave"
• package: perl package
• function: function within the package to be called
• callback: callback function

Note that either "package" and "function" are specified, or a "callback" is given right away.

ObjectMethod getCommandHandlers($id) → @callbacks

get the list of registered handlers for a specified action id

ObjectMethod redirectUrl(url)

the redirect property records the need of the system to initiate a redirect at the end of the processing queue

ObjectMethod solrIndexTopicHandler($indexer, $doc, $web, $topic, $meta, $text)

hooks into the solr indexer and add workflow fields

ObjectMethod solrIndexAttachmentHandler($indexer, $doc, $web, $topic, $attachment)

hooks into the solr indexer and add workflow fields

ObjectMethod dbCacheIndexTopicHandler($db, $obj, $web, $topic, $meta, $text)

hooks into the dbcache indexer and add workflow fields

internal package Foswiki::Plugins::QMPlugin::State

implements a state that a network is in

a topic is in a certain state. one state can transition into another by following the topological constraints of the underlying network.

ClassProperty TRACE

boolean toggle to enable debugging of this class

ClassProperty PROPS

definition of all mandatory properties of an object of its kind; node, edge and role classes each refine this list

ClassMethod new($web, $topic, $rev, $meta) → $state

constructor for a state object

ObjectMethod init($web, $topic, $rev, $meta)

init this state by reading the associated topic; this method is called as part of the constructor, but may also be called afterwards to assign a different topic or revision to it.

ObjectMethod finish()

called when this object is destroyed

ObjectMethod setWorkflow($workflow) → $net

set the workflow definition topic of this state; this is either done as part of the init() method; returns a Net object when a workflow as set successfully, undef otherwise.

ObjectMethod unsetWorkflow($workflow) → $net

remove the workflow definition and its net from this state

ObjectMethod props() → @props

get a list of all known state properties

ObjectMethod prop($key, $val) → $val

getter/setter of a certain property of this state

ObjectMethod deleteProp($key) → $val

remove a property from this state, returns the original value

ObjectMethod expandValue($val) → $val

expand the given value in the context of the current topic

ObjectMethod save(%params) → $this

save this state into the assigned topic/ params are forwared to Foswiki::Meta::save().

ObjectMethod updateMeta() → $this

save this state into the assigned meta object, don't save it to the store actually

ObjectMethod change($action, $to, $comment, $user, $keepReviews) → $boolean

change this state by performing a certain action, providing an optional comment; returns true if the action was successfull and the state has been transitioned along the lines of the net. Otherwise an error is thrown. Note that only the properties of this state are changed; it is not stored into the current topic; you must call the save() method to do so.

The keepReviews boolean allows to keep review objects from a previous transition. Previous review objects will be filtered out not matching the current action.

ObjectMethod resetReviews() → $boolean

reset an ongoing parallel review to the start. returns true if any review was found and deleted

ObjectMethod filterReviews($action, $id) → $boolean

removes any review that does not the given state and action parameters, returns true if an review has been deleted.

ObjectMethod traverse($edge, $comment)

change the current state by traversing the given edge; note that this only changes the current location within the net; the changed data is not stored into the current state.

ObjectMethod updateCustomProperties()

recompute all custom node properties and store them into the state

ObjectMethod log($edge, $comment)

write the event of traversing the given edge to the wki logs with an optional comment

ObjectMethod queueCommand($edge, $id, $params)

queue the command of an edge being traversed

ObjectMethod processCommands($type)

commands are processed after this state has been saved, not earlier, as some commands handler might alter the store of the changed state, such as moving the related topic to the trash.

ObjectMethod sendNotification($template) → $errors

sends a notifications for the current edge transition. This is called when a transition has actually happened, but may also be called later on to re-send the email notification. this method is always called when save() is performed; the method returns a list of errors that may have happened as part of the mail delivery process. See also Foswiki::Func::sendEmail.

$template is the name of the template to be used for the email, defaults to qmpluginnotify.

ObjectMethod getNotificationTemplate($edge) → $templateName

get the name of the template for the given edge. if the edge doesn't have a mailTemplate property will the QMNet's default net be used. See Foswiki::Plugins::QMPlugin::Net::getNotificationTemplate().

ObjectMethod setACLs($node) → $boolean

sets the ACLs as imposed by the current node of the state or the specified one; this method is called by save() itself and probably of no direct use otherwise.

returns true if acls changed and false if no change was needed.

ObjectMethod getWeb() → $web

get the web of this state

ObjectMethod getTopic() → $topic

get the topic of this state

ObjectMethod getMeta() → $meta

get the meta object of this state

ObjectMethod getRevision() → $rev

get the revision of the topic of this state

ObjectMethod getLastApproved($force) → $state

get the state that was last approved starting at the current rev. if $force is set the last revision will be digged out by a search. the approvalRev property will be used otherwise.

ObjectMethod getReviews() → @reviews

get all reviews of this state

ObjectMethod numReviews() → integer

get the number of reviews in this state

ObjectMethod numComments() → integer

get the number of reviews in this state

ObjectMethod getReviewEdge() → $edge

get the edge that has been reviewed

ObjectMethod getCurrentNode() → $node

get the node that this state is currently associated with

ObjectMethod getCurrentEdge() → $edge

get the edge that has been traversed to reach this state

ObjectMethod getNet() → $net

get the net that this state is currently associated with

ObjectMethod getPossibleActions($node, $user) → @actions

get the list of possible actions starting from the current node or the node specified in the call; the empty list is returned when user is not allowed to perform any actions

ObjectMethod getTriggerableActions($node, $user) → @actions;

get a list of actions that might be triggered

ObjectMethod getPossibleEdges($node, $user) → @actions

get the list of possible edges starting from the current node or the node specified in the call; the empty list is returned when user is not allowed to perform any actions

ObjectMethod getTriggerableEdges($node, $user) → @actions;

get a list of edges that might be triggered

ObjectMethod isReviewedBy($user) → $boolean

returns true when the current state has been reviewed by user already

ObjectMethod isParallel() → $boolean

returns true when there the current review actions must be signed off by multiple users

ObjectMethod isApproved($node) → $boolean

returns true if the given or current node of the state is an approval node

ObjectMethod hasChanged() → $boolean

returns true when this state was changed as part of a transition, returns false if other changes happened to the topic

ObjectMethod getCurrentSignOff($edge) → $percent

get the current sign-off progress counting the number of people that already reviewed this state

ObjectMethod addReview($data)

create a new review of this state

ObjectMethod getReviewers($action) → @users

get the list of users that already reviewed the current state

ObjectMethod getNumReviews($edge) → $number

returns the number of people that already reviewed the current state using the given action

ObjectMethod getComments() → @comments

get the list of comments in reviews; each item in the result list has properties:

• author
• date
• text

ObjectMethod getPossibleReviewers($from, $action, $to) → @users

get the list of allowed users of outgoing edges, optionally performing a certain action; returns an empty list there are no specific restrictions, that is all users may perform a certain action

ObjectMethod getPendingApprovers($node) → @users

get the list of users that still need to approve the current state

ObjectMethod getPendingReviewers($edge) → @users

get the list of users that still need to review the current state

ObjectMethod reroute($web, $topic, $meta)

create a copy of the underlying topic and continue the state there

ObjectMethod reassign($to)

change meta object part of this state

ObjectMethod render($format) → $string

render the properties of this object given the specified format string

ObjectMethod asJson() → $json

ObjectMethod renderReviews() → $string

returns a string representation of all reviews of a state

ObjectMethod getCore() → $core

convenience method to get the plugin core

ObjectMethod translate($string) → $string

translates a string using MultiLingualPlugin

ObjectMethod stringify() → $string

returns a string representation of this object

ObjectMethod json()

returns a JSON encoder/decoder

internal package Foswiki::Plugins::QMPlugin::Net

implements a workflow network

A net consists of nodes, edges that connect them and roles that participate in this workflow. A net is constructed on the base of a workflow definition. A net can either be defined in a way only reflecting the typology or have a State assigned to it. The State encodes the location within the network. The state has been reached by having traversed the edges in the net from the start node following outgoing directed edges.

ClassProperty TRACE

boolean toggle to enable debugging of this class

ClassMethod new($web, $topic, $state) → $net

constructor for a net object; this either returns a net object or undef when parsing of the network definition failed for some reason

ObjectMethod finish()

called when this object is destroyed, calls finish() on its parts

ObjectMethod setState($state) → $state

assign a state to this network

ObjectMethod getState() → $state

get the state assigned to this network

ObjectMethod getNodes() → @nodes

get the list of all nodes in this net

ObjectMethod getNode($id) → $node

get a node of a specific id

ObjectMethod getRoles() → @roles

get the list of all roles in this net

ObjectMethod getRole($id) → $role

get a role of a specific id

ObjectMethod getEdges() → @edges

get the list of all edges in this net

ObjectMethod getEdge($from, $action, $to) → $edge

get a specific edge in this net. The parameters $from, $action and $to specify which edge to return. All parameters are optional and may be specified in different combinations. If more than one edge matches the given parameter will only the first one found be returned.

ObjectMethod getSortedItems($type, $propName) → @items

get the list of all items of type $type (nodes, roles, edges) sorted by the given property Name

ObjectMethod getSortedRoles($propName) → @roles

get the list of all roles sorted a given property name

ObjectMethod getSortedNodes($propName) → @nodes

get the list of all nodes sorted by a given property name

ObjectMethod getSortedEdges($propName) → @edges

get the list of all edges sorted by a given property name

ObjectMethod getDefinition() → $webtopic

get the webtopic path of the network definition

ObjectMethod getMeta() → $meta

get the Foswiki::Meta object of the current net

ObjectMethod getNotificationTemplate() → $templateName

get the name of the template for workflow notification emails

ObjectMethod getReminderTemplate() → $string

get the name of the template for workflow reminders

ObjectMethod parseTableDefinition() → $boolean

parse the definition for this net stored in TML tables. this is called by the constructor right away; returns true when parsing was successfull. There is a certain amount of compatibility with WorkflowPlugin in that workflow definitions written for it may be used in QMPlugin as well.

WorkflowPlugin format

States

State	Allow Edit	Allow View	Message

Transitions

State	Action	Next State	Allowed	Form	Notify

QMPlugin format

Roles table

ID	Members	Notify

Nodes table

ID	Title	Allow Edit	Allow View	Allow Approve	Message

Edges table

From	Action	To	Allowed	Enabled	Notify	Command	Sign Off

ObjectMethod getUnknownNode() → $node

get the "unknown" node; it is a system node not part of the net

ObjectMethod getDefaultNode() → $node

get the default node; this is the first node in the node definition list

ObjectMethod getApprovalNodes() → $list

get all nodes marked as approval nodes in this net; this is the one node that has got an asterisk (*) assigned to it or has got the ID QMPLUGIN_APPROVAL (defaults to approved)

ObjectMethod getAdminRole() → $role

get the admin role of this net; this is the one role that has got an asterisk (*) assigned to it, or has got the ID QMPLUGIN_ADMIN (defaults to Admin)

ObjectMethod isAdmin($user)

returns true if the given user is member of the admin role

ObjectMethod stringify() → $string

returns a string representation of this object

ObjectMethod getDot($params) → $tml

returns a TML expression to render the graphviz dot graph

ObjectMethod getVis($params) → $tml

returns a TML expression to render the Vis.js graph

internal package Foswiki::Plugins::QMPlugin::Edge

implements an Edge in a workflow Net

an edge is a directed connection between two Nodes part of a Net

ClassProperty PROPS

definition of all mandatory properties of an edge

ClassMethod new() → $core

constructor for an edge object

ObjectMethod fromNode()

get the node on the source end of this edge

ObjectMethod toNode()

get the node on the target end of this edge

ObjectMethod getSignOff() → $float

get the number of signatures required to transition this edge;

This can either be a relative value as a percent value between 0 and 1 if the value is preceeded with a percent sign, or a value > 1 representing the absolute number of signatures required.

ObjectMethod isRelativeSignOff() → $boolean

returns true of a relative signoff has been specified using a percentage

ObjectMethod getReviewers() → @reviewers

returns a list of users that may switch this edge

ObjectMethod getNotify() → @users

returns a list of users that have to be notified

ObjectMethod getEmails() → @emails

returns the list of email adressess to notify when this edge is transitioned

ObjectMethod isEnabled($user) → $boolean

returns true if this edge is enabled, that is:

1. the "enabled" attribute of the edge evaluates to true (or is undef) and
2. user is a member of the "allowed" list

ObjectMethod isTriggerable($user) → $boolean

returns true if this edge is enabled and triggerable, that is:

1. the edge is enabled
2. the "trigger" attribute evaluates to true and
3. user is a member of the "allowed" list

ObjectMethod render($format, $params) → $string

render this edge given the specified format string

ObjectMethod execute($state)

execute all commands of this edge

ObjectMethod asJson($state)

returns a json object representing this edge

internal package Foswiki::Plugins::QMPlugin::Node

implements a Node in a workflow Net

Nodes in a net are connected by Edges

ClassProperty PROPS

definition of all mandatory properties of a node

ClassMethod new() → $core

constructor for a node object

ObjectMethod finish()

called when this object is destroyed

ObjectMethod addIncomingEdge($edge)

register an incoming edge for this node

ObjectMethod addOutgoingEdge($edge)

register an outgoing edge from this node

ObjectMethod getOutgoingEdges() → @edges

get the list of outgoing edges from this node

ObjectMethod getIncomingEdges() → @edges

get the list of incoming edges to this node

ObjectMethod isApprovalNode → $boolean

returns true if this is an approval node

ObjectMethod getNextNodes() → @nodes

get the list of nodes of outging edges from this node

ObjectMethod getPreviousNodes() → @nodes

get the list of nodes of incoming edges to this node

ObjectMethod getACL($type) → @list

get the access control list to control the given type of action

ObjectMethod hasViewAccess($user) → $boolean

returns true when the given user has got view access to this node

ObjectMethod hasEditAccess($user) → $boolean

returns true when the given user has got edit access to this node

ObjectMethod render($format, $params) → $string

render this node given the specified format string params is a hash reference with default values for properties not defined

internal package Foswiki::Plugins::QMPlugin::Command

implements a command that is executed while traversing a net

ClassProperty TRACE

boolean toggle to enable debugging of this class

ClassMethod new($handler, $source, $params) → $command

constructor for a command object

ObjectMethod getSource()

simple getter

ObjectMethod getParams()

simple getter

ObjectMethod finish()

ObjectMethod execute($state)

handle and destroy

ObjectMethod handle($state)

execute the command

internal package Foswiki::Plugins::QMPlugin::Review

a Review is part of a State and records the review in progress

ClassProperty TRACE

boolean toggle to enable debugging of this class

ClassProperty PROPS

definition of all mandatory properties of an object of its kind; node, edge and role classes each refine this list

ClassMethod new($web, $topic, $rev, $meta) → $state

constructor for a state object

ObjectMethod finish()

called when this object is destroyed

ObjectMethod getState() → $state

get the state this review is part of

ObjectMethod store($meta)

store the review object into a QMREVIEW meta data record

ObjectMethod props() → @props

get a list of all known Review properties

ObjectMethod prop($key, $val) → $val

getter/setter for a property of this class

ObjectMethod index() → $index

get the unique index of this object in a set of same objects part of a state

ObjectMethod render($format, $params) → $string

render the properties of this object given the specified format string params is a hash reference with default values for properties not defined

ObjectMethod expandValue($val) → $val

expand the given value in the context of a state this object is in

ObjectMethod stringify() → $string

returns a string representation of this object

internal package Foswiki::Plugins::QMPlugin::Role

implements a role concept for workflows

ClassProperty PROPS

definition of all mandatory properties of a class of its kind; node, edge and role classes each refine this list

ClassMethod new() → $core

constructor for a role object

ObjectMethod render($format, $params) → $string

render this node given the specified format string params is a hash reference with default values for properties not defined

ObjectMethod isMember($idOrUser) → $boolean

returns true if $idOrUser (default current user) is member of this role

ObjectMethod getMembers($expand) → @members

returns the list of members that have this role assigned

ObjectMethod getEmails() → @emails

returns the list of emails of this role. this is either the list of users as per "notify" property or of all members otherwise.

internal package Foswiki::Plugins::QMPlugin::Utils is a Exporter

This package exports a few operations on topics and attachments to ease copying, moving and trashing them with ease. All functions operate on Foswiki::Meta objects.

StaticMethod trashTopic($meta)

moves a topic object to the trash web. see also Foswiki::UI::Rename

StaticMethod trashAttachments($meta)

moves all attachments of a topic objects to the trash. see also Foswiki::UI::Rename

StaticMethod trashAttachment($from, $attachment)

move a single attachment to the trash

StaticMethod copyAttachments($from, $to)

moves all attachments from one topic to another.

StaticMethod copyAttachment($from, $attachment, $to)

move a single attachment from one topic to another.

StaticMethod copyTopic($from, $to)

copies the one topic to another. Note that this function only copies over the top revision of the source topic, not the entire history. It thereby creates a new revision at the target topic. Attachments are copied over as well. However attachments that don't exist at the source topic anymore are removed from the target topic.

StaticMethod moveTopic($from, $to)

this function copies the source topic to the target and then deletes the source topic afterwards.

StaticMethod renameTopic($from, $to)

rename/moves topic from one location to another. Note that $to can either be a Foswiki::Meta object or a topic name

ObjectMethod expandAUTOINC($web, $topic) → $topic

from Foswiki::Meta