Configuring permissions

DOCman comes with powerful yet easy-to-use groups and permission system that can be configured for supporting the most common types of use-cases and then some. This article provides an introduction on how the system works and how to configure it.

DOCman permissions can be configured through the global settings and on individual categories. You may use the settings permissions UI for configuring permissions globally and then fine tune or override permissions rules in specific categories.

Configuration permissions can be hard, to make things simple and easy DOCman will automatically make the necessary adjustments for you when setting permissions. The permissions system will compute if the configured permissions require changes on others permissions while also making sure that these changes cannot be undone by locking some selections.

Configuring Permissions

Global permissions

Global permissions can be set through the DOCman settings, you will find a Global permissions tab with the user groups selectors for each action on both documents and categories.

There are 3 different types of groups: regular, internal and fixedavailable which you can use to configure permissions.

Regular

Regular groups are custom groups that can be created through the wp-admin DOCman groups view. These groups are fully manageable within this view and once created they can be edited (for assigning or removing users from the group) or deleted.

Internal

Internal groups are one to one mappings for WP roles. In a vanilla WordPress install we have corresponding internal groups for the following WP roles: Author, Editor, Contributor and Subscriber. These groups cannot be managed manually in DOCman, instead they are synced, groups are added, updated and/or deleted based on changes to WP roles (including user assignments).

Fixed

Fixed groups are a special type of hardcoded groups for defining special sets of users:

• Public: guest users
• Registered: logged-in users
• Owner: document/category owners
• Admis only: site administrators

Permissions set here will affect all categories and documents. They can be thought of as the default permission settings which you can then override on one or more categories.

Admin permissions

The global permissions UI also shows an additional ADMIN section providing two groups selectors that allow you to configure access to DOCman's admin views:

Manage

Groups added here will be able to access the DOCman admin interface for managing documents and categories. Be aware though, permissions that are set on either globally or on categories will still apply. If a user in a selected group cannot see a given category, they will still not be able to see this category in the admin interface, even if their group is listed under this selector.

Configure

Grants configuration capabilities to groups listed under this selector. Configuration includes having access to DOCman settings and groups views.

In this case we allow users belonging to the Author and Editor internal groups (WP roles) to access the DOCman admin interface as managers, this means that they will only be able to see and manage documents and categories, without having access to the settings and groups views.

Category and document permissions

When editing a given category you can access the Permissions tab just above the description text editor. Here you will find a similar interface as the one available for setting global permissions.

The main difference between both interfaces is the addition of a new users selector under each action. This allows you to add individual users for each action, in addition to groups. This is very handy when you need to grant action permissions to a single user without having to add them to a group/role, nor having to create a new group/role for them.

When both groups and users are set for a given action, if the current user matches any of the two permission conditions then the action is granted.

It is also possible to set action permissions to users only by "locking" the group selector. This is made possible with the help of the fixed Admins only group which should be selected under the group selector for the action. This effectively ensures that individual users set are the only ones (other than administrators) that can execute the action. Please note that site administrators are always able to do everything and are not limited in any way by permissions settings on DOCman.

Permission Inheritance

Category permissions affect the current category (category actions) and the documents it contains (document actions). These permissions are inherited from either a parent category (if permissions are set on it) and/or from global permissions settings. Inherited permissions can then be overridden on the category itself.

• Global Permissions
  • Parent Category Permissions
    • Current Category Permissions

Permissions that are inherited show as greyed-out in the corresponding groups/users selectors, they are in a un-editable state. It is possible to override their values by simply clicking on the corresponding Override button located to the right. Likewise, clicking on the Reset button will tell the system to clear current selections and go back to the inherited state.

As mentioned above, document permissions are set in the category containing them by simply setting groups and/or users on Document action selectors. These settings affect all the documents inside the category that you are setting permissions for. Documents inside child categories will also be affected through inheritance as stated above.

In the example above users belonging to the Moderators group will be able to edit and delete documents in the current category. The same applies on children categories (by inheritance) if permissions for for these actions are not overridden down the hierarchy.

Permissions constraints

Owner group

The ownership concept is used in DOCman for allowing some specific workflows that would otherwise be impossible to achieve. This is where the Owner fixed group comes into play.

When a user uploads a document or creates a category, the user becomes the owner of that resource. By setting the Owner value in a group permission selector for a given resource/action, you are effectively allowing the execution of the action to the owner of the resource in question.

Here we are additionally granting edit permissions to document owners under the category.

Owners have also hidden document superpowers. Document owners can see their owned documents if they can see documents in the containing category regardless of the document published/scheduled state. The same applies if the user owns the category containing those documents. For example, if a user owns a category and he can see the documents inside, then unpublished, scheduled and expired documents will become visible to this user. Likewise, if the user owns a document inside the category instead, while still being able to see documents inside this category, then the document will show even if it's not published.

Learn more about  setting up a document area for logged-in users to see ownership in action

View action

The view action is by far one of the most important among all. DOCman uses a simple but important rule: users can only execute an action on document/category that they can view and thus can access.

Moderators are automatically added in the view groups selector and set in a locked state to ensure that they can see documents inside the category. Otherwise they would not be able to edit or delete the documents they cannot see.

There's only one exception to this rule and that's when uploading documents. This is a particular case where having view action allowance is not really a requirement. If you think of it, you do not need view permissions over something that does not yet exists nor you need to be able to see a given category for being able to upload documents to it. Only the add documents action really matters in this case.

Permission Examples

Workflows

More often than not you will be faced with far more complex requirements when it comes to manage your document library. The DOCman permission system provides the foundations for supporting different workflows that otherwise would be difficult or even impossible to accomodate.

Here's a short list of some very common workflows that are supported in DOCman:

• A document approval workflow where a selected group of users are allowed to upload documents, but these documents won’t get published unless a moderator approves them.
• Selling digital goods by controlling who gets access to view and download independently.
• Restrict file uploads to specific user groups where accountants in a firm can access documents from customers assigned to them.

Use cases

The permission system also makes possible to implement some common use cases that are seen often on document libraries:

• Setup a document area for logged-in users for them to only be able to see their uploaded files.
• Share documents with customers and accountants when a company needs sharing documents with their clients.
• Share documents with students and their parents so that teachers in a school can properly communicate with each by sharing specific documents available to one but not the other.

This is by no means an exhaustive list. We have some more guides for helping you setup other common workflows and use cases that require some permissions tuning. Make sure to check them out and reach to us if you need further help while configuring DOCman.