[CMF-checkins] CVS: CMF/DCWorkflow/help - 001-overview.stx:1.1 002-expressions.stx:1.1 003-guards.stx:1.1 004-actionbox.stx:1.1 011-states.stx:1.1 021-transition.stx:1.1 031-variables.stx:1.1 041-worklists.stx:1.1 051-scripts.stx:1.1 061-permissions.stx:1.1

Shane Hathaway shane@cvs.zope.org
Mon, 15 Jul 2002 09:36:18 -0400


Update of /cvs-repository/CMF/DCWorkflow/help
In directory cvs.zope.org:/tmp/cvs-serv23990/help

Added Files:
	001-overview.stx 002-expressions.stx 003-guards.stx 
	004-actionbox.stx 011-states.stx 021-transition.stx 
	031-variables.stx 041-worklists.stx 051-scripts.stx 
	061-permissions.stx 
Log Message:
Checked in unfinished, not-yet-integrated help docs from John Morton.  Great
work!


=== Added File CMF/DCWorkflow/help/001-overview.stx ===
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.





=== Added File CMF/DCWorkflow/help/002-expressions.stx ===
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:

   - '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 'here'?

   - 'workflow' is the workflow definition object. Same as the
   workflow context, above?
  
   - 'transition' is the transition object being executed. Same
   as above?

   - 'old_state' is the former state object. Former status? Is this
   the same value in the contexts of pre and post scripts?

   - 'new_state' is the destination state object. Ditto?

   - '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.



=== Added File CMF/DCWorkflow/help/003-guards.stx ===
Guards

  Guard settings control access to the transitions, variables or work
  lists. If a user possesses any of the permissions or roles
  specified, or if one of the expressions evaluates as true, then
  whatever is being guarded is accessible. 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?]

  






=== Added File CMF/DCWorkflow/help/004-actionbox.stx ===
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:** How are these actually used without a TALES expression to use
 them in?]


=== Added File CMF/DCWorkflow/help/011-states.stx ===
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.

 [**Note:** Display bug - you can still see possible transitions that 
 have been deleted, though the don't show up in the action box or on a
 state's properties tab] 

 Within a state's properties tab you can set the title, 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).



=== Added File CMF/DCWorkflow/help/021-transition.stx ===
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, 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 three 
  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.
    [*Note:* In what order? Mutually exclusive guards seem necessary.]

    - WorkflowMethod initiate actions occur as a side effect when
    a method of the content object with the same name as the
    transtion, and that has been wrapped in the WorkflowMethod class
    is called.[*Note:* is the core method executed before or after the
    transition is attempted?]


  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 and WorkflowMethod 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).


=== Added File CMF/DCWorkflow/help/031-variables.stx ===
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 transitions 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.


=== Added File CMF/DCWorkflow/help/041-worklists.stx ===
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.]
 
 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.
 ]




=== Added File CMF/DCWorkflow/help/051-scripts.stx ===
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.





=== Added File CMF/DCWorkflow/help/061-permissions.stx ===
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.