Default Workflow

Chapter 3 covered the default workflow and the default settings when publishing content. I discussed the security and settings for each state in the workflow. However, a picture is worth a thousand words, so Figure 8-2 shows the workflow state.

Figure 8-2. The default workflow for content that comes with Plone

Figure 8-2 shows the main states and the transitions. This figure has a gray dotted line that represents a sort of security divider. To the left of the line is where owners of the content usually interact with the content. To the right of the line is where reviewers usually interact with the content.

NOTE The owner of the content is the person who created the content originally. An owner is one particular member of a Plone site. Although many members exist in a Plone site, only one person can be the owner of a piece of content in a Plone site. Because the owner role is calculated when an object is created, the owner role is special.

Just like with the credit card example, an associated set of permissions exists for the default workflow. Table 8-4 outlines all the permissions and the states.

Table 8-4. The Default Workflow Permissions

View refers to the following permissions: Access Contents Information and View

Edit refers to the following permission: Modify Portal Content

As you can see from Table 8-4, by default only when content is in the private state is it truly hidden from everyone else. When content is in the published state, only the manager can edit it. Later in the "Editing Permissions" section, I'll show you how to change these permissions easily through the Web.

Folder Workflow

I also discussed the folder workflow in Chapter 3, when I covered publishing content with you. However, as I noted in that chapter, no pending state exists for folders. Instead, you have a slightly simpler workflow, as shown in Figure 8-3.

Figure 8-3. The folder workflow for content that comes with Plone

Other Workflows

Numerous workflows are available to a Plone site, including private workflow, community workflow, one-step publication workflow, and so on. ZopeZen comes with a workflow, and PloneCollectorNG also comes with a workflow. DCWorkflow comes with four workflows.

Currently, two workflows come in the PloneWorkflows product in the collective project on SourceForge (http://sf.net/projects/collective): the community workflow and one-step publication workflow. The community workflow is similar to the Plone workflow, with a few changes. The one-step publication workflow has two states: private and published.

At the moment, you have no easy way to install and uninstall workflows, and you have no real easy way to transition content between one state and another. For example, if you install the one-step publication workflow into an existing state, you also need to fix the states for all objects and move them into one of the new states. In this case, it's probably simple-everything in a published state should stay as it is, and everything else should move into the private state.

Setting the Initial State

To set the initial state, go to the States tab and check out the states available; next to one of the states you'll see an asterisk, as shown in Figure 8-6.

Figure 8-6. Setting the initial state for this workflow

You set the initial state for your workflow on this page by checking the box next to the state and then clicking Set Initial State. All content that uses this workflow will be created with an initial state. Any content that has already been created will remain in its initial state; changing the state afterward won't change that state. You can set only one initial state for each workflow.

Editing States

The States tab lists the states that are present in this workflow. At the beginning of this chapter, I explained that a state represents an object at a particular point in time. Each state has an ID that's unique; this is usually a simple verb such as pending or published. To add a state, enter an ID and click Add at the bottom of the page.

You'll also see the following options:

Title: The title of the state is displayed in your Plone site and is a user-friendly version of the state.

Description: The description of the state is a long description of the state. This isn't currently shown to users but may be in the future.

Possible transitions: This lists all the possible transitions that can occur from the state. This list will show only if you actually have a transition in the system. Simply select the transitions that need to occur on this state. By selecting a transition for this state, you're selecting the start point for this transition to be this state.

To alter a state, enter the changes and then click Save to commit the changes. The Permissions tab will open with the permissions that will be applied to an object while it's in this state. This may mean changing the permissions on an object when it transitions into that state. The form is rather self-explanatory; to enable an anonymous user to view the object, check the boxes that correspond to View and Anonymous and click Save, as shown in Figure 8-7.

Figure 8-7. State permissions page

If you change the permissions for a particular workflow state, you've created an issue that needs resolving. Any existing content in that state won't have the new workflow permissions set on it. The content will have the old workflow permissions, and you'll need to update them. When you've finished making all your changes, go to the root workflow page and click Update Security Settings, as shown in Figure 8-4. Performing that update may take a while depending upon the number of objects to be altered.

The Variables tab allows you to assign a value to a variable when the object is in this state. The workflow determines the list of variables available to each state. For more information on these, see the "Editing Variables" section.

Editing Transitions

The Transitions tab lists the transitions that will occur in this workflow. In the beginning of this chapter, I showed you how a transition represents the changes that will occur to the object. Each transition has a few variables that are shown on the summary page. To add a transition, enter an ID and click Add at the bottom of the page, as shown in Figure 8-8.

Figure 8-8. Transition details page

If you now click a transition, you'll open the following details for that transition:

Title: This is the title for this transition.

Description: This is the detailed description for this transition.

Destination state: This is the state that will be the target for this transition. The initial source state is defined by assigning the transition to the state.

Trigger type: This indicates how the transition will be triggered. Automatic means that this will happen as soon as it moves into this state. Initiated by user action is the most common choice and means a user has enacted the transition by clicking a link.

Script (before): This runs this script before this transition occurs.

Script (after): This runs this script after this transition occurs.

Guard: This is the security for this state (explained shortly).

Display in actions box: This is how this transition will be displayed in Plone. Entering a value here also ensures that the transition will be entered as an action. You can then get this transition as an action by querying for actions.

Of these values, the destination state is quite interesting. Although I've already mentioned that transitions normally change state, this isn't required. Because each transition can run scripts and write something into the history, it can be useful sometimes not to change state. For an example of this, see the "Using Workflow to Track Changes" section later in this chapter. If your transition does change the state, then select the new state as the destination state.

A transition can have multiple starting points but only one destination; if you need multiple destinations, you'll have to make multiple transitions. You can specify scripts to run before or after this transition. Two common examples are moving an object in workflow and sending an e-mail notification. The "Common Tasks and Examples" section covers both of these examples.

Before any transition can be executed, a security guard checks the entire transition to ensure that the user running the transition has the right to do so. The guard has the following three components:

Permission(s): These are the required permissions. Multiple permissions should have a semicolon (;) to separate them.

Role(s): These are the required roles. Multiple roles should have a semicolon (;) to separate them.

Expression: This is a workflow expression. For more information on this, see the "Editing Workflow Expressions" section later in this chapter. For each value specified, the guard must evaluate as true before continuing. If a test of any of the values fail, then the transition won't execute. Usually you'll find most guards have only one or two values specified.

Editing Variables

The Variables tab lists the variables that will be created and changed in the workflow. I haven't discussed variables much with you up to this point; instead, I've focused on states and transitions. This section covers variables.

It isn't always possible, and I don't recommend that you try, to encapsulate all the information you'll need in a workflow within just states and transitions. Instead, you can use variables to store some workflow-related information. For example, in the credit card bill example, the bill could be paid by several methods (Internet banking, check, and so on). You could store the amount method ($100, for example) in a variable. Should the bill be rejected or altered, that amount would be updated. The point of a variable is to have something that changes between each state and transition.

So, returning to the main workflow page, click the Variables tab to get a list of all the variables. To add a variable, enter a variable* ID and click Add at the bottom of the page. To determine what state an object is in at any time, DCWorkflow stores the current state in a variable on the object. The default name of that variable is *review_state.

NOTE If you need to change this because it conflicts with another name, you can do so at the bottom of that page. However, doing this will cause all your current objects to lose their state, so be careful about changing that value.

Each workflow variable has the following properties:

• Description: This is the variable description.
• Make available to catalog: These variables will be placed in a list exposable to the catalog. This doesn't add indexes or metadata to the catalog; you still have to do that manually.
• Store in workflow: This determines if the information is to be stored in the workflow or on the object.
• Variable update mode: This determines when to update the variable.
• Default value: This determines a default value as a string.
• Default expression: This is the default value as an expression. If this is present, it'll be used instead of default value (for more information, see the "Editing Workflow Expressions" section later in this chapter).
• Info. guard: These are security settings for accessing this variable. These guard settings are similar to the guard settings for a transition; however, the guard occurs when accessing the variable here.

Editing Worklists

The Worklists tab provides access to all the worklists that are assigned in this workflow. A worklist is a method of querying the workflow for information about the numbers of objects in that workflow. For example, I'd like to be able to easily ask the workflow for all the outstanding credit card bills I have.

To add a worklist, enter an ID and click Add. Each worklist has the following properties:

• Description: This is a description of the worklist.
• Cataloged variable matches: This is the value that the worklist must match to be added in this worklist. The variable matched is the workflow state variable given in the variables list (the default variable name for this variable is review_state).
• Display in actions box: This is information to display on the user interface. Entering a value here also ensures that the transition will be entered as an action. You can then get this transition as an action by querying for actions.
• Guard: This is a guard for accessing this worklist.

Returning to the credit card example, if I wanted to know all the credit card bills that need reviewing by me, then I could place this information in a worklist. First, the variable review_state would contain the current state for each item. All the credit card bills that need reviewing would be in the review state. Second, I'd add a worklist called review_queue, and the value for variable would be pending. I could now ask the worklist for all the items in the review_queue.

Although a worklist is a convenient way of storing this information, Plone doesn't use them. Instead, Plone uses ZCatalog directly to query objects that are workflowed. Since the DCWorkflow worklist uses the catalog tool, the end result is the same.

Editing Scripts

The Scripts tab lists the scripts that are available this workflow. This list is actually a standard folder in the ZMI, and you can add almost anything there. Since the main reason you'd want to do this would be to add a script to perform advanced handling of transitions, you should add only Script (Python) objects here.

To add a script from the Scripts tab, select Script (Python) from the Add drop-down menu, and give the script an ID. The script is passed one and only one object, which is the base workflow expression object; for more information on this object, see the "Editing Workflow Scripts" section later in this chapter. For example, if you need to access the actual object in the workflow, you can use a Python script such as the following:

##parameters=state_change
obj = state_change.object

What happens in this script is up to the developer-you can run almost anything here. You can trigger events, and you can access other workflows and transitions. For some example scripts, see the "Sending E-Mail Notifications" and "Moving Objects" sections later in this chapter. When the script executes, it will execute as the user who initiated the transition. You could assign proxy roles on the script if it needs to happen as someone else. Returning to the transitions, you can assign this script to any number of transitions in the script (after) and script (before) settings. You can run the script either before or after a transition.

Editing Permissions

The Permissions tab lists the permissions that are managed by this workflow. You've seen these permissions already when examining the states. You set the list of permissions manageable in those states in this tab. To add a new permission, select the permission from the drop-down box and select Add.

Editing Workflow Scripts

Scripts are an opportunity for the developer to perform some logic upon a transition. That logic can be almost anything you want. You could be checking that some conditions have been performed (for example, is the document spell checked?) or that some special actions have been performed. When the object is transitioned, the script will be called.

When a script is called, one extra parameter is passed to that script. That extra parameter provides access to all sorts of transition-related elements and attributes. That parameter is called the state_change parameter, and it has the following attributes:

status: This is the workflow status.

object: This is the object being transitioned in the workflow.

workflow: This is the current workflow object for the object being transitioned.

transition: This is the current transition object being executed.

old_state: This is original state of the object.

new_state: This is destination state of the object.

kwargs: These are keyword arguments passed to the doActionFor method.

getHistory: This is a method that takes no parameters and returns a copy of the object's workflow history.

getPortal: This is a method that takes no parameters and returns the root Plone object.

ObjectDeleted(folder): This tells workflow that the object being transitioned has been deleted; it takes the object to which you'd like to return the user. Pass to the exception the folder you'd like the user to be redirected to (see the "Moving Objects" section later in this chapter).

ObjectMoved(newObject, newObject): This tells workflow that the object being transitioned has moved. Pass to the exception the folder you'd like the user to be redirected to (see the "Moving Objects" section later in the next chapter).

getDateTime: This is a method that takes no parameters and returns the DateTime object that relates to the transition.

For example, to find out what state is being transitioned to and when, the following is a Script (Python) object that will tell you just that information. This script logs the information about the transition into the log file:

##parameters=state_change
st = 'From %s to %s on %s' % (
    state_change.old_state,
    state_change.new_state,
    state_change.getDateTime())
context.plone_log(st)

TIP When you're writing a Script (Python) object, you may need to print to the log file to help with debugging. A script called plone_log does this, which takes a string and passes it to Plone's logging functions. Hence, calling context.plone_log is a useful tool for debugging.

When assigning a script to a transition, you have two choices: before and after. As the names suggest, a script that's set assigned to before runs prior to the transition running. This is suitable for scripts that may check if something should happen prior to the transition running, such as testing that another dependent object or page has been uploaded or there are no spelling errors. The script assigned to after runs once the transition completes-although if at any time an uncaught exception is raised on a script, this will cause the transition to fail, the object to remain in its original state, and the exception to display to the user.

Editing Workflow Expressions

Throughout this chapter you've seen values that can be expressed as workflow expressions. For example, the value assigned to a variable is the result of a workflow expression. This expression is nothing special; it's merely a Template Attribute Language (TAL) expression with a few different variables available. You already learned about TAL expressions in Chapter 5, so you should be familiar with these expression and all their options, such as Python, string, and path expressions.

Unlike the standard TAL expression, a few extra parameters are passed through to the namespace, relating to the particular workflow. The namespace for a workflow expression contains the following:

• here: This is the object being transitioned in the workflow.
• container: This is the container of the object being transitioned in the workflow.
• state_change: This is the state change object referenced in the "Editing Workflow Scripts" section.
• transition: This is the transition being executed, identical to state_change.transition.
• status: This is the original state, identical to state_change.old_state.
• workflow: This is the workflow for this object.
• scripts: These are the scripts available in this workflow.
• user: This is the user executing this transition.

Writing Through the ZMI

Probably the simplest but most laborious way to write workflow is to use the ZMI. Although the ZMI drives many people crazy, it's a simple way to set up the options. Unfortunately, once you've started writing through the ZMI, you're stuck in that paradigm. In other words, there's no easy to edit or alter that workflow on the file system. I discussed editing a workflow through the Web with you earlier in this chapter, of course.

To export a workflow from the ZMI, click portal_workflow and select the Contents tab. Select the created workflows you'd like to export by checking the boxes on the left of the ZMI, and then click import/export. At the top part of the export page, select Download to local machine, and click export. A file with extension .zexp will be created that can be saved and redistributed. Selecting XML Format will provide a file in Extensible Markup Language (XML) format with an .xml extension.

If you're provided a workflow in a the .zexp or .xml format, then importing the workflow into your Plone is straightforward. Place that file in the import directory of Zope on the file system. This can be the instance home directory or the Zope directory.

Then click portal_workflow, select the Contents tab, and click import/export. At the bottom part of the page, you'll see a small form that takes an import filename. Enter the name of the filename there, and leave Take ownership of imported objects selected. Click the Import button to import the workflow. The workflow will now be imported and given the name specified in the export.

Writing a Workflow in Python

Using Python is probably the favorite way of programmers to write a workflow, since it can all be done in Python and easily distributed. First, make a Python module on the file system. At the top of the file, import the appropriate tools, as follows:

from Products.CMFCore.WorkflowTool import addWorkflowFactory
from Products.DCWorkflow.DCWorkflow import DCWorkflowDefinition

Second, make a function that creates the workflow. Appendix A lists the API for writing a workflow in a little more detail. But you could just cheat and look at all the great examples available in the PloneWorkflow's project in the collective (http://sf.net/projects/collective), or even the ones contained in Plone. For example:

def sample(id):
    """ Sample workflow """
    ob = DCWorkflowDefinition(id)
    ob.states.addState('private')
    ob.states.addState('public')
    # add transitions
    return ob

Finally, register the workflow in the system, like so:

addWorkflowFactory(sample,
                   id='sample_workflow',
                   title='Sample workflow')

This script will need to be as part of a product installation. Chapter 12 covers writing and installing products.

Now, of course, a shortcut is available, which is called DCWorkflowDump. This will take the code from the ZMI and dump it into a Python module for you. You can find the source code for DCWorkflowDump in the collective at http://sf.net/projects/collective, but you can also find a zip file of the code on the Plone book Web site at http://plone-book.agmweb.ca.

To install DCWorkflowDump, unzip the file and copy the directory called DCWorkflowDump into the Products directory of your Plone installation. To check that you're in the right directory, your Products directory should also contain a directory for DCWorkflow, among other things. Then restart your Plone instance.

Once you've restarted Plone, go to the particular workflow in the ZMI, and you'll notice a new tab called dump. Click that page to get the dump screen, and then click Dump it! to dump the workflow to the screen. This will take your workflow and format it in Python for you. Save that file to your product, and you now have a Python file you can manipulate. This product is a great tool because it allows you to create the workflow in the ZMI and then distribute and alter it through Python.