For the workflows a lot of concepts have to work together: users, groups, roles, privileges, granting and denying permissions, namespaces, actions.

If set up correctly the system is very powerful and changes and/or new workflows have a minimal impact on the system. I will describe how things are related and what the best way is to set up a system.

For the example I will use a site containing recipes as an example. The following users are present: Alice, Dan, Ed, Joe, Jane, Mark, Mary, Sam, Steve.

And here are the groups. After the group the set of users of that group are listed:

• Soups editors: Alice
• Soups authors: Dan, Ed
• Main courses editors: Joe
• Main courses authors: Jane, Mark
• Desserts editors: Mary
• Desserts authors: Sam, Steve

One of the most important concepts are roles. By using roles, granting and denying permissions becomes very easy and the maintenance of assigned permissions is kept to a minimum. The recipes site uses the standard Hippo roles: author and editor.

The site uses the following folder structure for storing their recipes in the repository:

  general
  recipes
      desserts
          cheeses
          icecream
          puddings
      main courses
          chicken
          children
          fish
          meat
          vegetarian
      soups
          chicken
          fish
          meat
          vegetarian

The following permissions have been assigned to the folders:

  Folder                  Subject                 Privilege
  ----------------------  ----------------------  ---------
  recipes/desserts        Desserts authors        Author
  recipes/desserts        Desserts editors        Editor
  recipes/main courses    Main courses authors    Author
  recipes/main courses    Main courses editors    Editor
  recipes/soups           Soups authors           Author
  recipes/soups           Soups editors           Editor

As you can see only groups are used for the subject. Permissions can but nerver are assigned to a user directly. Also note that only roles are used for privileges. Neither standard WebDAV privileges nor workflow privileges should be assigned directly, except for the WebDAV privilege 'read' which is usually used to give access to folders high up in the hierarchy.

The main advantage of setting up the users, groups and permissions like this is that user management becomes very easy. When a user is no longer allowed to work on a set of documents he or she only needs to be removed from the appropriate group. New users only have to be added to the appropriate groups. No new groups are needed, and no changes to the permissions are needed.

The structure above also allows for new workflows to be introduced without having to make changes to the groups and permissions. The only thing to be done is to assign the appropriate privileges of a workflow to the roles. This is descibed in more detail below.

Now I will explain how all of the above works together with the workflow. The most important aspect of the workflow are the actions. They determine what the user is allowed to do with a document at a particular state.

The CMS supports multiple workflows. Different workflows have a lot of the same actions (for example 'save' and 'publish'). It is undesirable that when the privilege to perform 'publish' on one workflow is assigned to a role, the privilege is also given to perform 'publish' on the other workflows. By adding a namespace to an action it is possible to distinguish between the actions with the same name again. Here is an example:

  http://hippo.nl/.../reviewed-actions                  save
  http://hippo.nl/.../reviewed-actions                  publish
  http://customer.com/.../reviewed-actions-publisher    save
  http://customer.com/.../reviewed-actions-publisher    publish

In some workflows it is needed to use two workflow actions for the same user action. The best example for this is the 'save' action. Because the 'save' action is assigned to the 'author' and 'editor' roles, authors and editors are allowed to save whenever the 'save' action is enabled in the workflow. For the 'reviewed actions' we don't want authors to be able to change the document while it is waiting to be reviewed for publication. Enabling the 'save' action in the 'waiting for publication' state is therefore not possible. This is solved by adding a new workflow action called 'saveForEditor', which does exactly the same thing as 'save'. But the 'saveForEditor' action is only assigned to the 'editor' role preventing authors from invoking it.

To be able to assign workflow actions to roles, a privilege has to be created in the repository for each workflow action. These privileges are then assigned to roles (which are also privileges). The privilege to create for a workflow action must have the same simple name as the action and the namespace must match the 'namespaceUri' specified in the metadata of the action.

The CMS uses the 'current-user-privilege-set' property of a document to get the privileges a user has for a document. This property recursively expands the directly assigned privileges to get all the effective privileges. The names and namespaces of the privileges returned by this property are used to match against the workflow actions. If a privilege matches with a workflow action then it is allowed to appear in the workflow actions box, or it may be executed.

All privileges are stored as folders beneath 'actions' in Slide. The multi-level folder structure that gets created is optional. The structure is only created so the privileges are neatly organized. Only the namespace, which is assigned to property 'privilege-namespace' of the privilege folder, is used to determine whether or not a workflow action matches a privilege.

The 'slideLocation' specified in the metadata of a workflow action is intended to specify the folder in which to put the privilege for the action. It is not used at this moment, but the CMS will be extended to automatically create the privileges for the workflow actions. The 'slideLocation' property of the workflow action will be used then.

Just like the workfow actions, the roles are also privileges. And for organisation purposes they are put in a separate folder beneath 'actions' called 'hippo-roles'. If you need different roles with different workflow action assignments it is advisable to create a separate set of roles in a separate folder beneath 'actions'.

When the privileges for the workflow actions and the roles are in place, the last thing that needs to be done is to assign privileges of workflow actions to privileges of roles. Privileges are assigned to other privileges by including them in the 'privilege-member-set' property of the privilege they should be assigned to. For the example of the recipe site the 'privilege-member-set' property of the 'author' privilege will contain amongst others:

  DAV:                                    read
  DAV:                                    write
  http://hippo.nl/.../reviewed-actions    save

And for the 'editor' privilege the property will contain amongst others:

  DAV:                                    read
  DAV:                                    write
  http://hippo.nl/.../reviewed-actions    save
  http://hippo.nl/.../reviewed-actions    publish

The creation of the privileges for the workflow actions and the roles, and the assignment of the workflow action privileges to the role privileges can be done by adapting the repository initialization tool. Don't forget to add the standard WebDAV privileges to the roles that you create.

As the CMS will display all privileges from all workflow actions and roles beneath 'actions' in the permissions screen, it is best to delete unused privileges to avoid confusion.

By combining all the data from above we can deduce the effective workflow actions a user is allowed to invoke. The table below shows the effective privileges for a subset of the folders and users. The standard privileges are also included in the table:

  Folder                       User     Privileges
  ---------------------------  -------  ---------------------------------
  recipes/desserts             Alice    read, write, save, publish, ...
  recipes/desserts/cheeses     Alice    read, write, save, publish, ...
  recipes/desserts/puddings    Alice    read, write, save, publish, ...
  recipes/desserts             Dan      read, write, save, ...
  recipes/desserts/cheeses     Dan      read, write, save, ...
  recipes/desserts/puddings    Dan      read, write, save, ...
  recipes/desserts             Ed       read, write, save, ...
  recipes/main courses         Joe      read, write, save, publish, ...

There is one more thing to consider. The actions of the workflow are executed as the user invoking them. As some workflow actions make changes to other locations in the repository than the location used by the CMS (files/<name>.preview), it is important to ensure that users are allowed to write to these locations. The locations to check are the live location (files/<name>.www), the trash location (files/<name>.trash) and the history location (files/<name>.history). Usually the standard permission 'write' is assigned to the standard group 'authenticated' for each folder. The repository initialization tool contains code which does this.