[Checkins] SVN: Products.DCWorkflow/trunk/docs/ STX help files moved to `docs` folder and converted to ReST
Charlie Clark
cvs-admin at zope.org
Wed Apr 4 19:43:02 UTC 2012
Log message for revision 124949:
STX help files moved to `docs` folder and converted to ReST
Changed:
A Products.DCWorkflow/trunk/docs/
D Products.DCWorkflow/trunk/docs/001-overview.stx
D Products.DCWorkflow/trunk/docs/002-expressions.stx
D Products.DCWorkflow/trunk/docs/003-guards.stx
D Products.DCWorkflow/trunk/docs/004-actionbox.stx
D Products.DCWorkflow/trunk/docs/011-states.stx
D Products.DCWorkflow/trunk/docs/021-transition.stx
D Products.DCWorkflow/trunk/docs/031-variables.stx
D Products.DCWorkflow/trunk/docs/041-worklists.stx
D Products.DCWorkflow/trunk/docs/051-scripts.stx
D Products.DCWorkflow/trunk/docs/061-permissions.stx
A Products.DCWorkflow/trunk/docs/ActioneBoxes.rst
A Products.DCWorkflow/trunk/docs/Expressions.rst
A Products.DCWorkflow/trunk/docs/Guards.rst
A Products.DCWorkflow/trunk/docs/Overview.rst
A Products.DCWorkflow/trunk/docs/Permissions.rst
A Products.DCWorkflow/trunk/docs/Scripts.rst
A Products.DCWorkflow/trunk/docs/States.rst
A Products.DCWorkflow/trunk/docs/Transition.rst
A Products.DCWorkflow/trunk/docs/Variables.rst
A Products.DCWorkflow/trunk/docs/Worklists.rst
-=-
Deleted: Products.DCWorkflow/trunk/docs/001-overview.stx
===================================================================
--- Products.DCWorkflow/trunk/Products/DCWorkflow/help/001-overview.stx 2012-04-04 18:20:29 UTC (rev 124945)
+++ Products.DCWorkflow/trunk/docs/001-overview.stx 2012-04-04 19:42:59 UTC (rev 124949)
@@ -1,82 +0,0 @@
-Overview
-
- DCWorkflows provide workflow objects that are fully customizable via
- the Zope Management Interface. You can specify the states, and the
- permissions they set on content that is in that state, the transitions
- between those states, and other things like variables for things that
- aren't well represented by states, work lists for reviewers, and
- scripts to embody complex guards and to extend pre and post transition
- behaviour.
-
- The process for creating a workflow runs something
- like this:
-
- - Draw a state diagram with the nodes (bubbles) as states and the
- arcs (arrows) as transitions. Remember to consider all the states
- your content can be in, and for each state, consider who should
- have permission to access and change the content. Consider what
- actions the users will perform to make the transitions between states,
- and not only who will be allowed to perform them, but who will be
- *required* to perform them.
-
- It's often a good idea to start on paper, then transfer
- the diagram to a digital copy using a diagram/flowchart tool, such as
- 'dia', so that you have an image to go with later documentation. This
- process tends to make it easier to spot corner cases before you
- actually create the workflow object.
-
- - Start by creating an example DCworkflow, rather than a new one, as it's
- faster to delete all the states and transitions than it is to create all the
- standard variables that tend to be used by the CMF. [**Note:**
- Perhaps we should have a bare dcworkflow, a workflow with standard
- variables, and the couple of standard examples.]
-
- - In the permissions tab, select all the permissions that you want the
- workflow to govern. These will be dependent on the types of content
- you'll be using with the workflow; 'Access contents information',
- 'Modify portal content', and 'View' are the standard permissions for
- the default portal content types.
-
- - Define any extra variables that you need for information that isn't
- well represented by states. [**Note:** generic examples? I can think of
- a few that could appear in some use cases, but they're all
- idiosyncratic of particular publishing needs]
-
- - Set up the states for your workflow, one for each node in your state
- diagram. Try to stick to the standard names for a publication workflow, as
- some badly behaved products have states like 'published' hardcoded into
- their searches (ie CalendarTool, last I looked) [**Note**: Maybe I
- should just file some bug reports rather than casting aspersions :-)].
- Set up the permissions on the states now, as well, though see the
- "State Tab" section for advice.
-
- - Set up any scripts that you will be using in your transitions, such
- as pre and post transition scripts and to handle complex guard
- conditions. Just set up skeletons for now, if you haven't though
- through all the details.
-
- - Create your transitions from all the arcs on your state diagram. You
- should be able to pick the right destination state as all your states
- are already defined, and set up the right scripts to run, as you've
- defined those as well. It's worth noting that the guard behaviour is
- such that if any guard matches, the transition can occur. You can
- specify more than one permission, role or expression by separating
- them with a semicolon.
-
- - Go back to the states tab and, for each state, set the possible
- transitions from the list of all available transitions in each state.
-
- - Finally, in the work lists tab, create any work lists for any states
- that need them. Work lists are actions that indicate how many objects
- of a given state are present, and usually link to some search page
- that lists the actual object instances. You typically use them to list
- all the pending content waiting for review. Work lists have several
- unusual behaviours, however, so check the specific notes in the
- "Worklists" section.
-
- By working in this order, you will tend to step through the
- creation process one tab at a time, rather than switching back and
- forth between them, which tends to be slower and somewhat confusing.
-
-
-
Deleted: Products.DCWorkflow/trunk/docs/002-expressions.stx
===================================================================
--- Products.DCWorkflow/trunk/Products/DCWorkflow/help/002-expressions.stx 2012-04-04 18:20:29 UTC (rev 124945)
+++ Products.DCWorkflow/trunk/docs/002-expressions.stx 2012-04-04 19:42:59 UTC (rev 124949)
@@ -1,64 +0,0 @@
-Expressions
-
- Expressions in DCWorkflow are TALES expressions. See
- "TALES Overview":/Control_Panel/Products/PageTemplates/Help/tales.stx
- for general TALES information. They are used as access guards and for
- the setting variable values.
-
- [**Note:** I haven't figured out what all these contexts actually are
- and what you can use them for. Explanations are is welcome!]
-
- Some of the contexts have slightly different meanings from what is provided
- for expressions in page templates:
-
- 'here' -- The content object (rather than the workflow object)
- 'container' -- The content object's container
-
- Several other contexts are also
- provided:
-
- 'state_change' -- A special object containing information about the
- state change (see below)
- 'transition' -- The transition object being executed
- 'status' -- The former status
- 'workflow' -- The workflow definition object
- 'scripts' -- The scripts in the workflow definition object
-
- 'state_change' objects provide the following attributes, some of which
- are duplicates of the above information:
-
- - 'status' is a mapping containing the workflow status. This
- includes all the variables defined in the variable tab with "store
- in state" checked.
-
- - 'object' is the object being modified by workflow.
- (Same as the 'here' variable above.)
-
- - 'workflow' is the workflow definition object. (Same as the
- 'workflow' variable above.)
-
- - 'transition' is the transition object being executed. (Same
- as the 'transition' variable above.)
-
- - 'old_state' is the former state object. The name of the former state,
- for example "published", is available as 'old_state.getId()'. (Note
- that DCWorkflow defines 'state' and 'status' as different entities;
- the name of the current 'state' is stored in the 'status'. The word
- clash is unfortunate; patches welcome.)
-
- - 'new_state' is the destination state object. Use 'new_state.getId()'
- to access the new state name.
-
- - 'kwargs' is the keyword arguments passed to the doActionFor() method.
-
- - 'getHistory()', a method that returns a copy of the object's workflow
- history.
-
- - 'getPortal()', which returns the root of the portal.
-
- - 'ObjectDeleted' and 'ObjectMoved', exceptions that can be raised by
- scripts to indicate to the workflow that an object has been moved or
- deleted.
-
- - 'getDateTime' is a method that returns the DateTime of the transition.
-
Deleted: Products.DCWorkflow/trunk/docs/003-guards.stx
===================================================================
--- Products.DCWorkflow/trunk/Products/DCWorkflow/help/003-guards.stx 2012-04-04 18:20:29 UTC (rev 124945)
+++ Products.DCWorkflow/trunk/docs/003-guards.stx 2012-04-04 19:42:59 UTC (rev 124949)
@@ -1,30 +0,0 @@
-Guards
-
- Guard settings control access to the transitions, variables or work
- lists. Guards can be applied based on permissions, roles, groups or
- a TALES expression. These elements are applied sequentially if they
- contain values. If one of the conditions in each of the specified
- permissions, roles or groups is met the guard element will be
- satisfied. For the guard to allow access, all specified element that
- contain values must be satisfied.
- If no permissions, roles or expressions are specified, access is
- automatically granted.
-
- You can supply several options in each field by separating them with
- a semicolon.
-
- The context in which the guards evaluate permissions and roles is
- obviously important. In the case of transitions and work lists, it
- depends on the category. If it's 'worklist', then the context is
- that of the content object, and local roles will behave just as
- you'd expect. If the category is 'global', then the context will be
- the site root, so the local roles between the site root and the
- content won't be considered.
-
- [**Note:** What about variables?]
-
-
-
-
-
-
Deleted: Products.DCWorkflow/trunk/docs/004-actionbox.stx
===================================================================
--- Products.DCWorkflow/trunk/Products/DCWorkflow/help/004-actionbox.stx 2012-04-04 18:20:29 UTC (rev 124945)
+++ Products.DCWorkflow/trunk/docs/004-actionbox.stx 2012-04-04 19:42:59 UTC (rev 124949)
@@ -1,39 +0,0 @@
-Action Boxes
-
- Action box settings are required for work lists and any transition that
- is intended to be a user initiated action. They define how the action
- will appear in the action box, what section it will appear in and
- what it will link to.
-
- Names and URLs for the actions box can be formatted using standard Python
- string formatting. An example::
-
- %(content_url)s/content_submit_form
-
- The string '%(content_url)s' will be replaced by the value of content_url.
- The following names are available:
-
- - portal_url
-
- - folder_url
-
- - content_url
-
- - count (Available in work lists only. Represents the number of items in
- the work list.)
-
- The following names are also available, in case there is any use for them.
- They are not strings.
-
- - portal
-
- - folder
-
- - content
-
- - isAnonymous
-
- Note that this formatting is done using standard Python string formatting
- rather than TALES. It might be more appropriate to use TALES instead.
- As always, patches welcome.
-
Deleted: Products.DCWorkflow/trunk/docs/011-states.stx
===================================================================
--- Products.DCWorkflow/trunk/Products/DCWorkflow/help/011-states.stx 2012-04-04 18:20:29 UTC (rev 124945)
+++ Products.DCWorkflow/trunk/docs/011-states.stx 2012-04-04 19:42:59 UTC (rev 124949)
@@ -1,45 +0,0 @@
-States Tab
-
- From the states tab it's possible to add new states, and rename and
- delete existing states. It is also possible to set a particular state
- to be the initial state that new content is set to when created.
-
- The list of existing states also displays each state's title and all
- the possible transitions from that state (and their titles). You can go
- straight to the details of each state and transition from here.
-
- Within a state's properties tab you can set the title, description,
- and the transitions that are possible from this state from a list of
- all the available transitions created in the workflow's
- transitions tab.
-
- In the state's permissions tab, you can set up the roles to
- permissions mappings that will apply to roles when content
- managed by this workflow is in this state. It uses the usual cookie
- cutter approach as do all other permissions tabs, except that the
- only permissions listed are those that have been selected to be
- managed by the workflow from the workflow's permissions tab.
-
- A good strategy for managing permissions on each state is to rely on
- acquisition for the "published" states, and to drop acquisition and
- use explicit permissions on states that are private or interim
- publishing states. This way, you can modify the access policy to
- "published" content at the site root or for specific folders without
- having to modify each workflow's set of "published" states.
-
- [**Note**: The available roles in the permissions tab will be
- whatever is acquired from the site root, so I guess creating
- roles under sub-folders ought to be discouraged if people want
- to use them in workflows]
-
- Reviewer roles should either have view permissions on every
- state or you should change the appropriate skins to take them
- somewhere sensible after a transition or they'll end up with an ugly
- access denied page after sending content back to private state.
-
- In the state's variables tab, you can add, change and delete variables
- that you want to assign a value to when objects move into
- this state. The available variables are set in the workflow's
- variables tab, and the value is a TALES expression (see Expressions
- for more details).
-
Deleted: Products.DCWorkflow/trunk/docs/021-transition.stx
===================================================================
--- Products.DCWorkflow/trunk/Products/DCWorkflow/help/021-transition.stx 2012-04-04 18:20:29 UTC (rev 124945)
+++ Products.DCWorkflow/trunk/docs/021-transition.stx 2012-04-04 19:42:59 UTC (rev 124949)
@@ -1,50 +0,0 @@
-Transitions Tab
-
- Transitions are the actions that move content from one state in the
- workflow to another. From the transitions tab it's possible to add new
- transitions, and rename and delete existing transitions.
-
- The list of existing transitions also displays a summary of each
- transition's title, description, destination state, trigger, guards,
- and action box entry. You can click through each transition to access
- their details.
-
- Within a transition's properties tab you can set the title, and
- a collection of properties the define the transtion's behaviour, as
- follows:
-
- Destination state -- selected from all the states defined in the
- states tab. A transition can remain in state, which is useful for a
- reviewer adding comments to the review history, but not taking any
- action, updating some variable, or invoking scripts.
-
- Trigger type - There are two types:
-
- - User actions are the familiar user initiated transitions activated
- by actions in the action box.
-
- - Automatic transitions are executed any time other workflow
- events occur; so if a user action results in the content moving
- to a state that has automatic transitions, they will be executed.
- (You should use mutually exclusive guards to prevent indeterminate
- behavior.)
-
-
- Scripts - Perform complicated behaviours either before or after the
- transition takes place. Scripts of all kinds are defined in the
- workflow's scripts tab. Scripts called from here must accept only
- one argument; a 'status_change' object. See Expressions for more
- details.
-
- Guards and Action boxes -- See the "Guards" and "Action Boxes"
- sections for specific details about those fields. Note that
- automatic transitions don't need the action box fields to be filled out.
-
- What the action should link to.
-
-
- In the transition's variables tab, you can add, change and delete
- variables that you want to assign a value to, when the transition is
- executed. The available variables are set in the workflow's variables
- tab, and the value is a TALES expression (see Expressions for more
- details).
Deleted: Products.DCWorkflow/trunk/docs/031-variables.stx
===================================================================
--- Products.DCWorkflow/trunk/Products/DCWorkflow/help/031-variables.stx 2012-04-04 18:20:29 UTC (rev 124945)
+++ Products.DCWorkflow/trunk/docs/031-variables.stx 2012-04-04 19:42:59 UTC (rev 124949)
@@ -1,48 +0,0 @@
-Variables Tab
-
- Variables are used to handle the state of various workflow related
- information that doesn't justify a state of it's own. The default
- CMF workflows use variables to track status history comments, and
- store the the last transition, who initiated it and when, for example.
- From the variables tab it's possible to add new variables, and rename
- and delete existing variables.
-
- The list of existing variables also displays a summary of each
- variable's description, catalog availability, workflow status, default
- value or expression and any access guards. You can click through to
- each variable to configure it's details.
-
- In each variable's property tab you can set the variable's
- description and a collection of properties the define the variable's
- behaviour, as follows:
-
- Make available to catalog -- Just as it says, it makes this variable
- available to the catalog for indexing, however it doesn't
- automatically create an index for it - you have to create one by
- hand that reflects the content of the variable. Once indexed, you can
- query the catalog for content that has a particular value in is
- variable, and update the variable by workflow actions.
-
- Store in workflow status -- The workflow status is a mapping that
- exists in the state_change object that is passed to scripts and
- available to expressions.
-
- Variable update mode -- Select whether the variable is updated on
- every transition (in which case, you should set a default
- expression), or whether it should only update if a transition or
- state sets a value.
-
- Default value -- Set the default value to some string.
-
- Default expression -- This is a TALES expression (as described in
- Expressions) and overrides the default value.
-
- Guards -- See the "Guards" section.
-
-
- State variable - stores the name of the variable the current state of
-the content is stored in. CMF uses 'review_state' by default, and will
-have already created a FieldIndex for it. The state variable is
-effectively a variable with "Make available to catalog" set, a default
-value of whatever the initial state is and a default expression that
-sets to the new state on every transition.
Deleted: Products.DCWorkflow/trunk/docs/041-worklists.stx
===================================================================
--- Products.DCWorkflow/trunk/Products/DCWorkflow/help/041-worklists.stx 2012-04-04 18:20:29 UTC (rev 124945)
+++ Products.DCWorkflow/trunk/docs/041-worklists.stx 2012-04-04 19:42:59 UTC (rev 124949)
@@ -1,128 +0,0 @@
-Worklists Tab
-
- Work lists are a way to make people aware of tasks they are required
- to perform, usually reviewing content in the publishing context.
- Work lists are implemented as a catalog query that puts an action in
- the actions box when there are some tasks the member needs to perform.
-
- From the work lists tab it's possible to add new work lists, and rename and
- delete existing work lists. The list of existing work lists also
- displays a short summary of each work list's description, the catalog query
- it uses, and any guard conditions. You can access the details of each
- work list by clicking on them.
-
- In each work list's properties tab, you can set the description of
- the work list, and it's various behaviour defining properties. The
- "Catalog variable matches" field sets the state that is work list
- matches. The "variable_name = " text to the left of the text box is
- the name of the state variable defined at the bottom of the variables
- tab. The values can be set to a number of possible matches separated
- by semicolons. [**Note:** CVS feature. There's more in
- doc/worklists.stx, but I'm not sure I understand the implications]
-
- The action box fields are discussed in more detail in the Action Box
- section. In this case, the url that the work list links to should
- probably implement a search page with a catalog query similar to the
- "Catalog variable matches", otherwise the difference between the
- number of items waiting and the items reported in the search will be
- confusing.
-
- [**Note:** What we *really* need from the work list is a way to define
- full catalog queries for the action, and a new action box variable
- that urlquotes that query so it can be passed straight to the search
- page. This way, the work list count and the number of items on the
- search page will be the same as they are derived from the same
- query string, defined in one place.
-
- Reply from Shane: work lists already exercise the catalog too heavily,
- and most people don't understand their purpose. Expanding their
- capabilities further could impact performance. I think perhaps
- the UI should instead display work lists on a user's home page rather
- than the actions box, which would open up new possibilities.]
-
- The guard fields are described in detail in the "Guards"
- section. It's probably better to avoid using permission and role
- guards, as they're not really necessary - a user will see a
- work list action only if they can see content in that particular
- state, so the state guards are usually sufficient. In addition, as
- the work lists are in the 'global' actions category by default, and
- global actions are evaluated in the context of the site root, local
- roles like Owner or locally set Reviewer roles, and the permissions
- they grant, will not apply. [*Note:* Does anyone know a good reason
- why work lists appear in the global box rather than in the workflow
- box? This particular problem should vanish if they are moved there.]
-
- Whether a work list action appears in the action box, and the
- number of items in the work list depends on several factors:
-
- - The state that the work list is generated for
-
- - The name of the state variable used to indicate the
- current state of an object
-
- - Whether the user can view content which is in that
- state
-
- This has some unexpected consequences:
-
- - If you have several workflow that use the same state variable,
- and similar state names, and each has a work list on, say, the
- 'pending' state, then both work lists will appear in the action box,
- and the number of items in each will be the total of all the content
- in a 'pending' state, regardless of which workflow manages that
- content (except that if the work list action entries are exactly the
- same text, the action tool will filter out the duplicate).
-
- - If each workflow manages the permissions on content in the
- 'pending' state differently, by, say, using two different reviewer
- roles, then users who have one role and not the other will
- see a single work list entry with the right number of items, but
- users with both roles will see the same as above.
-
- So there are a few tricks to getting the work lists to do the kinds of
- things we want.
-
- If you have several similar workflows, such as a standard one, and a
- couple of specialized ones for particular content, and you want to
- have one reviewer role for the lot, then you should set up just one
- work list in the standard workflow for the states that need them, and
- leave the other workflow to rely on that work list.
-
- If you have a workflow that uses a different reviewer role than
- other workflows, and consequently, you want it to have it's own
- separate work lists, you have two choices. One is to use state names
- that are unique to each workflow, while the second is
- to use state variable name that is unique each workflow. The
- second option is obviously a lot easier, however, if you change the
- name of the state variable when there exists content that is using
- this workflow, they will immediately loose there workflow state
- and default to the initial state. In addition, you'll need to add
- a field index for the new state variable name in the portal_catalog
- tool, by hand.
-
- [Note: In the first instance, we could add an action box name field
- to each state so that nicely formated names appear in the action
- box for things like "Published (yet to be effective)" rather than
- "published_not_yet_effective", and so we can lie about the names
- to make them unique, so that "foo_workflow_pending" looks like
- "Pending". In the second instance, I see no reason why the state
- variable name change action shouldn't migrate the value of the old
- state variable to the new for all the content managed by this
- workflow, and it could probably automatically add indexes for
- new state variable names if they don't already exists (and
- perhaps remove indexes for state variable names not used elsewhere).
-
- While we're thinking about ways to make sweeping workflow changes
- less painful, there are a couple of changes that could be made
- to the code that changes content type to workflow mappings: if a
- content to workflow mapping has changed, then, for each instance of
- that content type, attempt to keep the state variable the same
- unless that state doesn't exist in the new workflow, then evaluate
- any automatic transitions on that state. This way it's possible
- to migrate between workflows by ensuring that states with the same
- name have the same semantics, or if they don't exists in the new
- workflow, we can create placeholder states with an automatic
- transition to the state we want to be in.
- ]
-
-
Deleted: Products.DCWorkflow/trunk/docs/051-scripts.stx
===================================================================
--- Products.DCWorkflow/trunk/Products/DCWorkflow/help/051-scripts.stx 2012-04-04 18:20:29 UTC (rev 124945)
+++ Products.DCWorkflow/trunk/docs/051-scripts.stx 2012-04-04 19:42:59 UTC (rev 124949)
@@ -1,20 +0,0 @@
-Scripts Tab
-
- Scripts are used to extend the workflow in various ways. Scripts can
- be External Methods, Python Scripts, DTML methods, or any other callable
- Zope object. They are accessible by name in expressions, eg::
-
- scripts/myScript
-
- or::
-
- python:scripts.myScript(arg1, arg2...)
-
- From transitions, as before and after scripts, they are invoked with a
- 'state_change' object as the first argument; see the Expressions section
- for more details on the 'state_change' object.
-
- Objects under the scripts are managed in the usual ZMI fashion.
-
-
-
Deleted: Products.DCWorkflow/trunk/docs/061-permissions.stx
===================================================================
--- Products.DCWorkflow/trunk/Products/DCWorkflow/help/061-permissions.stx 2012-04-04 18:20:29 UTC (rev 124945)
+++ Products.DCWorkflow/trunk/docs/061-permissions.stx 2012-04-04 19:42:59 UTC (rev 124949)
@@ -1,10 +0,0 @@
-Permissions Tab
-
- You can manage all of the actions a user can perform on an object by
- setting up permissions to be managed by the workflow under the
- permissions tab. Here, you can select which permissions should be
- state-dependent from a list of all available permissions, and you
- can delete previously selected permissions. In each state, use
- it's permissions tab to set up the role to permission mappings
- appropriate for that state.
-
Copied: Products.DCWorkflow/trunk/docs/ActioneBoxes.rst (from rev 124945, Products.DCWorkflow/trunk/Products/DCWorkflow/help/004-actionbox.stx)
===================================================================
--- Products.DCWorkflow/trunk/docs/ActioneBoxes.rst (rev 0)
+++ Products.DCWorkflow/trunk/docs/ActioneBoxes.rst 2012-04-04 19:42:59 UTC (rev 124949)
@@ -0,0 +1,39 @@
+Action Boxes
+============
+
+Action box settings are required for work lists and any transition that is
+intended to be a user initiated action. They define how the action will
+appear in the action box, what section it will appear in and what it will
+link to.
+
+Names and URLs for the actions box can be formatted using standard Python
+string formatting. An example::
+
+ %(content_url)s/content_submit_form
+
+The string '%(content_url)s' will be replaced by the value of content_url.
+The following names are available:
+
+* portal_url
+
+* folder_url
+
+* content_url
+
+* count (Available in work lists only. Represents the number of items in the
+ work list.)
+
+The following names are also available, in case there is any use for them.
+They are not strings.
+
+* portal
+
+* folder
+
+* content
+
+* isAnonymous
+
+Note that this formatting is done using standard Python string formatting
+rather than TALES. It might be more appropriate to use TALES instead. As
+always, patches welcome.
Copied: Products.DCWorkflow/trunk/docs/Expressions.rst (from rev 124945, Products.DCWorkflow/trunk/Products/DCWorkflow/help/002-expressions.stx)
===================================================================
--- Products.DCWorkflow/trunk/docs/Expressions.rst (rev 0)
+++ Products.DCWorkflow/trunk/docs/Expressions.rst 2012-04-04 19:42:59 UTC (rev 124949)
@@ -0,0 +1,61 @@
+Expressions
+===========
+
+Expressions in DCWorkflow are TALES expressions. They are used as access
+guards and for the setting variable values.
+
+[**Note:** I haven't figured out what all these contexts actually are
+and what you can use them for. Explanations are is welcome!]
+
+Some of the contexts have slightly different meanings from what is provided
+for expressions in page templates:
+
+* 'here' -- The content object (rather than the workflow object)
+* 'container' -- The content object's container
+
+Several other contexts are also provided:
+
+* 'state_change' -- A special object containing information about the state
+change (see below)
+
+* 'transition' -- The transition object being executed
+
+* 'status' -- The former status 'workflow' -- The workflow definition object
+
+* 'scripts' -- The scripts in the workflow definition object
+
+'state_change' objects provide the following attributes, some of which
+are duplicates of the above information:
+
+* 'status' is a mapping containing the workflow status. This includes all the
+ variables defined in the variable tab with "store in state" checked.
+
+* 'object' is the object being modified by workflow.(Same as the 'here'
+ variable above.)
+
+* 'workflow' is the workflow definition object. (Same as the 'workflow'
+ variable above.)
+
+*- 'transition' is the transition object being executed. (Same as the
+ 'transition' variable above.)
+
+* 'old_state' is the former state object. The name of the former state, for
+ example "published", is available as 'old_state.getId()'. (Note that
+ DCWorkflow defines 'state' and 'status' as different entities; the name of
+ the current 'state' is stored in the 'status'. The word clash is unfortunate;
+ patches welcome.)
+
+* 'new_state' is the destination state object. Use 'new_state.getId()' to
+ access the new state name.
+
+* 'kwargs' is the keyword arguments passed to the doActionFor() method.
+
+* 'getHistory()', a method that returns a copy of the object's workflow
+ history.
+
+* 'getPortal()', which returns the root of the portal.
+
+* 'ObjectDeleted' and 'ObjectMoved', exceptions that can be raised by scripts
+ to indicate to the workflow that an object has been moved or deleted.
+
+* 'getDateTime' is a method that returns the DateTime of the transition.
Copied: Products.DCWorkflow/trunk/docs/Guards.rst (from rev 124945, Products.DCWorkflow/trunk/Products/DCWorkflow/help/003-guards.stx)
===================================================================
--- Products.DCWorkflow/trunk/docs/Guards.rst (rev 0)
+++ Products.DCWorkflow/trunk/docs/Guards.rst 2012-04-04 19:42:59 UTC (rev 124949)
@@ -0,0 +1,24 @@
+Guards
+======
+
+Guard settings control access to the transitions, variables or work lists.
+Guards can be applied based on permissions, roles, groups or a TALES
+expression. These elements are applied sequentially if they contain values.
+If one of the conditions in each of the specified permissions, roles or
+groups is met the guard element will be satisfied. For the guard to allow
+access, all specified element that contain values must be satisfied.
+
+If no permissions, roles or expressions are specified, access is
+automatically granted.
+
+You can supply several options in each field by separating them with a
+semicolon.
+
+The context in which the guards evaluate permissions and roles is obviously
+important. In the case of transitions and work lists, it depends on the
+category. If it's 'worklist', then the context is that of the content object,
+and local roles will behave just as you'd expect. If the category is
+'global', then the context will be the site root, so the local roles between
+the site root and the content won't be considered.
+
+[**Note:** What about variables?]
Copied: Products.DCWorkflow/trunk/docs/Overview.rst (from rev 124945, Products.DCWorkflow/trunk/Products/DCWorkflow/help/001-overview.stx)
===================================================================
--- Products.DCWorkflow/trunk/docs/Overview.rst (rev 0)
+++ Products.DCWorkflow/trunk/docs/Overview.rst 2012-04-04 19:42:59 UTC (rev 124949)
@@ -0,0 +1,75 @@
+Overview
+========
+
+DCWorkflows provide workflow objects that are fully customizable via the Zope
+Management Interface. You can specify the states, and the permissions they
+set on content that is in that state, the transitions between those states,
+and other things like variables for things that aren't well represented by
+states, work lists for reviewers, and scripts to embody complex guards and to
+extend pre and post transition behaviour.
+
+The process for creating a workflow runs something
+like this:
+
+* Draw a state diagram with the nodes (bubbles) as states and the arcs
+ (arrows) as transitions. Remember to consider all the states your content can
+ be in, and for each state, consider who should have permission to access and
+ change the content. Consider what actions the users will perform to make the
+ transitions between states, and not only who will be allowed to perform them,
+ but who will be *required* to perform them.
+
+ It's often a good idea to start on paper, then transfer
+ the diagram to a digital copy using a diagram/flowchart tool, such as
+ 'dia', so that you have an image to go with later documentation. This
+ process tends to make it easier to spot corner cases before you
+ actually create the workflow object.
+
+* Start by creating an example DCworkflow, rather than a new one, as it's
+ faster to delete all the states and transitions than it is to create all the
+ standard variables that tend to be used by the CMF. [**Note:** Perhaps we
+ should have a bare dcworkflow, a workflow with standard variables, and the
+ couple of standard examples.]
+
+* In the permissions tab, select all the permissions that you want the
+ workflow to govern. These will be dependent on the types of content you'll be
+ using with the workflow; 'Access contents information', 'Modify portal
+ content', and 'View' are the standard permissions for the default portal
+ content types.
+
+* Define any extra variables that you need for information that isn't well
+ represented by states. [**Note:** generic examples? I can think of a few that
+ could appear in some use cases, but they're all idiosyncratic of particular
+ publishing needs]
+
+* Set up the states for your workflow, one for each node in your state
+ diagram. Try to stick to the standard names for a publication workflow, as
+ some badly behaved products have states like 'published' hardcoded into their
+ searches (ie CalendarTool, last I looked) [**Note**: Maybe I should just file
+ some bug reports rather than casting aspersions :-)]. Set up the permissions
+ on the states now, as well, though see the "State Tab" section for advice.
+
+* Set up any scripts that you will be using in your transitions, such as pre
+ and post transition scripts and to handle complex guard conditions. Just set
+ up skeletons for now, if you haven't though through all the details.
+
+* Create your transitions from all the arcs on your state diagram. You
+ should be able to pick the right destination state as all your states
+ are already defined, and set up the right scripts to run, as you've
+ defined those as well. It's worth noting that the guard behaviour is
+ such that if any guard matches, the transition can occur. You can
+ specify more than one permission, role or expression by separating
+ them with a semicolon.
+
+* Go back to the states tab and, for each state, set the possible transitions
+ from the list of all available transitions in each state.
+
+* Finally, in the work lists tab, create any work lists for any states that
+ need them. Work lists are actions that indicate how many objects of a given
+ state are present, and usually link to some search page that lists the actual
+ object instances. You typically use them to list all the pending content
+ waiting for review. Work lists have several unusual behaviours, however, so
+ check the specific notes in the "Worklists" section.
+
+By working in this order, you will tend to step through the
+creation process one tab at a time, rather than switching back and
+forth between them, which tends to be slower and somewhat confusing.
Copied: Products.DCWorkflow/trunk/docs/Permissions.rst (from rev 124945, Products.DCWorkflow/trunk/Products/DCWorkflow/help/061-permissions.stx)
===================================================================
--- Products.DCWorkflow/trunk/docs/Permissions.rst (rev 0)
+++ Products.DCWorkflow/trunk/docs/Permissions.rst 2012-04-04 19:42:59 UTC (rev 124949)
@@ -0,0 +1,9 @@
+Permissions Tab
+
+You can manage all of the actions a user can perform on an object by
+setting up permissions to be managed by the workflow under the
+permissions tab. Here, you can select which permissions should be
+state-dependent from a list of all available permissions, and you
+can delete previously selected permissions. In each state, use
+it's permissions tab to set up the role to permission mappings
+appropriate for that state.
Copied: Products.DCWorkflow/trunk/docs/Scripts.rst (from rev 124945, Products.DCWorkflow/trunk/Products/DCWorkflow/help/051-scripts.stx)
===================================================================
--- Products.DCWorkflow/trunk/docs/Scripts.rst (rev 0)
+++ Products.DCWorkflow/trunk/docs/Scripts.rst 2012-04-04 19:42:59 UTC (rev 124949)
@@ -0,0 +1,18 @@
+Scripts Tab
+===========
+
+Scripts are used to extend the workflow in various ways. Scripts can be
+External Methods, Python Scripts, DTML methods, or any other callable Zope
+object. They are accessible by name in expressions, eg::
+
+ scripts/myScript
+
+or::
+
+ python:scripts.myScript(arg1, arg2...)
+
+From transitions, as before and after scripts, they are invoked with a
+'state_change' object as the first argument; see the Expressions section for
+more details on the 'state_change' object.
+
+Objects under the scripts are managed in the usual ZMI fashion.
Copied: Products.DCWorkflow/trunk/docs/States.rst (from rev 124945, Products.DCWorkflow/trunk/Products/DCWorkflow/help/011-states.stx)
===================================================================
--- Products.DCWorkflow/trunk/docs/States.rst (rev 0)
+++ Products.DCWorkflow/trunk/docs/States.rst 2012-04-04 19:42:59 UTC (rev 124949)
@@ -0,0 +1,42 @@
+States Tab
+==========
+
+From the states tab it's possible to add new states, and rename and delete
+existing states. It is also possible to set a particular state to be the
+initial state that new content is set to when created.
+
+The list of existing states also displays each state's title and all the
+possible transitions from that state (and their titles). You can go straight
+to the details of each state and transition from here.
+
+Within a state's properties tab you can set the title, description, and the
+transitions that are possible from this state from a list of all the
+available transitions created in the workflow's transitions tab.
+
+In the state's permissions tab, you can set up the roles to permissions
+mappings that will apply to roles when content managed by this workflow is in
+this state. It uses the usual cookie cutter approach as do all other
+permissions tabs, except that the only permissions listed are those that have
+been selected to be managed by the workflow from the workflow's permissions
+tab.
+
+A good strategy for managing permissions on each state is to rely on
+acquisition for the "published" states, and to drop acquisition and use
+explicit permissions on states that are private or interim publishing states.
+This way, you can modify the access policy to "published" content at the site
+root or for specific folders without having to modify each workflow's set of
+"published" states.
+
+[**Note**: The available roles in the permissions tab will be whatever is
+acquired from the site root, so I guess creating roles under sub-folders
+ought to be discouraged if people want to use them in workflows]
+
+Reviewer roles should either have view permissions on every state or you
+should change the appropriate skins to take them somewhere sensible after a
+transition or they'll end up with an ugly access denied page after sending
+content back to private state.
+
+In the state's variables tab, you can add, change and delete variables that
+you want to assign a value to when objects move into this state. The
+available variables are set in the workflow's variables tab, and the value is
+a TALES expression (see Expressions for more details).
Copied: Products.DCWorkflow/trunk/docs/Transition.rst (from rev 124945, Products.DCWorkflow/trunk/Products/DCWorkflow/help/021-transition.stx)
===================================================================
--- Products.DCWorkflow/trunk/docs/Transition.rst (rev 0)
+++ Products.DCWorkflow/trunk/docs/Transition.rst 2012-04-04 19:42:59 UTC (rev 124949)
@@ -0,0 +1,49 @@
+Transitions Tab
+===============
+
+Transitions are the actions that move content from one state in the workflow
+to another. From the transitions tab it's possible to add new transitions,
+and rename and delete existing transitions.
+
+The list of existing transitions also displays a summary of each transition's
+title, description, destination state, trigger, guards, and action box entry.
+You can click through each transition to access their details.
+
+Within a transition's properties tab you can set the title, and a collection
+of properties the define the transtion's behaviour, as follows:
+
+**Destination state** --
+ selected from all the states defined in the states tab. A transition can
+ remain in state, which is useful for a reviewer adding comments to the review
+ history, but not taking any action, updating some variable, or invoking
+ scripts.
+
+**Trigger type** --
+ There are two types:
+
+ * User actions are the familiar user initiated transitions activated by
+ actions in the action box.
+
+ * Automatic transitions are executed any time other workflow events occur;
+ so if a user action results in the content moving to a state that has
+ automatic transitions, they will be executed. (You should use mutually
+ exclusive guards to prevent indeterminate behavior.)
+
+
+**Scripts** --
+ Perform complicated behaviours either before or after the transition takes
+ place. Scripts of all kinds are defined in the workflow's scripts tab.
+ Scripts called from here must accept only one argument; a 'status_change'
+ object. See Expressions for more details.
+
+**Guards and Action boxes** --
+ See the :doc:`Gaurds` and :doc:`ActionBoxes` sections for specific details
+ about those fields. Note that automatic transitions don't need the action box
+ fields to be filled out.
+
+ What the action should link to.
+
+In the transition's variables tab, you can add, change and delete variables
+that you want to assign a value to, when the transition is executed. The
+available variables are set in the workflow's variables tab, and the value is
+a TALES expression (see Expressions for more details).
Copied: Products.DCWorkflow/trunk/docs/Variables.rst (from rev 124945, Products.DCWorkflow/trunk/Products/DCWorkflow/help/031-variables.stx)
===================================================================
--- Products.DCWorkflow/trunk/docs/Variables.rst (rev 0)
+++ Products.DCWorkflow/trunk/docs/Variables.rst 2012-04-04 19:42:59 UTC (rev 124949)
@@ -0,0 +1,50 @@
+Variables Tab
+=============
+
+Variables are used to handle the state of various workflow related
+information that doesn't justify a state of it's own. The default CMF
+workflows use variables to track status history comments, and store the the
+last transition, who initiated it and when, for example. From the variables
+tab it's possible to add new variables, and rename and delete existing
+variables.
+
+The list of existing variables also displays a summary of each variable's
+description, catalog availability, workflow status, default value or
+expression and any access guards. You can click through to each variable to
+configure it's details.
+
+In each variable's property tab you can set the variable's description and a
+collection of properties the define the variable's behaviour, as follows:
+
+**Make available to catalog** --
+ Just as it says, it makes this variable available to the catalog for
+ indexing, however it doesn't automatically create an index for it - you have
+ to create one by hand that reflects the content of the variable. Once
+ indexed, you can query the catalog for content that has a particular value in
+ is variable, and update the variable by workflow actions.
+
+**Store in workflow status** --
+ The workflow status is a mapping that exists in the state_change object that
+ is passed to scripts and available to expressions.
+
+**Variable update mode** --
+ Select whether the variable is updated on every transition (in which case,
+ you should set a default expression), or whether it should only update if a
+ transition or state sets a value.
+
+**Default value** --
+ Set the default value to some string.
+
+**Default expression** --
+ This is a TALES expression (as described in Expressions) and overrides the
+ default value.
+
+**Guards** --
+ See the :doc:`Guards`.
+
+**State variable** --
+ stores the name of the variable the current state of the content is stored
+ in. CMF uses 'review_state' by default, and will have already created a
+ FieldIndex for it. The state variable is effectively a variable with "Make
+ available to catalog" set, a default value of whatever the initial state is
+ and a default expression that sets to the new state on every transition.
Copied: Products.DCWorkflow/trunk/docs/Worklists.rst (from rev 124945, Products.DCWorkflow/trunk/Products/DCWorkflow/help/041-worklists.stx)
===================================================================
--- Products.DCWorkflow/trunk/docs/Worklists.rst (rev 0)
+++ Products.DCWorkflow/trunk/docs/Worklists.rst 2012-04-04 19:42:59 UTC (rev 124949)
@@ -0,0 +1,116 @@
+Worklists Tab
+=============
+
+Work lists are a way to make people aware of tasks they are required to
+perform, usually reviewing content in the publishing context. Work lists are
+implemented as a catalog query that puts an action in the actions box when
+there are some tasks the member needs to perform.
+
+From the work lists tab it's possible to add new work lists, and rename and
+delete existing work lists. The list of existing work lists also displays a
+short summary of each work list's description, the catalog query it uses, and
+any guard conditions. You can access the details of each work list by
+clicking on them.
+
+In each work list's properties tab, you can set the description of the work
+list, and it's various behaviour defining properties. The "Catalog variable
+matches" field sets the state that is work list matches. The "variable_name =
+" text to the left of the text box is the name of the state variable defined
+at the bottom of the variables tab. The values can be set to a number of
+possible matches separated by semicolons. [**Note:** CVS feature. There's
+more in doc/worklists.stx, but I'm not sure I understand the implications]
+
+The action box fields are discussed in more detail in the Action Box section.
+In this case, the url that the work list links to should probably implement a
+search page with a catalog query similar to the "Catalog variable matches",
+otherwise the difference between the number of items waiting and the items
+reported in the search will be confusing.
+
+[**Note:** What we *really* need from the work list is a way to define full
+catalog queries for the action, and a new action box variable that urlquotes
+that query so it can be passed straight to the search page. This way, the
+work list count and the number of items on the search page will be the same
+as they are derived from the same query string, defined in one place.
+
+Reply from Shane: work lists already exercise the catalog too heavily, and
+most people don't understand their purpose. Expanding their capabilities
+further could impact performance. I think perhaps the UI should instead
+display work lists on a user's home page rather than the actions box, which
+would open up new possibilities.]
+
+The guard fields are described in detail in the :doc:`Guards` section. It's
+probably better to avoid using permission and role guards, as they're not
+really necessary - a user will see a work list action only if they can see
+content in that particular state, so the state guards are usually sufficient.
+In addition, as the work lists are in the 'global' actions category by
+default, and global actions are evaluated in the context of the site root,
+local roles like Owner or locally set Reviewer roles, and the permissions
+they grant, will not apply. [*Note:* Does anyone know a good reason why work
+lists appear in the global box rather than in the workflow box? This
+particular problem should vanish if they are moved there.]
+
+Whether a work list action appears in the action box, and the number of items
+in the work list depends on several factors:
+
+* The state that the work list is generated for
+
+* The name of the state variable used to indicate the current state of an
+ object
+
+* Whether the user can view content which is in that state
+
+This has some unexpected consequences:
+
+* If you have several workflow that use the same state variable, and similar
+ state names, and each has a work list on, say, the 'pending' state, then both
+ work lists will appear in the action box, and the number of items in each
+ will be the total of all the content in a 'pending' state, regardless of
+ which workflow manages that content (except that if the work list action
+ entries are exactly the same text, the action tool will filter out the
+ duplicate).
+
+* If each workflow manages the permissions on content in the 'pending' state
+ differently, by, say, using two different reviewer roles, then users who have
+ one role and not the other will see a single work list entry with the right
+ number of items, but users with both roles will see the same as above.
+
+So there are a few tricks to getting the work lists to do the kinds of things
+we want.
+
+If you have several similar workflows, such as a standard one, and a couple
+of specialized ones for particular content, and you want to have one reviewer
+role for the lot, then you should set up just one work list in the standard
+workflow for the states that need them, and leave the other workflow to rely
+on that work list.
+
+If you have a workflow that uses a different reviewer role than other
+workflows, and consequently, you want it to have it's own separate work
+lists, you have two choices. One is to use state names that are unique to
+each workflow, while the second is to use state variable name that is unique
+each workflow. The second option is obviously a lot easier, however, if you
+change the name of the state variable when there exists content that is using
+this workflow, they will immediately loose there workflow state and default
+to the initial state. In addition, you'll need to add a field index for the
+new state variable name in the portal_catalog tool, by hand.
+
+[Note: In the first instance, we could add an action box name field to each
+state so that nicely formated names appear in the action box for things like
+"Published (yet to be effective)" rather than "published_not_yet_effective",
+and so we can lie about the names to make them unique, so that
+"foo_workflow_pending" looks like "Pending". In the second instance, I see no
+reason why the state variable name change action shouldn't migrate the value
+of the old state variable to the new for all the content managed by this
+workflow, and it could probably automatically add indexes for new state
+variable names if they don't already exists (and perhaps remove indexes for
+state variable names not used elsewhere).
+
+While we're thinking about ways to make sweeping workflow changes less
+painful, there are a couple of changes that could be made to the code that
+changes content type to workflow mappings: if a content to workflow mapping
+has changed, then, for each instance of that content type, attempt to keep
+the state variable the same unless that state doesn't exist in the new
+workflow, then evaluate any automatic transitions on that state. This way
+it's possible to migrate between workflows by ensuring that states with the
+same name have the same semantics, or if they don't exists in the new
+workflow, we can create placeholder states with an automatic transition to
+the state we want to be in.]
More information about the checkins
mailing list