Introduction

Whether you’re a developer new to the Web Development Kit (WDK) or you’re a system administrator trying to be efficient in your Documentum user management, you may have wondered why there are both groups and roles. This article explores the differences between them, and provides some guidance on how to decide when to use a group or a role.

In the Beginning, there were Groups

Groups are a convenient way of aggregating individual users, thereby simplifying the process of managing permissions. Specifically, groups can be used in the following ways:

• In conjunction with an Access Control List (ACL) to assign object-level permissions to all members of the group
• As the owner of a document to allow all members of the group to have ownership
• As the performer of a workflow task to allow that task to be delivered to all members of the group (or optionally the first to receive it)

The Content Server Fundamentals manual provides the following example of using groups to control permissions: you might set up a group called engr and assign version permission to the engr group in an ACL applied to all engineering documents. All members of the engr group then have version permission on engineering documents.

Groups contain the following properties:

• Name: the name of the Docbase group
• Class: the type of group (added in Content Server 5 – more on this later)
• Email address: the address for the group. If no value is entered, the group email address defaults to the group name.
• Owner: the name of the Docbase owner who owns this group (most groups are owned by the Docbase owner, but normal users can have their own groups as well, although this feature is rarely used)
• Administrator: specifies a user or group, in addition to a superuser and the group owner, who can modify the group (this allows a manager to maintain group membership without having system administration privileges to the rest of the system)
• Alias set: the default alias set for the group (used in certain cases to resolve an Alias Set’s scope)
• Group is Global: indicates that the group is displayed only in the governing Docbase of a federation
• Description: a user-friendly description of the group
• Is Private: defines whether the group is private or public. Public groups are visible to all users, while a private group is visible only to the owner of the group.

And to make your user management even more flexible, a group can belong to another group, facilitating a hierarchical user structure within which individual users and groups can be combined in the same group.

Along Came Roles

The release of Content Server 5 ushered in the era of roles. A role is a special type of group. Prior to roles, there was only one type of group, now called a standard group. This type of group is used to assign object-level permissions and participation in workflows as described above.

Version 5 added two new types of groups, a role group and a domain group:

Since a role is a specialized group, roles contain the same nine properties as groups, with restrictions on two of the properties (name and class) as discussed above.

Summary of the Differences

We’ve been focusing on the fact that roles are just a special type of group. So let’s summarize by highlighting the differences:

Again we turn to the Content Server Fundamentals manual for an example of using roles and domains to control function permissions. Suppose you write a client application called report_generator that recognizes three roles: readers (users who read reports), writers (users who write and generate reports), and administrators (users who administer the application). To support the roles, you create three role groups, one for each role. The group_class is set to role for these groups, and the group names are the names of the roles: readers, writers, and administrators. Then, create a domain group by creating a group whose group_class is domain and whose group name is the name of the domain. In this case, the domain name is report_generator. The three role groups are the members of the report_generator domain group.

When a user starts the report_generator application, the application is responsible for examining its associated domain group and determining the role group to which the user belongs. The application is also responsible for ensuring that the user performs only the actions allowed for members of that role group. Content Server does not enforce client application roles, since this responsibility is delegated to the application via the domain group.

Once the roles exist in your Docbase, they can be reused across applications. Just create a new domain group and add any of the existing role groups (readers, writers, and administrators in the example above) to the new domain group.

Roles in Web Publisher

Web Publisher is already configured with the roles that are defined in the Web Publisher doc app:

• wcm_content_author_role
• wcm_content_manager_role
• wcm_web_developer_role
• wcm_administrator_role

Web publisher uses these roles to determine which features are available to the user. For example, content authors are not allowed to see cabinets and folders, while content managers can. Content managers are not allowed to access administrative features, while administrators can. These out-of-the-box roles are ready to be used within any Web Publisher application, and they can be extended if needed. Plus, you can create new roles as needed.

Roles in WebTop

Webtop and WDK components can be configured to use any role that is defined in the associated Docbase. If no roles are configured in the Docbase, or if the Docbase is pre-5.1, Webtop defaults to using the client capability model in which four client capability levels can be set as client_capability attributes on the dm_user object in the Docbase:

• consumer
• contributor
• coordinator
• administrator

If you create role groups in the Docbase, you can create roles named consumer, contributor, coordinator, and administrator. Your custom roles can contain these roles (or vice-versa), so that Webtop and WDK components will not need to be reconfigured for your custom roles.