Milos Prudek’s Workflow article in ZopeMag issue 6 does a great job of explaining states and transitions and how you can create your own workflow or enhance existing ones. But there is more to workflows than states and transitions.

The standard Plone workflows (Folder Workflow Plone and Default Workflow Plone) as well as the other available types of workflow definitions (DC Workflow, CMF Default Classic, CMF Default Revision 2) except for 'Simple Review / Publish Policy', all allow through-the-web configuration. Using the respective tabs inside a workflow, you can define worklists, variables and scripts.

Figure 1 - The tabs of the workflow 'plone_workflow', incl. 'Variables', 'Worklists', and 'Scripts'

Workflow variables allow you to store information regarding objects that are subject to your workflow - for example, who submitted an object and when. In the default workflow, data such as the action performed, who performed it and when, as well as any comments the user made, can be shown on the advanced form for changing the state (see figure below).

Figure 2 - Information concerning the actions performed on an object'

For this list to appear on the advanced form for changing an object's state ('content_status_history' in portal_skins/plone_forms), go to the 'Variables' tab of the workflow 'plone_workflow', click on the variable 'review_history' and activate the checkbox 'Make available to catalog' (see figure below). This allows access to an object's review history. You may have to change an object's state after activating this checkbox before you see the review history because the variable's value is updated in the catalog only when a transition occurs - only then will it contain an actual value.

This is necessary for satisfying the condition used in the advanced form (above). If the variable 'review_history' is empty, the condition check fails and the table with the information is not shown.

Figure 3 - The variable 'review_history' of the workflow 'plone_workflow'

The figure above shows the various properties of a workflow variable. The checkbox 'Store in workflow status' enables you to call this variable when listing the information concerning an object. When a transition is made, the value for this variable is stored and can then be accessed. The following shows a sample review history (three entries, with the first one being the creation of the object), stored as a list of dictionaries:

You can see that for each action performed on the object there is a dictionary containing various key-value pairs. Each key-value pair consists of the variable name as a key and its value at the time the action was performed. The variables entered into the dictionary are only those whose 'Store in workflow status' checkbox has been activated.

You need to be careful with deactivating the checkbox 'Store in workflow status' for any variable (at least in the default workflows). Once a transition has been made and the review history has been updated (this time without, for example, the variable 'action' of the default workflow because it has been deactivated), the advanced form for changing the status will raise an error. It is trying to access the value of the variable 'action', but for one transition entry there is no 'action' defined. This may even break your PloneSite's homepage because the review box tries to access the variable as well.

You may choose to update a variable's value either on every transition or only when the transition or state define a new value for it. You may also set a default value or expression. Further, using the 'Info Guard' information, you can restrict access to the variable by permission role or expression.

Figure 4 -Excerpt from the variables defined in the default workflow 'plone_workflow'

If you’ve worked with Plone, you have probably noticed that when an object such as a Document or a News item is submitted it enters the state 'pending' and that, depending on the user you are logged in as, a box appears on the right side of the PloneSites' homepage called 'review list'. This box, which shows all pending objects, contains what is called a "worklist". A worklist is basically a search result. In the default Plone workflow, the review list appears if there are pending objects and the currently logged-in user has the permission 'Review portal content'. The following image shows the properties of this worklist.

Figure 5 - Default worklist 'reviewer_queue' of the workflow 'plone_workflow'

The variables that are listed under 'Cataloged variable matches (formatted)' are the ones you have defined in your workflow and for which you have activated the checkbox 'Make available to catalog', as well as the state variable (here: review_state). As mentioned above, a worklist is a search result. You can see this in the field 'URL (formatted)' under the category 'Display in actions box'. This category consists of three fields: the URL that delivers the search result, the name for the link created by the URL and a category (here: global). These three fields supply the necessary data to create a link in a user's 'actions' box. You can use the following variables inside the 'Name' and 'URL' fields:

• portal_url
• folder_url
• content_url
• user_id
• count

Using the fields 'Permission(s)', 'Role(s)' and 'Expression' under the 'Guard' category, you can restrict the users permitted access to this worklist, assuring, for example, that only reviewers see the review box.

Sometimes you may need to perform extra checks before a transition occurs or you may need to set variables afterwards. You can easily do this by integrating scripts into your workflow. Go to the 'Scripts' tab of the workflow you want to define the script for. There you can create Python scripts, DTML Methods or any other Zope object you might need. For example, let's create a DTML Method that sends an email to a specific reviewer email address when an object has been submitted.

Create a DTML Method called 'notifyMe' in the 'Scripts' view and enter the following code:

This DTML Method uses the sendmail-tag to send an email to 'reviewer@mycompany.com' with the subject 'Pending Object' and just one line in the body of the email: 'There is a new pending object'. The SMTP host is directly entered as an attribute in the sendmail-tag.

If you prefer, you can use the following Python script instead to achieve the same end:

This script checks first for a MailHost object and uses that to send the email, or raises an error if there is no MailHost. Then the variables needed for send() method are defined.

Once you've created a script in your workflow definition, it will appear in the drop-down lists 'Script (before)' and 'Script (after)' of a transition. The scripts above are defined for use when an object enters the state 'pending' and should therefore be executed after the transition 'submit' has been made.

Figure 6 - Selecting the script 'notifyMe' as the script to be executed after the transition is made

Go to the 'Transitions' view and click on the transition 'submit'. Then select the script 'notifyMe' from the drop-down list 'Script (after)'.

Figure 7 - The transition 'submit' with the script 'notifyMe' as the 'Script (after)'

Now, when an object using this workflow definition (here: Plone_workflow) is submitted and the transition has been made, an email is sent automatically to the email address 'reviewer@mycompany.com'.

As mentioned above, you can break your PloneSite pages if you are not careful with the variable definitions. So you need to spend some time before actually creating the workflow in defining as best as you can what you want your workflow to contain.

I hope this article, which is an addendum to Milos Prudek's, will help you in creating your own complex workflows.

I'd like to thank Kamal Gill of UC Davis for providing the basis for the Python script for sending an email.

Some documentation concerning methods can be found in the 'doc' directory of the product directory 'DCWorkflow'.