Manage Workflow

Outline:

Definitions and Background

• What workflows to control, and when to use them

• How to change workflows that govern our content

• How to modify an existing workflow to make it meet your needs

• How to create a new workflow to implement collaborative editing

One of Plone's greatest strengths is its advanced workflow system. Workflows control access to and operations on content objects in Plone. You can use workflows to control who can see a page, who can modify an image, who can create an event, and who can see the contents of a given folder.

You can also define review processes for your content objects, giving various groups of users different levels of access to your content objects, depending on where the object is in the review process. For example, using one of Plone's stock workflows, you can require that after a user creates a page, the page is reviewed before it is available to the public.

In this section, we'll teach you the fundamental concepts of Plone's workflows. We'll show you how to change the stock workflows, govern the content types on your site, and also how to modify these workflows to better suit your site's needs.

Background

Let's start with a definition, so that terms used later in the chapter are clear:

A workflow defines states (which are bundles of permissions for each role) for objects of a given content type, and transitions between these states (usually guarded in terms of permissions a user must have to execute those transitions).

Within that definition are several other terms that are important to understand. We'll start with permissions and build from there. Permissions are a low-level concept in Zope that determine whether a user can perform some action (such as View (an object), Modify (attributes of that object), or Add (some piece of content). To get an idea of the permissions available in Plone, head to your site's Site Setup, and then click on Zope Management Interface (known as the ZMI).

Once there, click on the Security tab near the top of the screen to see the lengthy list of permissions.

As you can see in the following screenshot, across the top of the columns, you'll see names such as Manager, Reviewer, and Member. These are the various roles a user might have for a given folder.

Roles

As the security tab implies, a role is a bundle of permissions for a group of users (any user who has that role) in a given context. Out of the box, Plone includes the following roles: Anonymous, Authenticated, Owner, Contributor, Editor, Manager, Member, Reader, and Reviewer. Anonymous, Authenticated, and Owner are slightly unusual, because Plone assigns them automatically; as you might expect, unauthenticated users have the Anonymous role, and logged-in users have the Authenticated role. Note that any permission that anonymous users have, all the other users have as well, even when they're logged-in. Also, a user will have the Owner role for any object that he or she creates.

So, for example, a logged-in user might have the Contributor role on your site, and this gives the user permission to Add events to your site. But that same user might not have the permission to delete any published content in the site.

Why are so few boxes checked explicitly? And what's up with "acquire?"

Zope (and consequently Plone) uses the concept of Acquisition, which can be complicated while programming, but makes security much simpler. With acquisition, a given container or object doesn't need to explicitly define all of the possible permissions for itself. Instead, it only needs to explicitly declare (or have set) the permissions that are important to its own security. Everything else is acquired from the container's context.

So, for example, your folders may not set a specific permission for Modify portal content, but instead can acquire which roles have that permission from the portal's root (your Plone site). This will be useful to keep in mind for later use; a permission you don't explicitly set in your workflow (and some that you do, if you want) will acquire permissions from its context and parents. So if. for some reason, users can cut and paste when you don't think they should, you might want to see which roles have the permission at your portal root, and then control it explicitly in your workflow.

The sheer number of permissions and checkboxes under the security tab can be somewhat overwhelming, and you're right if you feel a little nervous about changing anything here. In fact, changing security settings on the security tabbed page is usually a bad idea; workflow changes will override anything you modify from the security tabbed page, and workflow is a more systematic way to manage security.

In general, the only place where it's an acceptable idea to change security settings is the root of your site. Thankfully, with workflows, you don't have to fool around with the security tabbed page for any individual object—instead, you get to define how the security changes for entire classes of objects in a given state.

States

A state is a set of permissions for each role (on your portal) for a given object. For example, a page in the private state can only be viewed by its owner. The same page, when in the published state, can be viewed by anyone, but can only be edited by a manager. Typical states might include a draft stage, a review stage, a copy editing stage, and a publication stage. In each state, different groups of users might have the right to view, edit, or even delete an object. For example, a group of editors may be the only users who are allowed to edit a page in the copy editing stage, lest some other user introduces errors during that phase. During the draft stage though, all registered users might have access to modify a page, to ease collaboration.

Transitions

States, on their own, are not very useful, though—a page in the draft state needs some way to make it to the published state. Otherwise, the intended audience might never see it. This is where transitions come in. A transition is exactly what you would expect– a way to change the state of an object. Transitions are defined between two states (and yes, loops are possible). Naked transitions could be dangerous though. In our preceding example workflow, it wouldn't exactly be useful if a writer could transition a page out of copy editing. That's really the prerogative of the copy editor.

Thankfully, the authors of Plone's workflow engine realized this and now allow you to set guard roles that specify the roles required to execute a given transition. You are also allowed as many transitions as you want between states, so you could set up a workflow where authors have to send their pages for review, but managers (and only managers) can skip all the in-between states and push a page directly from private to published.

If you're poking around on the workflow tabbed page, you will actually notice several different kinds of transitions and guard options. Plone's workflow engine is incredibly flexible and powerful, and allows for automated transitions guarded by the Python code, which can evaluate complex rules. However, covering these extra features is beyond our discussion here.

Changing your site's workflow

Different types of sites require different types of workflow and access, and Plone makes changing the workflows that govern your content easy. For example, you may have a site that will be used as an Intranet/Extranet. Plone provides a pair of workflows for this case (Intranet/Extranet workflow and Intranet workflow for folders). Thankfully, changing from Simple Publication Workflow to the Intranet Workflow is painless. You can find the workflows (and a bunch of other useful settings) for your site under Site Setup under the Types option, as shown in the following screenshot:

The Type Settings section lists all of your content types, and then the (Default) option. Within Zope/Plone, you can specify a workflow for each content type, or say that the type follows the default. By default, all of your types will use the (Default) setting. You can see this in the ZMI, if you click portal_workflow for your Plone site:

Manage Approvals and Other Workflow for my Content

Out of the box, the default workflow is the simple_publication_workflow, which applies to of all the included content types, except File and Image. As files and images don't have workflows, they acquire all of their permissions from their containers, that is, if the user can access the folder containing an image or a file, the user can also access the image or the file.

To effect our change, we first have to change the (Default) from simple_publications_workflow to Intranet/Extranet workflow. Do this by selecting Intranet/Extranet Workflow from the New workflow drop-down.

This will change the workflow for Pages, Events, Favorites, Folders, Links, News Items, and Collections to the Intranet/Extranet Workflow. Further, notice the State Mapping box—this lets you tell Plone which states in your current workflow correspond to the states in the new workflow. You'll want to make sure that Pending review maps to Pending review, Private to Private, and Published to either Internally published or Externally published (depending on how you think of your existing published content). This will ensure that any content that you have already created on your site ends up in an appropriate state when you change the workflow.

Once you've set up your state mapping, click on Apply Changes. Take a look at the note about the speed of this action and its effect on performance. If you have an administrative (non-public) instance of your site, it would be a good idea to use that version for this sort of thing. If you have a site with lots of existing content, changing the workflow on all of these objects is a long process.

This should take care of most of our objects. However, for this workflow, Folders have their own special workflow that is simple and efficient. So, after you've set a new default, select Folder from the type field's drop-down list at the top of the page. Then, under New workflow, select Intranet Workflow for Folders. The state mapping here is pretty simple, as the Intranet workflow for Folders has only two states—just be sure to map published to Internal draft. How you handle folders that are currently pending review will depend on your specific situation. Once you've made your selections, apply this workflow, and then take a little break while Plone modifies all the folders in your portal.

It's always advisable to back up your site's data.fs file before making a large change of this nature.

Understanding Plone's supplied workflows

Plone ships with a variety of useful "stock" workflows that you can use for your portal, and these workflows even come with useful documentation that explains what they do. To better understand and investigate the descriptions that ship with the workflows, we'll use the ZMI and investigate the Simple Publications Workflow in detail.

To explore the Simple Publication Workflow, we'll need to spend some quality time in the ZMI. You will find the workflows by expanding the [+] sign next to portal_workflows in the left-hand index frame of the ZMI. While you're at it, go ahead and expand the [+] next to simple_publication_workflow too.

In the Types configuration, Plone explains that the simple publications workflow "Things start out as private, and can either be submitted for review or published directly." So, clicking the states link in the ZMI, we should expect to see three states, and indeed, we do:

Note that the private state has an asterisk (*) next to it, which indicates that this is the initial state for this workflow. When a user creates a new object that's governed by this workflow, it will start off in the private state. To learn more, let's click on *private, which brings us to the following screen, which offers a user-friendly description of the state and the possible transitions from the private state (which we'll talk more about later). From this screen, click on permissions, which will show you exactly what private means in terms of permissions by role:

From the preceding screenshot, we can see exactly what the users of a given role can do with an object in this state. For a private object, the object's owner, site managers, and editors can access information about the object (related to viewing the actual object through the web), change the date/time and location information of objects with those attributes (Plone Events in most cases), see the object in folder listings, modify (or edit) the object, and view the object itself.

Contributors and readers can see objects in the private state, but can't edit them (they lack Change portal events and Modify portal content). Remember that any other permission not listed by the workflow is acquired from the object's parent, so that permission for, say, viewing the history for an object governed by this workflow will be governed by the portal's default (only managers have this permission out

of the box). To see what happens when an object changes state, go back to the states overview,

then select published and click on its permissions tab:

This time, anonymous (and thus everyone else), has significantly more access to the object. Because anonymous has Access contents information, List folder contents, and View permissions, any portal user can see this object in folder listings and visit the object through the web. Note that the object's owner, as well as site editors and managers, can still edit the published content. As an exercise, look at the pending state's permissions and see if you can tell what differs there from the permissions of the private and published states.

Now that we understand the states, we need to understand how an object moves between them. Astute readers will remember that transitions change an object's state, and sure enough, there's a transitions link for this workflow. Clicking on this link brings us to a list of the transitions, as well as which states they move an object between:

From the preceding screenshot, you can see most of the options that a user has available to them in order to change the state of a given object. Unfortunately, you cannot see the source-state for a given transition from this screenshot; that is listed on the states screenshot. Using our great memories (or multiple tabs in Firefox), we can figure out the paths, though.

From private, a user with the Request review permission (contributors on an out-of-the-box Plone site) can submit an object to pending. From there, a user with the Review portal content permission can either publish an object (putting it in the published state) or reject it (putting it back in the private state). Users with the Review portal content permission can skip the pending state and directly publish from private. This is useful and convenient for managers who may need to rapidly create and release content objects.

Now that you have understood these ZMI pages, you can fully evaluate Plone's other workflows and understand exactly what they change with each state. The Type Settings page provides useful descriptions of each workflow to save you time and trouble. However, as security in Plone is controlled through workflow, it would be useful to be able to evaluate exactly what a given workflow permits in some level of detail.

Making our own collaboration workflow

Using your understanding of Plone's workflows, it's time to create a new one. Imagine that your site requires a great deal of collaborative authoring by staff (a new role) that needs to be reviewed before it's published. Moreover, after something is published, the regular staff should not be allowed to edit it. Finally, we need a copy editor role and a copy editing state as these pages are written by multiple authors and take some solid editing to make them flow well.

This workflow sounds close to the simple_publication_workflow, but it's slightly different. Let's start by making a copy of the simple_publication_workflow in the ZMI. Visit portal_workflow again, and then select the contents tab.

Select the checkbox next to simple_publication_workflow and then click on Copy. After the page refreshes, click on Paste. You will now have copy_of_simple_ publication_workflow (Simple Publication Workflow), which will be listed at the top of the screen. Select the checkbox next to this, click Rename, and replace the name with practical_collaboration_workflow. After the page refreshes, click on practical_collaboration_workflow, and give it a good title (for example, "Practical Collaboration Workflow") and a short description (such as "Provides a way for contributors to create and collaborate on pages, along with review and copy editing states"). Save your changes. Now let's dig into the roles, states, and transitions.

First, we'll need to add two new roles: Staff and Copy Editor. To add a role, we work in the ZMI. First, go to the root of your site (at the top of the leftmost sidebar, called Plone if you used the unified installer). Then, click on the Security tab. Scroll to the bottom of the page, and enter Staff in the User defined roles box, and then click on Add Role. Do the same for Copy Editor.

Next, the new roles will need permissions. We'll model the Copy Editor along the lines of Plone's built-in Editor type, and Staff on the Contributor type. So, for Copy Editor, ensure that the same checkboxes are selected as for Editor (for example, Access contents information, Manage properties, and so on) and then make sure Staff matches Contributor (for example, ATContentTypes: Add Document, Access contents information, and so on).

Now that we have adequate roles, we can allow any staff to modify a private object. This way, our staff can collaborate on pages without showing them to the public. So, click the States tab, and then the link to the private state. These pages are still private—the public can't see them—so the title is probably ok, although you may need to change the description.

After you've written something useful and pithy, go to permissions. Here, we'll want to give Staff the rights to Change portal events and Modify portal content, as well as the other permissions that allow them to actually see the content. We may want to give Copy Editors the right to view content at this stage too, as staff may have questions for them. So select Access contents information, List folder contents, and View, as shown in the following screenshot. Save your changes, and bask for a moment—you've just modified a workflow:

Moving on, let's do something similar in the Published state—this time though, we need to remove some permissions. Go back to the States, select published, and then select the permissions tab. Deselect the checkboxes for Change portal events and Modify portal content for the Owner role, as shown in the following screenshot and then save your changes:

Now, we just need to add the editorial review state and change some transitions around. We need reviewed pages to go to editorial review, instead of directly to published. Back at the States tabbed page, add a state with the ID editorial_review, which will be added to the list of states.

Now, let's make a transition into the editorial review. Head over to the Transitions screen, and add a transition called submit_to_editor. Select it from the list, and give it a title of "Submit to editor," and a description of "Submits an object for copy editing". For the destination state, select editorial_review, and under Guard we'll try something new—we will require the Reviewer; Manager role. We want reviewers to submit objects for editorial review, as there's no Request editorial review permission supplied with Plone. We add a semicolon and Manager after reviewer, because managers should be able to make any transition. In Name (formatted) add Submit to editor, and in URL (formatted) add %(content_url)s/content_status_ modify?workflow_action=submit_to_editor.

It is the URL that gets called to change the workflow state. The URL uses a simple substitution (the %(content_url)) to get the URL of the current content. Then it appends content_status_modify to it, and then passes the argument of workflow_action=submit_to_editor, which tells Zope to perform the Submit to editor transition.

We also need to make one small modification to an existing transition. Publishing will now require different guards. So, from the transitions list, select the publish transition. Then, in the Guard boxes, remove the Permission(s) and add the Role(s) of Manager; Copy Editor. This will allow managers and copy editors, but not the reviewers, to publish content as we don't want any unedited content going up on the site.

Now that we have our transitions set, we can return to the States tabbed page and set up the states. From the states list, first select pending and deselect publish as a possible transition; replace it with submit_to_editor, as shown in this screenshot:

Save your changes, and then head over to editorial_review. On this screen, give the state a title (Editorial review) and a description (Reviewers submit content for copyediting.). Then, select the retract and publish transitions.

Once you've saved these changes, click on the Permissions tab, and set up some reasonable permissions. First, deselect Acquire permission settings? We want to explicitly set these permissions for the state. Now, give Copy Editor, Editor, and Manager all five permissions. Copy editors and managers should be able to view and modify the content, while the editor is a local role that should be allowed to edit content. For Owner, Staff, Contributor, and Reader, select Access contents information, List folder contents, and View, so that these users can still look at objects in the editorial review without disturbing the editor's work. When you're done, the permissions should appear as follows:

With this last change, you're ready to set this workflow as your portal's default. So, back in Plone, in the Type Settings, select (Default) and set the New Workflow to Practical Collaboration workflow. As most of our states have the same names, it's easy to verify that the mappings are correct. So all that's left to do is to apply the change and wait. And with that, you have a new collaboration workflow:

Summary

• What workflows control, and when to use them

• How to change the workflows that govern our content

• How to modify an existing workflow to make it meet our needs

• How to create a new workflow to implement collaborative editin