User Roles and Privileges

This page is intended to provide a useful guide on how user roles and privileges work within EPrints repository software, expanding on the information already available at user_roles.pl.

A role in EPrints is made up of 1 or more privileges. Giving a user a role gives them all the privileges associated with that role. You can also give users additional privileges without giving them the full role.

Creating a role

To create the role approve-hat you would do the following:

$c->{roles}->{"approve-hat"} = [
       "eprint/buffer/view:editor",
       "eprint/buffer/summary:editor",
       "eprint/buffer/details:editor",
       "eprint/buffer/move_archive:editor",
];

The privileges listed above means the users given the approve-hat role can see the View, Summary, Details and Move to archive screen as an editor. Note because they cannot edit items in the buffer they can't correct any mistakes they find. However they do have the power to move items to the archive. This means the approve-hat allows a user to see the metadata of an item and if they think it is correct move it to the archive. They cannot return it to the user or edit the metadata themselves.

The quoting around the role name approve-hat is required, eprints will generate an error if the text is simply {approve-hat}.

Tip: Ensure the role is in {roles} not {user_roles}!

Anatomy of a privilege

Many pre-existing privileges have a specific structure so they can be tested for generically. Privileges on data objects use the dataset ID as the first part of the privilege and the last part as the action that can be carried out on that data object. E.g.

• eprint/view
• user/edit
• saved_search/export

As the eprint data object also has virtual datasets that are subsets of the eprint dataset, based on the status of the eprints these are often used as the second part of the privilege. E.g.

• eprint/archive/view
• eprint/inbox/edit
• eprint/buffer/export

eprint and user data objects can also have an additional modifier to restrict the context in which the privilege permits access:

eprint/inbox/view:owner

A user can only view eprints that they own in the user workarea.

eprint/buffer/edit:editor

Only users with editorial scope for the eprint can edit it when it is in the review buffer

user/view:owner

A user can only view their own user profile.

config privileges are typically use the specfic privilege they give access. E.g.

• config/indexer
• config/regen_abstracts
• config/view

However, config/view and config/edit can be specialized to allow specific types of configuration file to be viewed or edited. E.g.

• config/view/phrase
• config/edit/autocomplete

Creating a privilege

There is no special step to creating a privilege, simply define it where you would like it tested for. Equally, there is no specified format for new privileges tying them to (for example) screens. As a result the following are all valid:

• "eprint/coindoi"
• "eprint/coindoiffff"
• "eprint/coindoi:editor"

However, to make sure the privilege is as intuitive as possible, it is best to stick as closely to the conventions described in "Anatomy of a privilege".

Assigning a role

Now that you have created a role you want to give that to class of users. To give every regular user of the repository the approve-hat you add it to the list of roles for the user.

$c->{user_roles}->{user} = [
        'general',
        'edit-own-record',
        'saved-searches',
        'set-password',
        'deposit',
        'change-email',
        'approve-hat',
],

Rather than giving every user the role you can give it to individual users. Administer a users profile and add the name of the role to their list of additional roles.

Assigning a user privilege

You do not have to give a user a full role you can give them a privilege. The syntax is slightly different. Add the name of the privilege prefixed with a '+' to the list of roles. You can remove a privilege by prefixing it with a '-'.

$c->{user_roles}->{user} = [
        'general',
        'edit-own-record',
        'saved-searches',
        'set-password',
        'deposit',
        'change-email',
        'approve-hat',
        '+eprint/archive/edit:owner',
],

You can also assign privileges to individual users through the web interface in the same way you can assign a role, remembering they will be listed as "roles". (remember the '+' or '-')

There is no need for users to log in again following a privilege change, eprints will pick it up automatically.

See Also

• Listings of User Roles and Privileges - A reference to role and privileges and what they allow a user to do.
• user_roles.pl - Describe the configuration file and how it may be edited/extended to modify/add new roles and privileges.
• Screen plugin visibility - Example of making a new Screen Plugin appear using roles.