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