ESciDoc User Roles

eSciDoc User Roles can be granted to eSciDoc users as unlimited, or limited to various resources (context, item, container) etc.

See also See also eSciDoc Admin Roles

Roles, Scopes and Actions
eSciDoc authorization component allows for a fine-grained definition of what users may do in the system. An information on how this is exactly done, can be found at ESciDoc Authorization and Authentication. Here some more exemplary and descriptive information is provided.

A Role is simply defining a set of actions which may be performed by the user. For each action associated with the role, none or several conditions (rules) can be defined. When conditions are defined, then these must be fulfilled at the time when a user tries to perform an action within the eSciDoc infrastructure.

An example of a Role, action and condition may be (as pseudo-code) defined as:

Role:     escidoc:some-role Action:   retrieve-item Condition: if-item-is-created-by-me

A Scope of the role is defining the types of resources for which the role can be granted and the types of resources for which the role is evaluated. Roles which have scopes are limited roles. Roles for which scope is not defined are unlimited roles. In both cases, none or several conditions (rules) can be defined for a role.

An example of an unlimited role is the "Default role" which is granted to each user who authenticates (is logged-in) with the eSciDoc infrastructure.

A Role may be defined for several Scopes. In this case, the privileges are validated respectively from the object for which these are granted.

An example of a role with several Scopes is the Collaborator role. This role can have Context, Item, Container or Component as a scope. When a user is granted with this role for a particular Context, then the user may perform all actions defined by the role (and its conditions) for all items, containers and components in that context. However, if a user is granted with this role for a particular Item, then the user may perform all actions defined by the role (and its conditions) only for this item and its components.

Scope:Context
When a Role is defined on scope of a Context, the actions can be performed on all applicable resources in a context.

For example, when a Collaborator role is granted to a user for a context C1, this user may retrieve all items, containers and components of the items in that context. In other example, when a Depositor role is granted to a user for a context, this user may create items and containers in this context. However, a user with this role may not retrieve all items and containers in the context. He may retrieve only released items and containers (default privilege) created by other users. He may always retrieve own items and containers in any status (Depositor role only privilege).

Scope:Item
When a Role is defined on scope of an Item, the actions can be performed only on Item for which the role has been granted and, optionally, on the components of that item.

Scope:Component
When a Role is defined on scope of a Component, the actions can be performed only on the Component for which the role has been granted. When Scope is defined for a Component following is always enforced:
 * the retrieval of the enclosing item is automatically allowed
 * the retrieval of the other components of the enclosing item is not automatically allowed
 * the retrieval of the component means: retrieval of the binary content of an internally managed component (e.g. the content of the uploaded file)
 * the retrieval of the component does not always mean: retrieval of the externally referenced content (e.g. locator in PubMan).

For example, sometimes the URL of the content of the component may point to external storage. The external system may apply own authorization (independently on the component visibility defined in eSciDoc).

Scope:Container
When a Role is defined on scope of a Container, the actions can be performed only on the Container. Depending on the conditions and character of the Role, sometimes actions can be performed also on members of the container (direct or on any level of the container hierarchy).

Agreement on Withdrawn status
When item or container is in status "withdrawn" - no actions are allowed (except retrieval). For items which have components, retrieval of the component content is not allowed. If the role is otherwise defined - this will be stated in the role definition.

For example, action described as "add/remove members to/from the container" or "update-item" may only be performed if the container (respectively the item) is not in status "withdrawn".

Default role (default privileges)
Each eSciDoc user is granted with the default role whenever using any eSciDoc service (authenticated with known account or simply as anonymous user). Here description of what default role allows. This role should not be explicitly granted to any user. This is automatically granted to every user of the eSciDoc infrastructure. Each user of eSciDoc infrastructure is allowed to:


 * retrieve released items and containers
 * retrieve all released versions of items and containers
 * retrieve contexts in the public-status open and closed
 * retrieve content models
 * retrieve components with public visibility of released items (or any released version of the item)
 * retrieve organizational-units in status open and closed
 * retrieve own user-account (if the user has been authenticated) and own grants
 * log-in and logout with valid username and password
 * unlock items that she/he has locked.
 * unlock containers that she/he has locked.
 * retrieve OAI-PMH set definitions
 * retrieve repository information
 * retrieve statistic-reports if she/he is in the role permitted by the record-definition
 * create grants on own contexts, items (and components) or containers
 * revoke grants she/he created
 * retrieve grants she/he created
 * retrieve grants of groups she/he is a member of
 * search items, containers and organizational units

Audience

 * Role-ID: escidoc:role-audience
 * Action/Condition:
 * retrieve content of components (files) with visibility "restricted" if the enclosing item is released
 * Scope of assignment:- can be assigned to a user or a user group for following resources:
 * Component of a released item
 * Context
 * See also:
 * Note on Withdrawn status
 * Default privileges

Examples of application

 * Publication has attached a fulltext with visibility set to "Restricted". In PubMan "Sharing tab" the depositor or the moderator of the item may define to which user groups this fulltext is accessible after the item is released. For each file which is associated with the publication item, different level of restriction may be defined.

Used by

 * PubMan

Collaborator roles
There are several types of collaborator roles, depending on the level of privilege user wants to grant to a certain set of items or containers.

Collaborator

 * Role-ID: escidoc:role-collaborator
 * Action/Condition:
 * retrieve items and containers in any status (pending, submitted, released, withdrawn)
 * retrieve item components (i.e. files) in any visibility when item is not withdrawn
 * Scope of assignment: - can be assigned to a user or a user group on objects of following types:
 * Component
 * Item
 * Container
 * Context
 * See also:
 * Note on Withdrawn status
 * Default privileges

Examples of application

 * An example use case may be a a working group who shares all of their resources for internal use before these are released.

Used-by

 * not yet used by any solution. Planned usage: PubMan, FACES

Collaborator modifier

 * Role-ID: escidoc:role-collaborator-modifier
 * Includes rights from: escidoc:role-collaborator
 * Action/Condition:
 * retrieve items and containers in any status (pending, submitted, released, withdrawn)
 * retrieve item components (i.e. files) in any visibility
 * update items (and their components) and containers
 * lock/unlock items and containers
 * Scope of assignment: - can be assigned to a user or a user group on objects of following types:
 * Item
 * Container
 * Context
 * See also:
 * Note on Withdrawn status
 * Default privileges

Examples of application

 * An example use case may be a a working group who shares and collaboratively modifies their resources.

Used-by

 * not yet used by any solution. Planned usage: PubMan, FACES

Collaborator modifier container-add-remove-members

 * Role-ID: escidoc:role-collaborator-modifier-container-add-remove-members
 * Action/Condition:
 * retrieve container in any status (pending, submitted, released, withdrawn)
 * update container
 * add/remove members to/from the container
 * lock/unlock container
 * Scope of assignment: - can be assigned to a user or a user group on objects of following types:
 * Container
 * See also:
 * Note on Withdrawn status
 * Default privileges

Examples of application

 * An example use case may be a a working group who shares and collaboratively modifies an album of images, or collection of various resources. The working group does not have right to modify the images in the collection. Some members of the working group may not see images other members added (if there are not suffucient privileges granted from other roles) - in this case they may only see the references to these images.
 * If the container has sub-container as a member, this role does not allow to add members to the sub-container.

Used-by

 * not yet used by any solution. Planned usage: FACES, VIRR

Collaborator modifier container-add-remove-any-members

 * Role-ID: escidoc:role-collaborator-modifier-container-add-remove-any-members
 * Action/Condition:
 * retrieve container in any status (pending, submitted, released, withdrawn)
 * retrieve any items which are members of the container (including sub-containers)
 * retrieve any components of the items which are members of the container (including sub-containers)
 * retrieve any containers which are members of the container (including sub-containers)
 * update container
 * add/remove members to/from the container (and to any sub-containers)
 * lock/unlock container (or sub-containers)
 * Scope of assignment: - can be assigned to a user or a user group on objects of following types:
 * Container
 * See also:
 * Note on Withdrawn status
 * Default privileges

Examples of application

 * An example use case may be a a working group who shares and collaboratively modifies an album of images, or collection of various resources, some of which can be collections themselves. The working group does not have right to modify the images in the collection or in the sub-collections.

Used-by

 * not yet used by any solution. Planned usage: FACES, VIRR

Collaborator modifier container-update-direct-members

 * Role-ID: escidoc:role-collaborator-modifier-container-add-remove-members
 * Includes rights from: escidoc:role-collaborator-modifier-container-add-remove-members
 * Action/Condition:
 * retrieve container in any status (pending, submitted, released, withdrawn)
 * update container
 * add/remove members to/from the specified container
 * update any items or containers that are direct members of the specified container
 * lock/unlock container and its direct members
 * Scope of assignment: - can be assigned to a user or a user group on following types of objects:
 * Container
 * See also:
 * Note on Withdrawn status
 * Default privileges

Examples of application
An example use case may be a a working group who shares and collaboratively modifies an album of images. The working group may additionally modify the images in the collection.

If the collection has sub-collections as a member, this role does not allow to add or modify the members of the sub-collection.

Used-by

 * not yet used by any solution. Planned usage: FACES, VIRR

Collaborator modifier container-update-any-members

 * Role-ID: escidoc:role-collaborator-modifier-container-update-any-members
 * Includes rights from: escidoc:role-collaborator-modifier-container-add-remove-any-members
 * Action/Condition:
 * retrieve container in any status (pending, submitted, released, withdrawn)
 * retrieve any items which are members of the container (including members of sub-containers)
 * retrieve any components of the items which are members of the container (including members of sub-containers)
 * retrieve any containers which are members of the container (including members of sub-containers)
 * update container
 * add/remove members to/from the container (and any sub-containers)
 * lock/unlock container
 * update any members of the container (including members of sub-containers)
 * lock/unlock any members of the container (including members of sub-containers)
 * Scope of assignment: - can be assigned to a user or a user group on following levels:
 * Container
 * See also:
 * Note on Withdrawn status
 * Default privileges

Examples of application
An example use case may be a a working group who shares and collaboratively modifies a multivolume collection of volumes and books. The working group can modify all resources associated with any level starting from the multivolume i.e. to the multivolume, all volumes and books.

Used-by

 * not yet used by any solution. Planned usage: FACES, VIRR

Depositor

 * Role-ID: escidoc:role-depositor
 * Action/Condition:
 * create items and components (files, locators)
 * create containers
 * retrieve items he created (own items) in any status (pending, submitted, in-revision, released, withdrawn), including the components of these items
 * retrieve containers he created (own containers) in any status
 * update own items
 * update own containers
 * add/remove members to own containers
 * delete own items and containers if their status is "pending" or "in-revision" (and if there are no previous versions with status "released")
 * submit, release and withdraw own items and containers
 * lock own items and containers
 * unlock own items and containers (if the lock owner as well)


 * Scope of assignment: - can be assigned to a user or a user group on following levels:
 * Context
 * See also:
 * Note on Withdrawn status
 * Default privileges

Examples of application
A Researcher may deposit publications in several contexts. For example, context of MPI publications and a context of non-MPI publications. His publications he may always see (and accordingly to the workflow modify, submit or release) from PubMan MyItems workspace.

Used-by

 * PubMan, FACES, VIRR

Moderator

 * Role-ID: escidoc:role-moderator (of a context)
 * Action/Condition:
 * retrieve items with status (submitted, released, in-revision, withdrawn), including the components of these items
 * retrieve containers he moderates with status (submitted, released, in-revision, withdrawn)
 * update items in status "submitted", "released"
 * update containers in status "submitted", "released"
 * add/remove members to containers in status "submitted", "released"
 * submit items and containers he modified
 * release items and containers
 * revise items and containers (if submitted)
 * withdraw items and containers (if released)


 * Scope of assignment: - can be assigned to a user or a user group on following levels:
 * Context
 * See also:
 * Note on Withdrawn status
 * Default privileges

Examples of application
A Librarian is moderator of a context. As such, she may modify and accept the publications created by depositor. As moderator of the context, she may also send back the publication for a rework. Moderated items are available via e.g. PubMan QA Workspace.

Used-by

 * PubMan, FACES, VIRR

Privileged viewer

 * Role-ID: escidoc:role-privileged-viewer
 * Action/Condition:
 * retrieve content of components (files) with any visibility (for items he may retrieve in accordance with other privileges)
 * Scope of assignment:- can be assigned to a user or a user group for following resources:
 * Context
 * See also:
 * Note on Withdrawn status
 * Default privileges

Examples of application

 * Publication has attached a fulltext with visibility set to "Restricted" or "Private". The user who has "Privileged viewer" role granted, may see all files (public, restricted or private) of all items he may access.

Used by

 * PubMan, FACES

CoNE roles
There are two roles granting edit rights for CoNE vocabularies to the user.

CoNE-Open-Vocabulary-Editor

 * Role-ID: escidoc:role-cone-open-vocabulary-editor
 * Action/Condition:
 * add/modify/delete CoNE entries for open CoNE vocabularies such as journals or persons.
 * Scope of assignment: - can be assigned to a user without a scope

Used-by

 * used by the CoNE service

CoNE-Closed-Vocabulary-Editor

 * Role-ID: escidoc:role-cone-closed-vocabulary-editor
 * Action/Condition:
 * add/modify/delete CoNE entries for closed CoNE vocabularies such as languages or subject classifications.
 * Scope of assignment: - can be assigned to a user without a scope

Used-by

 * used by the CoNE service

Reporter

 * Role-ID: escidoc:role-reporter
 * Action/Condition:
 * invoke the Reporting workspace in a solution


 * Scope of assignment: - can be assigned to a user or a user group - unlimited role
 * See also:
 * Note on Withdrawn status
 * Default privileges

Examples of application
A Researcher may invoke the Reporting workspace in a solution and execute all reports in this workspace (items in the reports based on the privileges for items).

Used-by

 * PubMan