(C) Tony Jensen and Jørn Lind-Nielsen 2003-2004
The online Encyclopedia "Wikipedia" describes a workflow like this:
Workflow is the operational aspect of a work procedure: how tasks are structured, who performs them, what their relative order is, how they are synchronized, how information flows to support the tasks and how tasks are being tracked. [WikiPedia www.wikipedia.org]
In Pagesetter we can control where in the workflow a publication is located, what kind of actions you can perform on it, when it can be done, and who can do it. The location is defined by the publication's state, which for instance can be "Preview" for something in preview for an editor. The state is something visible and can always be seen on the editor's list. The actions can be things like "Submit", "Accept", or "Reject", all of which triggers some code that modifies the publication. A publication can only change state as a result of a workflow action. You never edit the state directly.
Each of the workflows may have some configuration settings that can be set through the menu Configuration::Workflow. The standard settings are things related to notification mails to be sent when a publication changes state during the workflow. The most obvious of these are the mail addresses of the editors and moderators that should be informed of new content arrivals.
The workflow system has been designed to let the administrator add his own workflow without modifying the existing ones. This is done through an XML file in the "workflows/custom" directory.
Remember that, no matter how clever a workflow you might create, everything begins and ends with your editors. The workflow in it self is only a technology, it is not and will never be a substitute for good writers.
This will answer the question "How do I get my existing Publication Types working with Workflow?". The reason for this is that every publication type now needs a workflow attached to it. If it does not, you will receive an error.
In the pagesetter/workflows directory, there are two subdirectories. Each of these have the same structure.
The standard directory contains workflow information that comes standard with Pagesetter. The custom directory contains workflow information that you create. Because the Pagesetter workflows are stored in a different directory than what you develop, you will never have to worry about an upgrade to Pagesetter overwriting your workflow information.In the root of the directories are the xml files that define each workflow. Under that is an operations subdirectory. This directory contains one file for each operation that can be used in a workflow action.
Old revisions of a publication is stored in the depot. This revision control means you can always go back and view the content of an earlier version of a publication. Deleted publications are actually not deleted, but marked deleted and then moved to the depot.
If you really want to delete a document then you can do that while browsing the history of a publication, assuming you have admin access.
The state of a publication marks the location of it in the workflow process (or rather—the state machine that the workflow is based upon.
Actions are business functions like Submit, Approve, Reject, and Delete. They are verbs that can perform operations as well as move a document from one state to another. Actions are composed of operations.
If Actions are business functions then Operations are technical functions.
An operation is a unit of work. Examples are: sending an email, deleting a document (moving it to the depot), creating a new revision, update publication.
Operations are individual PHP files that represent one task. Any number of these Operations can be used to perform an Action.
Operations are called from Actions and can be passed parameters if necessary.
This section describes the XML elements used in a workflow definition. This definition will reside in an XML file in the workflows/custom directory.
A short title for the workflow. This will be used in drop-down selection boxes. It will probably be a capitalized version of the xml filename.
A detailed description of what the workflow is and what it does. It should explain under what circumstances someone would want to use this workflow.
Any information required within this workflow. You will need to define this information for each publication type that uses this workflow. Examples of configuration settings are notification email addresses. The configuration tag includes any number of setting tags. The setting tags are defined with an id, title, type, width and height. The possible values for the type are "bool", "int", "real", "string", "text" (long string), "html" (long string with editor), "date", and "time".
A list of all possible states in this workflow. A state is defined with an id attribute and the following children.
A list of all actions that are possible in each state of the workflow. An action is defined with an id attribute and the following children.
A boolean expression (predicate) that must evaluate to true in order to enable the action. You can refer to the lowest Pagesetter permission that is required in order to perform the action ("author", "editor", or "moderator"), and you can refer to the predicate "owner" which is true or false depending on whether or not the current user owns the pubication.
A simple permission could be <permission>editor</permission> whereas a more advanced one could be <permission>(author and owner) or editor</permission>. The last one is used in the MyWiki workflow and states that you must either have at least "editor" access or have author access and be the owner of the publication.
It is possible to combine permission requirements with the usual boolean connectors "and" and "or", use "!" for negation, and group expressions with parenthes.
Workflow operations are the technical bits of the workflow actions. In the workflow specification file actions refers to various opearations to get things done. An action like "approve" may for instance refer to the operations createNewRevision and mailToAuthor. Each of these individual operations matches precisely one PHP file in the operations directory. The PHP operation file is included and after that an interface function in that file is called by Pagesetter. If the operation is named createNewRevision then the PHP file must be named the same—createNewRevision.php and contain the function pagesetter_operation_createNewRevision.
The interface function is passed a reference to the publication user data, a reference to some core data, and the arguments (attributes) of the XML operation element in the workflow specification.
As an example we can take a look at the mailNewContentMessage operation:
function pagesetter_operation_mailNewContentMessage(&$publication, $core, $args) { // Standard PN-API call that creates a URL to the publication $editURL = pnModUrl('pagesetter', 'user', 'pubedit', array('tid' => $core['tid'], 'id' => $core['id'], 'action' => 'edit')); // Similar URL creation $viewURL = pnModUrl('pagesetter', 'user', 'viewpub', array('tid' => $core['tid'], 'pid' => $core['pid'], 'id' => $core['id'])); // Select the arguments specified in the operation tag: // <operation message="..." subject="..." recipient="...">mailNewContentMessage</operation> $message = $args['MESSAGE'] . "\n\nEdit: $editURL\nView: $viewURL"; $subject = $args['SUBJECT']; $mailTo = $args['RECIPIENT']; if (!empty($mailTo)) { $ok = mail($mailTo, $subject, $message); if (!$ok) return pagesetterWarningWorkflow("Mailing new content to '$mailTo' failed."); } return pagesetterWFOperationOk; }
The passed publication object contains the same data as the normal templates, except that core values are referred to as core_xxx instead of core.xxx.
The core object is not exactly the same as the core object used in the templates. For workflows it only contains the tid, pid, id, and creatorId values.
Workflow operations must return one of three values used to inform Pagesetter of the result:
In addition to this the operation can call pagesetterWarningWorkflow as illustrated in the mail example above. This function sets a warning message and returns pagesetterWFOperationWarning. The same goes for a call to pagesetterErrorAPI which sets an error message.