Illustration by Lia Avant

Plone Workflow

To quote the Plone Book, “Workflow is the process used to manage objects in a website. An example is a company's press release: an employee writes a press release and submits it to an editor for review before it is published on the website. This review process is called a workflow and is used by site managers to ensure that site content is correct.”

Technically, workflow is a set of states and transitions between the states. However, we will start our explanation with types. Plone supports various types out of the box, such as Discussion Item, Document or Event. There may be any number of instances of each Plone type, with each instance being in a different workflow state. You can have a Document instance called docA in the state visible, and another Document instance docB in the state published.

To go from state to state, instances must pass through transitions. A custom, fixed set of possible states, transitions, permissions and other data is called a workflow. Plone can have a different workflow for each type.

If your head is spinning, here's some relief: The default Plone installation specifies two workflows only: folder_workflow is used for Folders and Topics, and plone_workflow is used for everything else. You can certainly develop an unlimited number of additional workflows , but in this article we will play with plone_workflow only (and use it for the type Document). We will now give a short descritpion of the structure of the default Plone workflow plone_workflow.

Above I said that instances can be in different states. There are four default states: pending, private, published and visible. This set of states allows the basic workflow arrangement:

• Registered (non-anonymous) users (i.e. a user registered in Plone) can create new instances (documents, discussions etc.).
• These new instances are automatically created in the visible state.
• The instance creator (owner) can then Submit the document, i.e. change its state to pending, or Make the instance private, i.e. change its state to private (only the instance owner and Managers can see instances in the private state).
• Registered users without additional roles can Retract (move back to the visible state) or Make Private their pending documents (i.e., change them to the private state).

Figure 1 - Owner Transitions

The diagram above shows transitions that a user can carry out with his own documents based on the permissions defined for the role Owner.

The name of the transition can be different from the destination state of the transition. Transition history may add another name as well. For example, the Make private transition is displayed as hide in the transition history, and Make visible is displayed as show. Later on you will see that hide/show are transition ids, while Make private/Make visible are transition names.

A user with the role Reviewer can reject or publish submitted instances. Reject brings the instance back to the visible state, and is in essence the same as the Retract action by the instance owner.

After rejecting a document, the reviewer can still choose to Publish the document – and that is all he is entitled to do. The owner can, on the other hand, do more things with a rejected document: he can Submit it and Make it private. See the diagram below:

Figure 2 - Reviewer Transitions

From Private, there is only one path for any user: Make visible.

A Reviewer can Submit, Make private and Publish his own material (note that Submit means that the submitted document appears in a to-do list (Review List) for all reviewers, i.e. it is submitted to the Reviewer role, not to any particular reviewer; any reviewer, including the submitter himself if he is a reviewer, can select it and decide its fate). If he submits it, he has an even wider choice: Reject, Publish, Make Private and Retract. Note again that Retract and Reject are essentially the same thing. If a reviewer has published an instance, the only action that the owner can carry out is Retract. See the diagram below. A retracted document goes back to the Visible state. Visible is the default state of newly created documents (or more generally, instances). What “Visible” means in a given workflow is user definable. By default, Visible documents do not appear in directory listings, but they can be found via the Search function. Even anonymous users can find them in this way. In other words, default Visible means a document is “not secret, can be located, but is not advertised.”

Figure 3 - Reviewer Transitions for his instances

This default workflow works reasonably well under many circumstances. One of Plone's strengths, however, is its ability to add new workflow states and transitions. We will illustrate this by adding two new states: confidential and restricted. Instances in the confidential state are for management only – only the management can see them – while the restricted state will be assigned to internal company documents (instances) and only employees will be able to see them. Only restricted documents may become confidential, and only the company management may change the state from confidential to restricted. Restricted documents may be brought to the pending state by the management and reviewers only.

To separately control permissions for these states, new roles must be added in Plone. We will create an Employee role (for restricted documents) and the Boss role (for confidential documents).

A side note: In a large company, the task of deciding which restricted documents may be published could be assigned to a specialized security clerk; in this case you would have added a new role for this employee, let's say seclerk. He would then be responsible for this transition and the permission to carry out this transition would be removed from the boss role.

Although it is technically possible to change a document state from restricted to confidential, in practice it is rarely useful; once the document has circulated within the company the cat is out of the bag... The management is not allowed to make any other state changes. Their task is simply to keep their Plone interface clean and to maintain the hierarchical chain of command: they can order a reviewer to carry out any other transition for them.

Start with a default Zope installation and Plone 1.0.5. Add a new Plone site. Let's call the Plone site simply company. Choose “Create a new user folder in the portal” as your Membership source. The site type should be Default Plone.

Return to your ZMI and go to company/manage. Enter the Security tab, and add two new roles: Boss and Employee. Now we will start modifying our workflow. Open the portal_workflow tool. A list of Plone types will be displayed. Note that most items use a (Default) workflow, and that this default workflow is specified at the bottom of this list as plone_workflow. This is our target. Before you start modifying it, enter the Contents tab in portal_workflow and create a backup copy of the plone_workflow. Then enter plone_workflow and go to the States tab. You'll get a list of currently defined states; below each state there is a list of permitted transitions. We will need to create two new states (confidential and restricted) and three new transitions.

All subsequent modifications will be carried out from the relative address company/manage (http:// localhost:8080/company/manage in absolute terms if you run your Zope on localhost:8080).

If you click on any of the four default states in your plone_workflow, you will discover that a state does not have too many properties. Each state has a Title, Description and, most importantly, a set of allowed transitions. These are the default transitions for default states:

Figure - States Defaults

It's patently clear that you can only define the first part of our security model here: you may define that a confidential state may go to the restricted state, and the restricted state may go to confidential and pending, but you cannot specify here who is allowed to perform these transitions and who is not. You can, however, define who can see each state: if you open any state, the Permissions tab allows you to set four different permissions for each role. Plone allows you to add other permissions to this set of “managed permissions” (this expression is defined below) or to delete permissions, if you want.

If you need to define both new states and new transitions, as we indeed do, you face a small chicken-and-egg problem. States contain allowed transitions, so it looks like you should define transitions first. But each transition must define a destination state. Here's how to resolve this problem:

First we define our two new states, with ids confidential and restricted, in the States tab. Inside each state specify some useful Title and Description, but do not touch the list of permitted transitions. Both of the new states will be listed with a remark No transactions for the time being. In the following section you'll learn how you can define new transitions and all their properties, including a destination state. This is done in the Transition tab. Having done that, you will then be able to go back to the States tab and define the transitions allowed for each state. This resolves our chicken-and-egg problem.

Now let's take a closer look at the Transitions tab. It contains a list of default transitions: hide, publish, reject, retract, show and submit. To get an idea of their structure, open all of them in separate browser windows (better yet, in separate browser tabs). If you cycle through them, you'll see that they are very similar: a destination state is defined, and an action form is referenced. Guards (permissions and roles) limit who can carry out a given transition, even if permitted otherwise. Regardless of what other permissions a role might have, the Guards take precendence (see the Permissions for States section below). If you are curious, you can look up the action forms with the ZMI find function. No black magic, just an intertwined network of settings. Create a new transition with id confidential. In the confidential transition, make the Destination state confidential, put Boss; Reviewer in the Guard: Roles box, write “%(content_url)s/content_confidential_form” into the URL (formatted) box (this will be explained below), and write CONFIDENTIAL in the Name(formatted) box .

Great! You just created a transition that will allow the Boss and Reviewer role to move documents to the confidential state. But what about the restricted state? Documents should be able to reach the restricted state via two paths: from the less restrictive states (pending and perhaps published), and from the more restricted confidential state. The former path should be available to Reviewers, but the latter one should be limited to Bosses only. This means that we will need two new transitions:

Create two new transitions, hide_from_public and open_to_company, and fill them out according to the table below, which also contains an overview of the confidential state:

The two forms referenced in the the URL (formatted) box will be defined in the following section. To apply your permission changes, you must go to the Workflow tab of portal_workflow and click on the Update security settings button.

Now you should define the two forms referenced in the new transitions. The portal_skins/content folder contains plenty of forms. The content_publish_form reflects our needs best. This is determined by inspecting the source of various forms in portal_skins/content. The change to confidential and restricted requires the same form values as publishing. Choose it and click the Customize button. Then back up into portal_skins/custom, rename the content_publish_form to content_confidential_form and make a copy named content_restricted_form. The only line that must be adjusted is the <input type="hidden" name="workflow_action" value="publish"> line. Please enter “confidential” and “restricted” in the value field, respectively. It is wise, in addition, to change the form text to reflect the purpose of these new forms: heading, description and the submit button text.

Permissions for States are controlled via portal_workflow/<workflow_id>/states/ in the Permissions tab, where is plone_workflow in our case. As in Zope, roles are used to group permissions. You assign the permissions each role is to have. In addition to default Zope roles you can add your own roles. Roles are added via the standard Zope User Folder in the Plone instance.

Only a limited set of Permissions, called “managed permissions”. appears here. A developer determines which permissions become the managed permissions by selecting them from all Zope permissions. Zope with Plone has well over 100 different permissions. Usually, only a few need to be managed by a workflow. They are called “the managed permissions”. By default, the following four managed permissions are defined: Access contents information, Change portal events, Modify portal content and View. The set of managed permissions is defined via portal_workflow/ <workflow_id> in the Permissions tab. You won't change this set in the present article, because it is not necessary for achieving our goal.

Now it's time to define which roles can see which states. In the portal_workflow/plone_workflow, re-enter the confidential state, and enter the Permissions tab. Uncheck Acquire permission settings? for all, and check Access contents information and View for Boss, and check all permissions for Manager. Then enter the restricted state, uncheck Acquire permission settings? for all, and check Access contents information and View for Boss, Employee, and Reviewer, and check all permissions for Manager.

Finally, you'll define which transitions are permitted for each state. First re-enter the confidential state and check the open_to_company transition. This will be the only way out of the confidential state, and we limited it to the Boss role only in the previous section. Then enter the restricted state, and check the confidential, submit and publish transitions. Now we need to modify at least one of the default states, from which selected roles should be able to make documents confidential or restricted. Choose the visible state and add hide_from_public and confidential transitions to it. Then do the same with the pending and published states, so that privileged users (defined in the transition Guards as described above) can carry out these transitions when they work on pending documents.

At the end of your labors you should get the following screen:

Figure - States Defaults

To apply your permission changes, you must again go to the Workflow tab of portal_workflow and click on the Update security settings button.

Let us take a look at the resulting workflow and consider the decisions we have made and their implications. Confidential documents can only go to the restricted state. They cannot be directly published to anonymous users. Documents in the restricted state can of course be made confidential, but not by all employees; this prevents possible practical jokes by irresponsible employees. The reverse process, publishing, is achieved via the submit transition. Documents going from restricted to published will therefore appear in the pending list of your reviewers. We could design this workflow with slightly different privileges and it would still be a confidential/restricted scheme. Decisions that we have taken simply reflect our current view of our hypothetical company's management, and as such may change in the future.

Define the following users:

Be sure to define these users from inside Plone, not directly from the ZMI. This will ensure that each user has a default home folder in Plone. Once this is done, go to the ZMI and set the roles as listed above.

Log in as user anne and create two documents: docA and docB. Submit docA for review, but leave docB alone. Switch to the Contents view and verify that docA is in the pending state and docB in the default visible state.

Log out, and log in as Cindy, our reviewer. Document docA appears in Cindy's Review list in the right slot. Click on it and then click the state tab. You should see Reject, Publish, Hide from public and CONFIDENTIAL as allowed transitions. The figures below show how the Name (formatted) field with CONFIDENTIAL in capital letters in the ZMI corresponds to the presentation seen by users.

Figure - States Name 1

Figure - States Name 2

Also note the access URL:

/	Members/anne/docA/portal_form/content_status_history 

and save it in your browser's bookmarks. What about docB? Although it is not pending and therefore does not appear in the Review slot, you can display it by directly manipulating the URL above: simply go to

	/Members/anne/docB/portal_form/content_status_history

and note that there are three transitions available: publish, hide from public and CONFIDENTIAL. Of course, Cindy must know that docB exists if she is supposed to change it to the restricted state. She can learn about this easily, without having to question any other user. Here's how: In Cindy's personal bar there is a pending tab. Click on it; although you will only get pending documents (docA), take note of the URL:

/search?review_state=pending

If you simply change this URL to:

	/search?review_state=visible

you immediately learn about docB in Anne's home folder, and you can change its state from there. If you expect that reviewers will often be asked to make visible documents restricted, you should put this URL somewhere in Plone where only users with the role 'reviewer' can see it. This is very easy to do but beyond the scope of the present article.

Log out, and log in as Drew. Let's make use of your bookmarks. Access

	/Members/anne/docA/portal_form/content_status_history

Ooops. You get the error report Could not get info: review_history. This is simply because Drew has the Boss and Member roles, but not the Reviewer role. There are various solutions to allow Drew to access this option:

• You can change the permission for all Bosses at the same time. Simply go to the Plone root in the ZMI and check Review portal content for the Boss role.
• You can fix this for Drew alone by granting her the Reviewer role.

There are potential drawbacks for both these solutions: Bosses will get the above-mentioned pending documents slot on their home page, and they may not like it. To disable this slot for the Boss role, go to

	/portal_skins/plone_templates/ui_slots/

open the workflow_review_slot and click on Customize. Locate the line beginning with

	<div metal:define-macro="review_box"

and change the original content:

	tal:condition="results">

into the much more elaborate:

	tal:condition="python:test(results and not ('Boss' in 
	user.getRoles()),1,0)">

That's it. You have created a brand new workflow that is very practical.

To create a new workflow:

• Create a diagram (with pen and paper)
• Define roles and transitions
• Create forms referenced in new transitions
• Test, test, test!

While the above article was tested with Plone 1.0.5, the upcoming Plone 2.0 introduces virtually no changes in the workflow machinery.

Milos Prudek: Milos Prudek has been working professionally in the IT industry since 1988. While working as an application programmer with FoxPro and Pascal, he also taught a wide range of IT subjects to different audiences. A freelance developer and writer since 1991, he established a local ISP company, which he has since expanded. He has been active in Zope development since 1998 and runs a small Web usability and Web development company Spox Design. His only passion is promoting tolerance among people.