Welcome, guest | Sign In | My Account | Store | Cart

Notice! PyPM is being replaced with the ActiveState Platform, which enhances PyPM’s build and deploy capabilities. Create your free Platform account to download ActivePython or customize Python with the packages you require and get automatic updates.

Download
ActivePython
INSTALL>
pypm install collective.wtf

How to install collective.wtf

  1. Download and install ActivePython
  2. Open Command Prompt
  3. Type pypm install collective.wtf
 Python 2.7Python 3.2Python 3.3
Windows (32-bit)
1.0b9 Available View build log
Windows (64-bit)
1.0b9 Available View build log
Mac OS X (10.5+)
1.0b9 Available View build log
Linux (32-bit)
1.0b9 Available View build log
Linux (64-bit)
1.0b9 Available View build log
 
Author
License
LGPL
Lastest release
version 1.0b9 on Jan 5th, 2011

by Martin Aspeli <optilude@gmail.com>

This package contains tools for working with DC Workflow definitions via spreadsheets (or rather, CSV format) as well as debugging aids to make it easier to work with security and workflow in Zope 2 and Plone.

It consists of:

  • A GenericSetup exporter that can dump a workflow definition to a CSV file
  • A GenericSetup importer that can create a workflow definition from a CSV

System Message: WARNING/2 (<string>, line 15)

Bullet list ends without a blank line; unexpected unindent.

file - An in-browser tool to sanity-check a workflow - A browser view to dump a workflow in the site to CSV as a one-off - A browser view to show the roles of a user in a given context - Utility functions to trigger automatic transitions on an object, as well as on its parent.

CSV import/export

Please note that the CSV format is not completely equivalent to the standard XML-based GenericSetup format to import/export workflow definitions. If you require the full power of DCWorkflow, you should continue to use the XML based format. This is not (just) due to laziness - the CSV format has been simplified to make common operations easy.

For an example CSV file, see

collective/wtf/tests/profiles/testing/test_wf.csv.

To be imported as part of a GenericSetup extension profile, a file like this would normally go in

profiles/default/workflow_csv/wf_name.csv

where wf_name is the name of the workflow in portal_workflow.

Note that if a full workflow definition does exist (e.g. in profiles/default/workflows/my_workflow/definition.xml), the CSV importer will not attempt to run an import, so as not to conflict or overwrite changes.

To download a workflow definition in CSV format as a one-off, type a URL like this into your browser:

http://localhost:8080/Plone/portal_workflow/my_workflow/@@to-csv

Here, "Plone" is the name of the Plone instance and "my_workflow" is the name of your workflow definition. You will be asked to download a CSV file.

Workflow sanity checker

To invoke the sanity checker, type a URL like this into your browser:

http://localhost:8080/Plone/portal_workflow/my_workflow/@@sanity-check

Again, "Plone" is the name of the Plone instance and "my_workflow" is the name of the workflow definition. The output will be written to the browser window in plain text.

Other debugging aids

To view the current roles of a given user in a given context, type a URL like this into your browser when logged in as a Manager user:

http://localhost:8080/Plone/context/@@display-roles-in-context?user=<user>

Again, "Plone" is the name of the Plone instance. "context" could be any object. <user> should be replaced by the login name/id of the user you want to fetch roles for. The output will be written to the browser window in plain text.

CSV file specification

This section details the CSV file format.

General

The CSV file format generally relies on key-value pairs, where keys are in the first column (A) and values in the second column (B). Key names are not case sensitive, may substitute hyphens for spaces, and may optionally contain a trailing colon. For example, the following are all equivalent:

System Message: WARNING/2 (<string>, line 91)

Literal block expected; none found.

Some key:,some_value some key:,some_value some-key , some_value

The file is sub-divided into sections. A section begins with a row containing the section name in square brackets, and ends with at least one blank row. For example:

[SomeSection]

System Message: ERROR/3 (<string>, line 100)

Inconsistent literal block quoting.

Some key:,some_value Some other key:,another_value

[AnotherSection] ...

The various sections are listed below, in more detail.

The [Workflow] section

This is generally the first section in the file. It contains information about the workflow as a whole, with the following keys. Keys marked with a * are required.

Id* -- The name of the workflow as it will be installed in portal_workflow.

Initial state* -- The name of the initial state of the workflow. Must match the id of a [State] section elsewhere in the file.

Title -- A human-friendly title for the workflow.

Description -- A human-friendly description for the workflow.

Type -- The meta_type of the workflow. Defaults to 'Workflow', which is the standard DCWorkflow definition type. Note that if you have a custom workflow, there is no guarantee that collective.wtf will be able to parse it, so be careful.

State variable -- The workflow variable that holds the current state. For the primary workflow of a Plone content object, this should be 'review_state', which is the default. However, if you are designing a secondary workflow in a multi-workflow chain, it may need a different state variable.

For example:

[Workflow]

System Message: ERROR/3 (<string>, line 138)

Inconsistent literal block quoting.

Id:,test_workflow Title:,Test workflow Description:,Description of workflow Initial state:,state_one

The [State] section

This section defines a single workflow state. It must end with a permissions table - see below.

Id* -- A unique name for the state.

Title* -- A human-friendly title.

Description -- A human-friendly description.

Transitions -- A comma-separated list of transitions. Note that this should be limited to a single cell. Hence, you will need double quotes around the list, e.g. "transition_1, transition_2". Each transition listed must match the id of a [Transition] section elsewhere in the file.

Worklist -- The name of a worklist for objects in this state, if one is required.

Worklist label -- A human-friendly label for the worklist.

Worklist guard permission -- The name of a permission used to guard the worklist, if required.

Worklist guard expression -- A TALES expression used to guard the worklist, if required.

Worklist guard role -- The name of a role used to guard the workflist, if required.

For example:

[State]

System Message: ERROR/3 (<string>, line 177)

Inconsistent literal block quoting.

Id:,state_one Title:,State one Description:,Description of state one Transitions:,"to_state_two,to_state_three" Worklist:,State one worklist Worklist label:,Worklist stuff goes here Worklist guard permission:,Review portal content Worklist guard expression:,python:True==True Worklist guard role:,Manager Permissions, Acquire, Manager, Member, Owner View, Y, Y, N, Y Access contents information, Y, Y, N, Y Modify portal content, N, Y, N, N

The permissions table

At the end of a [State] section, before the blank line that signals the end of that section, there must be a table of permissions for this state. The table may look like this:

System Message: WARNING/2 (<string>, line 198)

Literal block expected; none found.

Permissions, Acquire, Manager, Member, Owner View, Y, Y, N, Y Access contents information, Y, Y, N, Y Modify portal content, N, Y, N, N

Note that the additional whitespace here is purely for readability, and is optional.

The permissions table is created by having the pseudo-key 'Permissions' in column A. Column B is used to indicate whether a given permission is acquired from the parent object or not. By convention, the header row should contain the word 'Acquire' here. Subsequent rows should contain role names.

Underneath the header row, the first column should contain the names of permissions. Subsequent columns indicate whether the given role has the given permission in this workflow state. A case-insensitive value of 'Y', '*', 'X' or 'Yes' indicates true. Any other value (including blanks, 'N' or 'No') indicates false.

The [Transition] section

This section defines a transition between two states. It may contain the following keys:

Id* -- A unique identifier for the transition

Title -- A human-friendly title for the transition.

Description -- A human-friendly description for the transition.

URL -- A string containing a URL that will be used when the user clicks the transition in the workflow menu. May contain the special variables %(portal_url)s, %(folder_url)s, %(content_url)s and %(user_id)s. If not given, the default view will be used.

Target state -- The state that the workflow should move to after this transition has been executed. If omitted, the transition will not cause a state change. If included, it must match the id of a [State] section defined elsewhere in the file.

Trigger -- One of 'User' or 'Automatic'. Defaults to 'User'. An automatic transition is one which is run automatically when the workflow enters a state for which the automatic transition is a valid exit transition. Automatic transitions are often used with transition guards to automatically advance the workflow in certain situations, and/or with transition scripts that execute on the automatic transition.

Guard permission -- The name of a permission that is required before this transition is made available.

Guard expression -- A TALES expression that must be true before this transition is made available.

Guard role -- The name of a role that the current user must have before this transition is made available.

Script before -- A script to execute before the transition effects a state change. This may either contain a simple string, in which case it must match the id of a [Script] section elsewhere in the file, or a dotted name to an external method, e.g. 'my.product.Extensions.script_name.function_name', where 'my.product' is the name of a product that contains an Extensions/ folder, 'script_name' is the name of a .py file in that Extensions/ folder, and 'function_name' is the name of a function in that .py file. The function must take two parameters: self, and a state_change, a StateChangeInfo object. In this case, the importer will create a new External Method with the appropriate module ('my.product.script_name') and function ('function_name'), give it and id based on the script and function name (in this case, 'script_name.function_name'), and set this as the script before.

Script after -- A script to execute after the transition effects a state change. This may contain the same values as Script before.

For example:

[Transition]

System Message: ERROR/3 (<string>, line 275)

Inconsistent literal block quoting.

Id:,to_state_one Title:,Make it state one Description:,Make it go to state one Target state:,state_one Trigger:,User Guard permission:,Modify portal content,View Guard expression:,python:True==True Guard role:,Manager Script before:,shared_script Script after:,collective.wtf.Extensions.test_scripts.inline_test_one

The [Script] section

This may be used to define a script explicitly. Only external method scripts are supported. Note that single-use external methods can be defined "inline" using the notation described under 'The [Transition] section' above.

Id* -- The id of the script

Type* -- Should be 'External Method'. In the future, other types of script may be supported.

Module* -- The module where the external method is defined. Note that this should not contain the 'Extensions' directory.

Function* -- The name of the function to execute when the external method is run.

For example:

[Script]

System Message: ERROR/3 (<string>, line 307)

Inconsistent literal block quoting.

Id:,shared_script Type:,External Method Module:, collective.wtf.test_scripts Function:,script_section_test

Changelog

1.0b9
  • Don't make assumptions about the csv dialect on import. Instead, sniff the

System Message: WARNING/2 (<string>, line 319)

Bullet list ends without a blank line; unexpected unindent.

first 1024 bytes. [mj]

1.0b8
  • Avoid creating a ghost workflow_csv folder in the current directory.

System Message: WARNING/2 (<string>, line 326)

Bullet list ends without a blank line; unexpected unindent.

[optilude]

1.0b7
  • Add CMF 2.2 / Plone 4 support. Note that the new workflow options (like

System Message: WARNING/2 (<string>, line 332)

Bullet list ends without a blank line; unexpected unindent.

"manager bypass" and "creation guard") are not (yet) supported. [optilude]

1.0b6
  • Add support for setting the state variable, with the 'State variable' option

System Message: WARNING/2 (<string>, line 339)

Bullet list ends without a blank line; unexpected unindent.

to the main workflow section. [optilude]

1.0b5
  • Now imports/exports meta_type, in order to support workflows defined with

System Message: WARNING/2 (<string>, line 346)

Bullet list ends without a blank line; unexpected unindent.

collective.reactiveworkflow. This uses the option 'Type' in the main workflow section. [optildue]

1.0b5
  • Added utility methods to trigger automatic transitions on self and on

System Message: WARNING/2 (<string>, line 354)

Bullet list ends without a blank line; unexpected unindent.

the parent, borrowed from Products.ReactiveWorkflow, but made to be useable directly from a script rather than only in an event handler. [optilude]

  • Improve documentation

System Message: WARNING/2 (<string>, line 359)

Bullet list ends without a blank line; unexpected unindent.

[optilude]

  • Add inline script support

System Message: WARNING/2 (<string>, line 362)

Bullet list ends without a blank line; unexpected unindent.

[optilude]

1.0b4
  • Add script support

System Message: WARNING/2 (<string>, line 368)

Bullet list ends without a blank line; unexpected unindent.

[elro]

1.0b2
  • Add the ability to display roles in any context via a simple browser view

System Message: WARNING/2 (<string>, line 374)

Bullet list ends without a blank line; unexpected unindent.

[optilude]

Subscribe to package updates

Last updated Jan 5th, 2011

Download Stats

Last month:1

What does the lock icon mean?

Builds marked with a lock icon are only available via PyPM to users with a current ActivePython Business Edition subscription.

Need custom builds or support?

ActivePython Enterprise Edition guarantees priority access to technical support, indemnification, expert consulting and quality-assured language builds.

Plan on re-distributing ActivePython?

Get re-distribution rights and eliminate legal risks with ActivePython OEM Edition.