CPSWorkflow<br/>How to set up workflows using CPSWorkflow <br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>Date<br/><br/>15/06/2005<br/><br/>Version<br/><br/>0.1<br/><br/>Authors<br/><br/>Anahide TCHERTCHIAN, software developer &lt;at@nuxeo.com&gt; Florent Guillaume &lt;fg@nuxeo.com&gt;<br/><br/>Contributors Julien Anguenot &lt;ja@nuxeo.com&gt; Summary This is a technical document describing how to setup workflows using CPSWorkflow. Nuxeo<br/><br/>Company<br/><br/>Email<br/><br/>contact@nuxeo.com<br/><br/>Web<br/><br/>http://www.nuxeo.com<br/><br/>Rights<br/><br/>Copyright © 2005 Nuxeo This book is free. You may use the information in this book for any purpose, commercial or otherwise, without fee or obligation of any kind. Furthermore, permission is granted to copy, distribute, and/or modify this book under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation (http://www.gnu.org/copyleft/fdl.html); with Front Cover Text «CPSWorkflow HowTo», with Back Cover Text « You have the right to copy and/or modify this book, like for all free software and free documentation produced by the Nuxeo company » and with Invariant Section « Links, references and contacts ».<br/><br/>Licence<br/><br/>Nuxeo © 2005<br/><br/>2/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>Table of Contents<br/>1 Introduction.....................................................................................................................................5 2 Workflow concepts.........................................................................................................................6<br/>What is a workflow?.....................................................................................................................................6 The CPSWorkflow concept..........................................................................................................................6 Workflow Items............................................................................................................................................6<br/>Workflow definition..................................................................................................................................................7 States.......................................................................................................................................................................7 Transitions...............................................................................................................................................................7 Variables..................................................................................................................................................................8 Scripts......................................................................................................................................................................8 Stacks......................................................................................................................................................................9<br/><br/>Placeful workflow configuration...................................................................................................................9<br/><br/>3 Workflow sample..........................................................................................................................10<br/>Introduction to a publication workflow.......................................................................................................10 Basic publication workflow.........................................................................................................................11<br/>Creating a new workflow in the Zope Management Interface (ZMI).....................................................................11 Adding states.........................................................................................................................................................13 Adding transitions..................................................................................................................................................13<br/><br/>Templates and scripts................................................................................................................................16 Complete workflow with collaborative validation.......................................................................................17<br/>Introduction to the collaborative process..............................................................................................................17 Adding a local role.................................................................................................................................................18 Adding a stack definition to a state.......................................................................................................................18 Adding transitions to manipulate the stack...........................................................................................................20<br/><br/>Using the newly created workflow.............................................................................................................23<br/>Create a new portal type or use an existing one..................................................................................................23 Set up the appropriate workflow chain in sections................................................................................................23 Try out the new workflow.......................................................................................................................................23<br/><br/>4 Appendix......................................................................................................................................25<br/>Workflow tool..............................................................................................................................................25 Workflow definition.....................................................................................................................................25<br/>Workflow installer..................................................................................................................................................25 Placeful workflow configuration.............................................................................................................................25<br/><br/>State definition...........................................................................................................................................26<br/>State behaviours....................................................................................................................................................26<br/><br/>Transition definition....................................................................................................................................26<br/>Transition behaviours............................................................................................................................................26<br/><br/>Workflow expressions................................................................................................................................27<br/>The available namespace.....................................................................................................................................27 The state change object........................................................................................................................................27<br/><br/>Stacks related definitions...........................................................................................................................28<br/>Stack definition......................................................................................................................................................28 Stack......................................................................................................................................................................28 Stack element........................................................................................................................................................29<br/><br/>Defining new stacks...................................................................................................................................29<br/>Stack definition registry.........................................................................................................................................29 Stack registry.........................................................................................................................................................29 Stack element registry...........................................................................................................................................30<br/><br/>Nuxeo © 2005<br/><br/>3/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>5 Links, references and contacts....................................................................................................31<br/>About CPS.................................................................................................................................................31 About Nuxeo..............................................................................................................................................31 About Zope.................................................................................................................................................31<br/><br/>Nuxeo © 2005<br/><br/>4/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>1 Introduction<br/>The purpose of this documentation is to explain how to setup workflows using CPSWorkflow. CPSWorkflow is an extension of the DCWorkflow product, providing some additional features that will be explained in this document. CPSWorkflow is a CPS core component that can be used as well within a CMF or CMFPlone instance, even if some features are not available outside of CPS. Concepts and terms used about workflows will be presented in the first chapter, and a sample workflow will be detailed in the second chapter. The appendix gives additional technical information about workflows implementation. This documentation comes with a Zope product called CPSWorkflowHowTo, available at: http://svn.nuxeo.org/trac/pub/browser/CPSWorkflowHowTo<br/><br/>Nuxeo © 2005<br/><br/>5/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>2 Workflow concepts<br/>What is a workflow?<br/>A workflow is useful to manage business processes: it allows to define and follow the flow of actions performed by users or other entities. This is a generic definition. When applied to content management applications, other words can light up this definition: a document follows a process, users perform actions they are authorized to perform on this document, and all these actions are tracked in the document workflow history.<br/><br/>The CPSWorkflow concept<br/>The CPSWorkflow product follows the DCWorkflow assumptions:  workflows are assigned to document types, not to some given documents. In CPSWorkflow, local workflow chains are placeful.  a single document in the system represents the process followed.  workflow actors are identified by the roles/permissions they owe. These assumptions put constraints on the way workflows can be defined and customized, even if you can sometimes circumvent these rules. Every document in CPS workspaces and sections follows a workflow, except configuration files. Workflows control all the operations of a site, and all the security checks.<br/><br/>Workflow Items<br/>Workflows are mainly defined by their states and transitions. From this point of view, they can be seen as a deterministic finite-state automata. A document moves from a state to another executing transitions. Some transitions do not have any initial state (initial transitions), they are used at creation time. Some transitions do not have any destination state, they are used as &quot;remain in state&quot; transitions: when executed, the document remains in the state it was already in. Several transitions can have the same initial state, and several transitions can also have the same destination state. By convention, state names are nouns, and transition names are verbs. The set of states and transitions is usually used to represent the document life cycle. Other items, variables, are used to keep track of additional information, like the date and the actor of the last transition. Furthermore, some scripts can be executed just before or after a transition to perform additional actions. Finally, stacks holding users/groups can be defined on states, and manipulated through workflow transitions, allowing to set local roles dynamically on the document. The following sections give an overview about each of these items.<br/><br/>Nuxeo © 2005<br/><br/>6/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>Workflow definition<br/>A workflow is mainly characterized by its set of states and transitions, its variables, and the list of permissions managed. Scripts are involved in transitions, and stacks are involved in states and transitions, so they will be introduced later on. Worklists and groups are DCWorkflow features that are not used in CPS workflows even if they are fully functional.<br/><br/>States<br/>States are mainly defined by the list of transitions that can be performed when the document is in that state, and a mapping of permissions to roles for that state. This is static information: when the document is in that state, the given configuration will apply. For instance, if the &quot;View&quot; permission is only mapped to the &quot;Manager&quot; role, only users who are managers will be able to see the document. The state can only define mappings for permissions controlled by the workflow, and defined at the workflow level. The state does not handle permissions/roles applying to its transitions, it only gives the list of transitions that make sense from that state. Each transition will then control who can perform it. Additional information about variables, and groups can be given. Variables are defined at the workflow level, but when moving to a given state, they can be updated using a particular value. Groups are not used in CPS workflows. Stack definitions and state behaviours referring to stacks can also be set up on a state. This will be detailed in the stacks section.<br/><br/>Transitions<br/>Transitions are mainly defined by their destination state, the transition type, and the guard used to filter users that will be able to perform the transition. Workflow scripts can be executed just before or after the transition, and an associated action to display on the site is also defined on the transition. Variables are defined at the workflow level, but when performing a given transition, they can be updated using a particular value. Additional features are provided with CPSWorkflow transition flags.<br/><br/>The destination state is either one of the states of the workflow, either a loop over the state (&quot;remain in state&quot; transition). In the second case, the same transition can be used on different states. More generally, it is possible to reuse the same transition on different parts of the workflow, since the source state is not defined in the transition but managed by the state.<br/><br/>Nuxeo © 2005<br/><br/>7/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>The default transition type is &quot;Initiated by user action&quot;: the transition execution is requested by the user, usually via a script in skins. Other options are &quot;Automatic&quot; and &quot;Initiated by Workflow Method&quot;. The former is executed when a document moves to a state listing that automatic transition. The latter is never used in CPS workflows. The guard used to control in what situation the transition can be executed is a set of properties: permissions, roles, groups and a TALES expression can be used. In CPS workflows, roles are usually defined and groups are never used. These properties complete each other: for instance, if a transition guard sets roles and an expression, user will have to meet the two conditions to be able to perform the transition. Workflow scripts can be executed just before or after the transition. Most of the time, they are used to perform specific actions that cannot be taken by transitions with special flags. An optional action associated to the transition can be defined. Sometimes we do not want to display any message in an action box to make the transition possible, but most of the time we do. The action name, URL and category can then be defined. The action will not be displayed in the actions box if the transition guard fails for the authenticated user. Transition flags have three major purposes:  Find special transitions: for instance it is helpful to look for transitions flagged as initial transitions, to know if a document with a given type can be created.  Control subobjects allowed behaviours: a container is responsible of globally allowing certain behaviours for its subobjects. This covers creation, deletion, moving into the container, etc... Once a container allows certain operation, the workflow for the portal type itself will have to allow the operation too.  Perform specific actions while executing the transition, for instance: freeze or delete the document, add users to a given stack, etc...<br/><br/>Variables<br/>Variables are used to store information related to the workflow but that do not justify a state. Workflows usually use variables to store status history details (last transition performed, person who performed it and when, attached comments, etc...). Variables are defined thanks to their default expression, the way they're updated, access guards... Most of workflows will not need to change variables defined in default CPS workflows. Please note that stacks are stored as workflow variables: when a stack definition is added to a state, the corresponding variable is created.<br/><br/>Scripts<br/>Scripts are useful to perform miscellaneous actions extending the workflow features. They are usually used in transitions, as before/after actions to be executed, and take an object called state_change as first parameter. state_change keeps information about the object current status and can also be used in transitions and stack guard expressions.<br/><br/>Nuxeo © 2005<br/><br/>8/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>Stacks<br/>Stacks can be seen as high-level variables. Stacks can store any kind of objects, but we usually use them to store members or groups since their main purpose is to provide dynamic, workflow-driven local roles distribution on the document. Imagine you would like to involve a set of users in a document process, controlling the permissions according to the document state, and other users actions/duties on the document. Stacks allow you to set local roles dynamically, using a set of parameters as: the document state, the document itself, the user's location in the stack, etc... Two basic kind of stacks are implemented in CPSWorkflow, but it is easy to define new kinds of stacks. These basic stacks are a simple stack, and a hierarchical stack. A simple stack is a list while a hierarchical stack has a level notion to take care of the hierarchy between users/groups held in the stack. The stack definition is given at the state level, it is used when creating and manipulating the actual stack object, by providing high-level accessors or mutators on it. The state allows the existence and manipulation of a stack, and defines what actions can be performed on a given stack (for instance: add users, remove users, reset the stack, change the current level in the case of a hierarchical stack,...). Transitions are also involved because actions on stacks can only be performed executing transitions that allow them. A different definition of a stack can be given for another state of the workflow. A state can hold several stacks, and can make the distinction between actions that are allowed for a given stack, and forbidden for others. A transition can also make the difference between several stacks, allowing to add users only to a given stack, for instance.<br/><br/>Placeful workflow configuration<br/>Workflow configuration is placeful in CPS: we can decide that for a given subtree, a given portal type will follow a given workflow. A placeful (local) workflow is used for instance to have a subtree dedicated to public content where objects must pass through a reviewing process (sections), and another subtree where the objects can be created and worked upon easily by the members (workspaces).<br/><br/>Nuxeo © 2005<br/><br/>9/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>3 Workflow sample<br/>Maybe you would appreciate a workflow sample to light up all these definitions. Default CPS workflows already give examples of complex publication processes. We will create a new workflow, adapting the default publication workflow, and turning it into a collaborative validation workflow. You can follow the steps involved in the creation of this workflow in the following sections, or install the CPSWorkflowHowTo product, execute its installer, and look at the workflow definition while reading the documentation. You can also take example on this product to see how to create properly new workflows.<br/><br/>Introduction to a publication workflow<br/>Defining a workflow always starts by drawing a picture. Here is the picture of our simple workflow, representing its states and transitions.<br/><br/>Let's describe this workflow usage from a CPS point of view. This is a publication workflow, happening in sections in CPS. The document exists, it has been created in a workspace and follows a workspaces specific workflow. When trying to publish the document, a new document (actually, a new revision of the document) is created in a selected section. This document follows a sections specific workflow. If the authenticated user has enough rights in the given section to publish the document, it is directly published. If he/she does not have enough rights, the new document moves to a pending state, where it will be approved or rejected by reviewers who have sufficient rights in the section to do so. Let's describe it from a more technical point of view. Two states and five transitions are involved in this process. The pending state (&quot;Waiting for reviewer&quot;) and the published state (&quot;Public&quot;) can be accessed via different transitions. The &quot;None&quot; state represented in a circle is not a real state, it is here to represent the virtual source state of initial transitions. There are two initial transitions, &quot;Member request publishing&quot; and &quot;Member publishes directly&quot;. There is one transition to move from the pending state to the published state (&quot;Reviewer accepts publishing&quot;) and two &quot;remain in state&quot; transitions, when validation fails or<br/><br/>Nuxeo © 2005<br/><br/>10/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>when publication is cancelled: &quot;Reviewer rejects publishing&quot; and &quot;Reviewer removes content from publication&quot;. This is a simple workflow, although there are things to understand that do not appear clearly on the graph:  When the new document is created, it is created from another existing document, following another workflow in workspaces.  When publication is rejected, or when document is unpublished, document is actually deleted. Usually, you would define only one initial transition, flagged as an initial transition for creation of the document. When invoking the creation of the document, the workflow tool is queried and finds out what transition applies by looking for workflow(s) defined for the given document type in the given place (remember workflows are placeful) and looking for initial transitions for creation in the found workflow(s) ­ usually only one workflow, and only one initial transition for creation apply. Here we have two initial transitions, leading to two different states. They're not initial transitions for creation, but initial transitions for publication. The right transition will be executed according to the user's rights in the chosen section. It is possible to submit the document for publication because it follows a workspaces specific workflow that allows object &quot;cloning&quot; into other folders.<br/><br/>Basic publication workflow<br/>Creating a new workflow in the Zope Management Interface (ZMI)<br/>The easiest way to start defining this workflow is to copy/paste an existing workflow, so that variables are already set (standard variables will be used in this workflow). In the ZMI, go to portal_workflow, and click on the &quot;Contents&quot; tab to display the list of existing workflows. Our workflow is very similar to &quot;section_content_wf&quot;, so you can copy/paste it and rename it &quot;cps_validation_wf&quot;. Click on this new workflow, you will see a page looking like this:<br/><br/>Nuxeo © 2005<br/><br/>11/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>The &quot;States&quot; tab will display the available states in that workflow. You can click on it and delete all the states, we will recreate new ones later. You can do the same with transitions. Variables have to be kept, and we do not need any scripts neither. The permissions tab tells that four permissions are managed by this workflow: &quot;Modify portal content&quot;, &quot;View&quot;, &quot;WebDAV Lock items&quot; and &quot;WebDAV Unlock items&quot;. You can delete WebDAV related permissions because we will not deal with them in the new workflow. Here is the list of existing variables, visible in the &quot;Variables&quot; tab:<br/><br/>All these variables are standard ones ; you can click on each of them to get more details about the way they are updated, for instance. You can see that most of involved expressions use the state_change object. This object is created when changing the document status, and stores information about changes in progress. You can see that comments and destination container are information passed as keywords when executing the transition. Let's add the missing states and transitions to this workflow.<br/><br/>Nuxeo © 2005<br/><br/>12/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>Adding states<br/>Go to the &quot;States&quot; tab, and add new states with ids &quot;pending&quot; and &quot;published&quot;:<br/><br/>Click on the &quot;pending&quot; state, and add a title like &quot;Waiting for reviewer&quot;. It is not possible to set transitions available from this state for the time being, because no transitions have been defined for this workflow yet (well, if you did delete them after copying). In the permissions tab, you will see the two permissions managed by the workflow. By default, permissions are inherited. We will define specific permissions for our pending state: unselect the permissions acquisition, and associate permissions to the following roles:  View: Manager, SectionManager, SectionReviewer  Modify portal content: Manager, SectionManager, SectionReviewer The role SectionReader is not involved here because we do not want section readers to see or edit documents that have not been validated by section reviewers. Click on the &quot;published&quot; state, and add a title like &quot;Public&quot;. In the permissions tab, unselect the permissions acquisition, and associate them to roles as described below:  View: Manager, SectionManager, SectionReviewer, SectionReader  Modify portal content: Manager So section readers will be able to see published documents, and nobody's supposed to edit them: only a Manager of the site can modify them, but this is just a &quot;rescue&quot; permission setting.<br/><br/>Adding transitions<br/>Now that states have been created, let's add the missing transitions. Go back to the workflow definition, and click on the &quot;Transitions&quot; tab.<br/><br/>Nuxeo © 2005<br/><br/>13/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>Add a transition with id &quot;publish&quot;, and then click on it. You can then set its title to &quot;Member publishes directly&quot;, select the &quot;published&quot; state as destination state and keep the &quot;initiated by user action&quot; transition type set by default. Only the roles property of the transition guard will be used ; set it to &quot;Manager; SectionManager; SectionReviewer&quot;: only people having one of these roles in the given section will be able to publish directly. Some transition flags are needed too: select &quot;Initial transition for publishing&quot;, &quot;Freeze object&quot; and &quot;Merge object with existing in same state&quot;. &quot;Initial transition for publishing&quot; will be helpful when looking for available transitions on submit. &quot;Freeze object&quot; and &quot;Merge object with existing in same state&quot; are needed to handle revisions of the document. Some knowledge about proxies and document repository is needed to understand what actually happens. The submission process consists of freezing the current revision of the document and creating a proxy to that revision in the section. Freezing the submitted revision is needed to ensure the submitted/published document could not be modified afterwards. If the working document happens to be modified, a new revision to work on will be automatically created. In other kinds of workflows, this wouldn't be needed.  &quot;Freeze object&quot; freezes the revision as well as all the revisions pointed by the proxy (but usually only one revision is involved). This means that the document revision will not be modifiable again, and ensures that this revision is marked as to be lazily copied for any future modification. For instance, if the working copy in workspaces is modified, a new revision is created, and the published revision is not modified.  &quot;Merge object with existing in same state&quot; is used so that there is only one published revision of a document. If the working copy of the document is edited (thus creating a new revision) and re-submitted, the published revision and the pending (newly created) revision are merged into the already-published proxy. A list of transition flags is given in the appendix, please refer to it to know what flags are needed and when.<br/><br/>Add the &quot;submit&quot; transition, with title &quot;Member requests publishing&quot; and destination state &quot;pending&quot;. The guard role will be &quot;Manager; Member&quot; for this one, since everybody can submit a document in a section. NB: the list of sections where a document can be submitted is filtered so that user only sees sections where he/she has local roles (at least SectionReader): the situation where a document is submitted in an unreachable section will not happen in practice. Transition flags needed here are only &quot;Initial transition for publishing&quot; and &quot;Freeze object&quot;. The &quot;accept&quot; transition takes &quot;Reviewer accepts publishing&quot; as title, &quot;published&quot; as destination state, &quot;Manager; SectionManager; SectionReviewer&quot; as guard roles, and the transition flag &quot;Merge object with existing in same state&quot;. This transition will display an action in the actions box, with name &quot;action_accept&quot;, URL &quot;%(content_url)s/content_accept_form&quot; and category &quot;workflow&quot;. We will talk about templates involved in workflows in the next section.<br/><br/>Nuxeo © 2005<br/><br/>14/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>The &quot;reject&quot; transition takes &quot;Reviewer rejects publishing&quot; as title, does not have any destination state (this is a &quot;remain in state&quot; transition), &quot;Manager; SectionManager; SectionReviewer&quot; as guard roles, and the transition flag &quot;Delete object&quot;: this revision of the document will be deleted if publication is rejected. The action displayed in the actions box is named &quot;action_reject&quot;, its URL is &quot;%(content_url)s/content_reject_form&quot; and its category &quot;workflow&quot;. The &quot;unpublish&quot; transition takes &quot;Reviewer removes content from publication&quot; as title, does not have any destination state (this is a &quot;remain in state&quot; transition), &quot;Manager; SectionManager; SectionReviewer&quot; as guard roles, and the transition flag &quot;Delete object&quot;: this revision of the document will be deleted if publication is undone. The action displayed in the actions box is named &quot;action_un_publish&quot;, its URL is &quot;%(content_url)s/content_unpublish_form&quot; and its category &quot;workflow&quot;.<br/><br/>When all these transitions are created and configured, you should have the following transitions in your workflow:<br/><br/>Now that transitions have been created, it is possible to configure possible transitions in the states: select &quot;accept&quot; and &quot;reject&quot; for the &quot;pending&quot; state, and the &quot;unpublish&quot; transition for the &quot;published&quot; state.<br/>Nuxeo © 2005 15/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>This new workflow is in fact very similar to the default &quot;section_content_wf&quot; workflow, but with fewer features: in particular, everything related to subobjects behaviours has been cleared out. It is fully functional because it reuses existing scripts and templates, already set up for CPS default workflows.<br/><br/>Templates and scripts<br/>Let's have a look at the user-visible part of a workflow. While everything that is accepted by the workflow has been configured, it is time to take care of what users attempt to do. The workflow is invoked when creating documents and when executing transitions. The creation process can be seen as a special transition to execute since special queries are made to the workflow tool. These queries are made via ZPT templates and Python scripts. Please note that the scripts we are talking about in this section are skin scripts, not workflow scripts. There is usually no reason to change the way documents are created: the workflow tool is queried to get the list of creatable items in a given place of the site and detects if workflow followed by these content types has a transition flagged as an initial transition for creation. This transition is executed while invoking the document creation. Some transitions do not have any action to display in the actions box. This is true for initial transitions, but also for transitions allowing special behaviours, like subobjects behaviours: the workflow tool will ensure that a transition allows this behaviour before performing it. Transitions with actions in the action box are meant to be invoked by users. User clicks on the action in it actions box, a page is presented, giving some information, and asking for other information needed to perform the transition (typically, the actual transition to perform, comments attached to the state change, section(s) chosen for submission,...). Then user submits the form, and transition is executed in the script that is called. Note that if an action does not appear in the users actions box but if the user can see the document, it is still possible to display the transition form by typing it in the URL. But when submitting the form, the workflow will check that the user can perform the transition, and raise an exception if not. Although various templates are used in default CPS workflows, most of transitions are executed using the script: CPSDefault/skins/cps_default/content_status_modify.py. The important line in this script is:<br/>wftool.doActionFor(context, workflow_action, **kw)<br/><br/>The workflow tool is asked to perform the &quot;workflow_action&quot; transition on the &quot;context&quot; object, using miscellaneous keywords (comments or relative path towards the submission section for instance).<br/><br/>Nuxeo © 2005<br/><br/>16/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>While executing this action, security checks will be performed, and before/after workflow scripts defined for this transition will also be executed. Any other automatic transition defined for the new state will be executed too. This script is the action given in all the forms we used to define the new workflow (content_accept_for, content_reject_form, etc...). The addition of the collaborative validation process in this workflow will lead us to define new scripts to perform some new transitions.<br/><br/>Complete workflow with collaborative validation<br/>Introduction to the collaborative process<br/>Let's spice up the reviewing process involving a collaborative validation process when document is in the pending state. When a document is submitted for publication, a section manager or a section reviewer decides not to accept or reject the document, but to make it go through a collaborative validation process: users/groups are added to a hierarchical stack, giving local roles dynamically.  Section managers and section reviewers can still accept or reject publication.  Users and/or groups at current level of the stack can:  reject publication  add/remove users and groups to the stack  change the current level by moving it down or up  Users and/or groups on top of the stack can accept publication if this level is also the current level.  Section managers, section reviewers and users in the stack can still view and edit the document while it's in the pending state. Here is the graph corresponding to this process:<br/><br/>Nuxeo © 2005<br/><br/>17/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>There are three new transitions: &quot;Manage delegatees&quot; is used to add or remove users to the stack; &quot;Move up delegatees&quot; is used to move up the stack current level, and &quot;Move down delegatees&quot; is used to move it down. Users in the stack will be assigned a local role. This role has to be different from the existing ones so that we can set up permissions properly: while section reviewers can view, edit and accept/reject publication, we would like to have an intermediate role between reviewer and reader, so that users in the stack can view and edit the document, but not always accept or reject publication.<br/><br/>Adding a local role<br/>Let's add a new local role to the portal, it will be used in the workflow definition. In the ZMI, go to the CPS root and click on the &quot;Security&quot; tab. Then click on the &quot;Manage permissions&quot; link on this page, and scroll down to the end of the page. You will have a form saying &quot;User defined role&quot;: type &quot;SectionIntermediateReviewer&quot; and add it.<br/><br/>Adding a stack definition to a state<br/>The stack we would like to use is a basic hierarchical stack, and we would like to use it in the pending state. Let's add the corresponding stack definition to the pending state: in the ZMI, come back to your workflow and go to the &quot;pending&quot; state. Click on the &quot;Workflow stacks&quot; tab, and add a hierarchical stack definition, with a hierarchical stack; type &quot;Reviewers&quot; for the stack definition name, it will be used to create the corresponding workflow variable.<br/><br/>Here is the variable that has been added to your workflow variables:<br/><br/>Nuxeo © 2005<br/><br/>18/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>Once the stack definition has been added, in the previous &quot;Workflow stacks&quot; tab, you can click on it to configure it. We are going to set the empty stack guard, to tell who can manage the stack when it's empty: set the roles to &quot;Manager; SectionManager; SectionReviewer&quot;. Section intermediate reviewers will not be able to initiate a collaborative validation process.<br/><br/>NB: &quot;Manage the stack&quot; means add, delete users/groups to the stack, and change the stack current level. Then set the dynamic roles configuration by adding the two roles that are managed by this stack:  SectionReviewer: we will set this role to users/groups on top of the stack. The corresponding expression is &quot;python:stack.getAllLevels() and level == stack.getAllLevels()[1] and level == stack.getCurrentLevel()&quot;. The stack has levels, its last level has to be the level where the stack element is, and it has to be the current level too.  SectionIntermediateReviewer: this role will be given to other users/groups in the stack. The corresponding guard expression is: &quot;python:stack.getAllLevels() and level &lt; stack.getAllLevels()[-1] or level != stack.getCurrentLevel()&quot;. Here is a screen shot of the configuration page:<br/><br/>Nuxeo © 2005<br/><br/>19/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>The stack definition is configured. Let's add permission mappings for the SectionIntermediateReviewer role in the pending state. Go back to the state definition, and click on the &quot;Permissions&quot; tab. Now that the new role has been declared in the portal, it's available in the list of existing roles. Select it for both permissions, &quot;Modify portal content&quot; and &quot;View&quot;: intermediate reviewers will now be able to edit and view the document. Now let's configure the state so that it allows different operations on the stack. Come back to the state configuration, and select the following state behaviour flags, always indicating the workflow variable &quot;Reviewers&quot;:  Push delegatees, on workflow variable &quot;Reviewers&quot;  Pop delegatees, on workflow variables &quot;Reviewers&quot;  Increase workflow level, on workflow variables &quot;Reviewers&quot;  Decrease workflow level, on workflow variables &quot;Reviewers&quot; These operations are now allowed if document is in the pending state. We are going to add transitions that will allow to execute the corresponding operations on the stack.<br/><br/>Adding transitions to manipulate the stack<br/>Go back to the workflow definition, and click on the &quot;Transitions&quot; tab. Add a transition with id &quot;manage_delegatees&quot;, and then click on it. You can then set its title to &quot;Manage delegatees&quot;, set it as a &quot;Remain in state&quot; transition, and keep the &quot;initiated by user action&quot; transition type set by default.<br/><br/>Nuxeo © 2005<br/><br/>20/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>Only the roles property of the transition guard will be used ; set it to &quot;Manager; SectionManager; SectionReviewer; SectionIntermediateReviewer&quot;. Some workflow stack transition flags are needed: select &quot;Push delegatees, on workflow variable&quot;, and fill the form with &quot;Reviewers&quot;, and select &quot;Pop delegatees, on workflow variables&quot;, and fill the form with &quot;Reviewers&quot;. These flags tell that this transition will be used to add/remove users/groups to the stack. This transition will also display an action in the actions box: set the action name to &quot;manage_delegatees&quot;, the URL to &quot;%(content_url)s/content_manage_delegatees_form&quot;, and the category to &quot;workflow&quot;. &quot;content_manage_delegatees_form&quot; is a new template that you can find in the CPSWorkflowHowTo product. Note that the guard of this transition also takes care of the stack guard: if the stack definition says that the authenticated user cannot manage the stack (because he/she's not at current level, for instance), executing this transition will not be possible.<br/><br/>Now lets add the two transitions that will be used to change the current level. Add a transition with id &quot;move_up_delegatees&quot;, set its title to &quot;Move up delegatees&quot;, and set it as a &quot;Remain in state&quot; transition. The transition guard roles have to be set to &quot;Manager; SectionManager; SectionReviewer; SectionIntermediateReviewer&quot;. Select the workflow stack transition behaviour &quot;Increase workflow level, on workflow variables&quot; and specify the workflow variable &quot;Reviewers&quot;. Set the action name to &quot;move_up_delegatees&quot;, and its URL to &quot;%(content_url)s/content_move_up_delegatees_form?current_var_id=Reviewers&quot;. &quot;content_move_up_delegatees_form&quot; is also a new template in the CPSWorkflowHowTo product. Variable is passed as a parameter because templates are as generic as possible, and we could imagine another stack definition exists in the same state: we have to specify on which stack the current level has to be moved. The last transition is quite similar: you can set the same configuration for the transition with id &quot;move_down_delegatees&quot;, turning every &quot;up&quot; word with &quot;down&quot; :) The transition flag to select is &quot;Decrease the workflow level, on workflow variable&quot; this time. Note that, whatever the transition guard says, the action to move up or move down the current level will not be displayed if it's not possible to do so (if level above current level is empty, for instance).<br/><br/>Now you can come back to the pending state configuration, and select the three new transitions as possible transitions:<br/><br/>Nuxeo © 2005<br/><br/>21/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>Note that templates used in these new transitions do not call the &quot;content_status_modify&quot; script to execute the transition, because special keywords have to be sent as parameters of the doActionFor method: information about the stack workflow variable involved, about the chosen level, chosen delegatees, etc... There is one detail missing: right now, only users with local role &quot;Manager&quot;, &quot;SectionManager&quot; or &quot;SectionReviewer&quot; can reject the document. We would like to let users/groups at current level take care of a rejection (e.g., users with role &quot;SectionIntermediateReviewer&quot; who are at current level in the stack). So we are going to add the SectionIntermediateReviewer role in the &quot;reject&quot; transition guard roles, and set the following expression in the guard expression: &quot;python:user.has_role(('Manager', 'SectionManager', 'SectionReviewer'), here) or user.has_role(('SectionIntermediateReviewer',), here) and here.portal_workflow.canManageStack(here, 'Reviewers')&quot;. Remember that the guard fails if guard roles fails OR if guard expression fails. This expression means that users with roles SectionIntermediateReviewer will be able to reject the document only if they can manage the stack, as a basic hierarchical stack is configured to allow only users at current level to do it.<br/><br/>Nuxeo © 2005<br/><br/>22/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>Using the newly created workflow<br/>Create a new portal type or use an existing one<br/>Now the workflow has been configured. I recommend you run the CPSWorkflowHowTo installer if you want a new document type, Schedule, to be created and installed. This document type will be used to test the new workflow, and it has a special layout so that the stack is displayed on its view page. Note that changes you would have made to the new workflow will be erased when launching the installer. If you want to test you workflow on an existing document type, without having to run the product installer, you can set up workflow chain configurations as described below. Note that you will still need to get and register in skins the CPSWorkflowHowTo product skin files.<br/><br/>Set up the appropriate workflow chain in sections<br/>CPS workflows are placeful: it is possible to indicate that a given portal type follows different workflows according to its location on the site. We usually make a distinction between CPS sections and workspaces: a workflow chains configuration file exists in both roots. In the ZMI, go to the sections folder, and click on the &quot;cps_configuration&quot; file: here you can change the mapping between allowed portal types and the workflow they have to follow in sections. If you have executed the CPSWorkflowHowTo installer, the Schedule portal type should be mapped to the &quot;cps_validation_wf&quot; workflow.<br/><br/>Try out the new workflow<br/>The Schedule document type has to be created in workspaces. When document is waiting for reviewers approval, a reviewer can manage delegatees to set up a collaborative validation process. Here is a screen shot presenting how delegatees can be assigned to the workflow:<br/><br/>Nuxeo © 2005<br/><br/>23/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>The Schedule document presents users/groups who are in the stack. You can see that the authenticated user, &quot;Test2&quot;, can manage delegatees and change the current level, reject the document publication, but cannot accept it. If current level is moved to the top level, then the user called &quot;test&quot; will be able to accept publication. Here Test2 and the group called SpecialGroup are at current level:<br/><br/>Nuxeo © 2005<br/><br/>24/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>4 Appendix<br/>This appendix gives technical details about workflow configuration and implementation. This is subject to changes and might not be kept up to date very quickly<br/><br/>Workflow tool<br/>The workflow tool is used to manage workflow related operations. There are two main methods that are invoked via user interface code:  doActionFor: this methods executes a workflow action (transition) on the given document.<br/>doActionFor(self, ob, action, wf_id=None, *args, **kw)<br/><br/>Sample code to execute a transition:<br/>context.portal_workflow.doActionFor(context, 'accept', comments=&quot;this doc rocks&quot;)<br/><br/> getInfoFor: this method returns a given workflow-specific property for an object. It is<br/><br/>usually used to get information about some workflow variable.<br/>getInfoFor(self, ob, name, default=_marker, wf_id=None, *args, **kw)<br/><br/>Sample code to get the document current state:<br/>context.portal_workflow.getInfoFor(context, 'review_state', None)<br/><br/>Workflow definition<br/>Workflow installer<br/>CPSInstaller has workflow related methods used to setup new workflows.<br/>verifyWfStates(self, workflow, states) verifyWfTransitions(self, workflow, transitions) verifyWfScripts(self, workflow, scripts) verifyWfVariables(self, workflow, variables, state_var=None) verifyWorkflow(self, wfvariables={}) wfdef={}, wfstates={}, wftransitions={}, wfscripts={},<br/><br/>Sample usage is given in the CPSWorkflowHowTo product installer.<br/><br/>Placeful workflow configuration<br/>To create a placeful workflow configuration, a 'CPS Workflow Configuration' object must be created in the ZMI. It's then possible to define for each portal type what workflow it has to follow.<br/><br/>Nuxeo © 2005<br/><br/>25/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>When a workflow is configured in a folder, it applies to the folder itself and all its subobjects, recursively. Sometimes we want to configure a workflow for all the subobjects of a folder but not for the folder itself. This can be done using a &quot;Below workflow chain&quot;. The corresponding CPSInstaller method is:<br/>verifyLocalWorkflowChains(self, object, wfchains, destructive=0, under_sub_add=None)<br/><br/>Sample code to setup a mapping in sections:<br/>self.verifyLocalWorkflowChains(self.portal.sections,{'Section': 'section_folder_wf'})<br/><br/>State definition<br/>State behaviours<br/>Existing state behaviours are related to stacks management:  Push delegatees: allow pushing elements in given stacks in that state  Pop delegatees: allow popping elements from given stacks in that state  Increase workflow level: allow moving up the current level for given stacks (only useful for hierarchical-like stacks) in that state  Decrease workflow level: allow moving down the current level for given stacks (only useful for hierarchical-like stacks) in that state  Reset workflow: allow emptying given stacks in that state<br/><br/>Transition definition<br/>Transition behaviours<br/>A number of transition flags have been added to DCWorkflow. These flags govern some special CPS behaviours for the transition. They can be subdivided in several categories.<br/><br/>Allowing subobject behaviour<br/>A container has responsibility for globally allowing certain behaviours for its subobjects. This covers creation, deletion, moving into the container, copying into the container, publishing into the container, checkout into the container. Once a container allows certain operation, the workflow for the portal type itself will have to allow the operation too. Some of these behaviours are checked by the manage_CPScopyObjects, manage_CPScutObjects and manage_CPSpasteObjects methods.<br/><br/>Initial transitions<br/>An initial transition is a transition followed when an object is created (or published, checked out, etc.) in a container. It does not have an initial state, but the destination state is the one the object will have after creation. When asking for the creation portal types,<br/><br/>Nuxeo © 2005<br/><br/>26/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>only those that have a suitable initial transition will be allowed. The standard &quot;initial state&quot; of DCWorkflow is not used. &quot;Transition for checkin&quot; is logically grouped together with those. It's a transition an object will follow when it is on the receiving end of a checkin (i.e., when it is the reference object into which a modification is checked back in).<br/><br/>Specific behaviours<br/> &quot;Freeze object&quot; is used by all transitions going to a state where the object should not    <br/><br/>be modified anymore. &quot;Publishing, with initial transitions&quot; is used as a mechanism for publishing an object into another container. &quot;Checkout, with initial transitions&quot; is used to checkout an object into another containe r. &quot;Checkin, with allowed transitions&quot; is used to checkin an object back into its original version. &quot;Merge object with existing in same state&quot; is used when in the destination state there should be only one docid in a state, e.g. only one published revision while several ones are pending.<br/><br/>Stacks related behaviours<br/> Push delegatees: allow pushing elements in given stacks executing this transition  Pop delegatees: allow popping elements from given stacks executing this transition  Increase workflow level: allow moving up the current level for given stacks (only use-<br/><br/>ful for hierarchical-like stacks) executing this transition  Decrease workflow level: allow moving down the current level for given stacks (only useful for hierarchical-like stacks) executing this transition  Reset workflow: allow emptying given stacks executing this transition Note that some of these behaviours are incompatible: for instance, if a transition is flagged with both behaviours &quot;increase workflow level&quot; and &quot;decrease workflow level&quot; on the same workflow variable, executing this transition will have no effect on the stack current level.<br/><br/>Workflow expressions<br/>Workflow expressions are used in transition guards and in stack definition guards. TODO: make the difference between DCWorkflow/CMFCore definitions and CPSWorkflow ones (some guards have been redefined to provide an extended namespace)<br/><br/>The available namespace<br/>TODO<br/><br/>The state change object<br/>TODO<br/><br/>Nuxeo © 2005<br/><br/>27/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>Stacks related definitions<br/>Stack definition<br/>A stack definition is an object stored within a state definition object implementing an abstraction layer on a stack object instance. It holds the basic configuration for a stack. A stack definition is defined by:  the stack type the stack definition will be able to manage  the id of the workflow variable where the stack instance will be stored  the managed roles, e.g. roles that the stack definition can cope with. Roles have an associated tales expression evaluated within the stack definition context, defining the policy for the given role. A stack definition:  defines high level accessors and mutators on the stack object.  defines the policy of roles distributions for the stack elements stored within the stack using managed roles expressions. It includes as well a specific guard while the stack object doesn't contain elements yet.  defines the default policy for viewing and editing stack elements using guards. (note that a stack element do have its own guard that may override the default behaviour from the stack definition). It may be used as well without any roles policy if the purpose of the stack is not to distribute local roles (for instance: adding a stack of tasks hooked on a given state). It is possible to know if a stack can be managed by the authenticated user by querying the workflow tool:<br/>context.portal_workflow.canManageStack(context, 'Reviewers')<br/><br/>Stack<br/>A stack is the actual object storing elements. A stack has a render method linked to a given template in skins ; it is used to represent the stack in different situations (view, edit, insert,...)<br/>stack.render(context, mode='view')<br/><br/>A stack knows how to construct a stack element checking the element prefix. A stack can be accessed asking the corresponding workflow variable to the workflow tool.<br/><br/>Nuxeo © 2005<br/><br/>28/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/>stack = context.portal_workflow.getInfoFor(context, 'Reviewers', None)<br/><br/>Stack element<br/>A stack element is stored within a stack. For instance, users and groups added to a stack are instances of different stack element types (user stack element and group stack element). A stack element is mainly defined by the prefix used to identify the element type (prefixes for basic stack elements are 'user' and 'group'). A stack element has its own guard that may override the default behaviour from the stack definition. If a stack element is protected, the stack will turn it into an instance of a corresponding hidden stack element type, defining what information is available.<br/><br/>Defining new stacks<br/>A system of registries is available to let you register your own stack definition, stack and stack element types. You need to implement the corresponding interfaces.<br/><br/>Stack definition registry<br/>To be able to register your own class within the WorkflowStackDefRegistry you need to subclass the bare definition or subclass one of the basic definitions, and implement the IWorkflowStackDefinition interface. You may use it like this:<br/>from Products.CPSWorkflow.stackregistries import WorkflowStackDefRegsitry from Products.CPSWorkflow.stackdefinition import StackDefinition<br/><br/>class MyStackDefinition(StackDefinition): # Here implementation .... WorkflowStackDefRegistry.register(MyStackDefinition)<br/><br/>Stack registry<br/>To be able to register your own class within the WorkflowStackRegistry you need to subclass the bare stack class or subclass one of the basic stacks, and implement the IWorkflowStack interface. You may use it like this:<br/><br/>Nuxeo © 2005<br/><br/>29/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/>from Products.CPSWorkflow.stackregistries import WorkflowStackRegistry from Products.CPSWorkflow.basicstacks import HierarchicalStack<br/><br/>class MyHierarchicalStack(HierarchicalStack): # Here implementation<br/><br/>WorkflowStackRegistry.register(MyHierarchicalStack)<br/><br/>Stack element registry<br/>To be able to register your own class within the WorkflowStackElementRegistry you need to subclass the base stack element class or subclass one of the basic stack elements, and implement the IStackElement interface. You may use it like this:<br/>from Products.CPSWorkflow.stackregistries import WorkflowStackElementRegistry from Products.CPSWorkflow.stackelement import StackElement<br/><br/>class MyUserStackElement(StackElement): meta_type = 'My Stack Element' prefix = 'my_user' # Here implementation<br/><br/>WorkflowStackElementRegistry.register(MyStackElement)<br/><br/>Do not forget to use a new prefix, so that the stack element type to use is detected properly when inserting a new element in the stack.<br/><br/>Nuxeo © 2005<br/><br/>30/31<br/><br/><br/>CPSWorkflow HowTo CPSWorkflowHowTo.sxw<br/><br/>5 Links, references and contacts<br/>About CPS<br/> Community site: CPS Project  User guide (currently only in French): CPS User guide  Developer guide (currently only in French): CPS 3 Book  HowTo « develop for CPS 3 » (currently only in French): HowTo CPS3  Development API: CPS 3 API  SVN repository (source code and bug tracker): http://svn.nuxeo.org  Mailing-lists:  French speaking users: cps-users-fr  English speaking users: cps-users  Development (English only): cps-devel<br/><br/>About Nuxeo<br/>Nuxeo is the European leader of services surrounding the open source platform Zope. Nuxeo develops and markets collaborative web content management systems, as well as associated services such as training, consulting and hosting. Nuxeo's customers have at their disposal a highly competent team with high technical qualifications and who use the best of free software. Nuxeo supports the open source software effort by publishing software components under a free license (GPL) and by contributing as a core developer to the development of the Zope platform. Nuxeo supports the action of the EuroLinux Alliance in favour of software innovation and free software, and against software patents, harmful for competition and innovation. Links:  Commercial web site: www.nuxeo.com/en  Email: contact@nuxeo.com<br/><br/>About Zope<br/> Community site: zope.org  Development recipes: Zope Labs<br/><br/>Nuxeo © 2005<br/><br/>31/31