User roles and rights

From Dokeos

Jump to: navigation, search
Overview for a specific role (platform admin section)
Overview for a specific role (platform admin section)
List of users and their role in a course (course admin view)
List of users and their role in a course (course admin view)
Overview of course rights (course admin view)
Overview of course rights (course admin view)

This page describes a software design that will give us

  • clearly defined default user roles in Dokeos
  • the ability to define new user roles and assign these roles to users
  • the ability to define exactly what rights or permissions each role has
  • localisation, local roles (see further) can have different rights in different locations - in different places in Dokeos like courses or document folders or...

Contents

Status

We've been discussing and improving the design for a while now. A general framework was written and presented on the developers meeting of August 2005. These ideas were accepted and this design page has been adapted to those new ideas. The design is being worked out further, which happens gradually along with the implementation. The basics should be clear now; the design will continously be improved the following months.

Implementation began in October 2005. A basic workable system has been implemented in Dokeos community release 2.0, and we've made several improvements in Dokeos community release 2.1. The implementation is still not perfect nor complete nor bugfree, we will improve it in upcoming versions. By releasing partially-complete code we can gather lots of feedback early, also about the interface; and we will also provide users with a real-world implementation that can be tested instead of a design that is only theoretical.

Features available in Community Release 2.0

General

  • Basic support for local roles, rights, locations
  • Users who enroll in a course are assigned a local role
  • Users not enrolled in a course get assigned a local role automatically when they visit one: users who are not logged in into the platform get the anonymous guest visitor role, logged in users get the registered guest visitor role
  • Upgrade code for this system

Platform admin section

  • the platform admin can adjust values for all roles / rights / locations
  • the platform admin can set default values for newly created courses and their tools; these values are used when a new course is created

Course Area

  • course admins can see and edit the local role of users in their courses through the user tool
  • course admins can see an overview of the roles/rights in their course and edit the values
  • the teacher / student view switch is now a list that allows course admins to choose any role to view their course (works, but not 100%)
  • global roles are hidden from user interface until they have some use
  • many of the normal (usable by students) course tools are converted to use the roles/rights system
  • Course visibility settings (open to the world|platform|enrolled users|course admin only) and course tool visibility setings (using the eye icon on the course homepage) are mapped to the view rights of the new system. This way, people can still set the visibility in an easy way, while those who want more options can have them as well.
  • The course homepage icons are displayed based on the view rights. The "activated" tools section shows tools made visible for the normal course member role, this means it remains easy to see for course admins which tools are availanle for students/trainees. When using the view as role feature it should show the view for the selected role.
  • A new modified visibility option in the course settings indicates changes have been made through the roles/rights interface

Help system

  • Specific online help section in course rights page
  • A roles and rights quick tutorial in the documentation folder supplied with every release (currently available in English, German, and Slovenian)

Additional features available in Community Release 2.0.1

Additional features available in Community Release 2.1

General

  • Support for global roles - multiple global roles for each user
  • My profile and Who is online show global roles

Platform admin section

  • Create new local and global roles. For local roles, you can choose an existing local role and the new role will be based on that role, with the same default settings.
  • Edit the name and description of existing roles.
  • Delete created roles. Note: you cannot delete the basic roles that are created by default, but you can change their name.
  • Add users form: specify the global role of the user
  • User list: show global roles, edit global roles

To do

More improvements and features will be added in later versions - Dokeos community release 2.2, 2.3...

General

  • (partially complete) the role/rights values set should actually be taken into account in the tool code (this will be a lot of work). Every tool needs to be analysed to allow correct use of the view, edit, add and delete rights.
  • (partially complete) Add global roles system and new locations (outside of courses)
  • (busy) A setting so the display of roles & rights specific pages can be turned off in the courses, so only platform admins get to see it (there's a setting already but this is not used everywhere, plus discussion: should platform admin still be able to see the roles-rights stuff, probably yes)
  • Course admins: optional ability to create a new local role
  • Course admins, when creating a new local role: the new role is based on another role, not just the "default" course settings should be used but settings of the course from where the role is created should also be copied (this should be given more thought).
  • Support for multiple local roles per user (multiple global roles is supported since cr 2.1)
  • Complete hierarchical location system - every location is included in the roles-rights system, not just courses and course tools. This includes things like course categories, categories in the links tool, folders in the documents tool... If a location has no rights set, the system should look higher in the hierarchy. For performance reasons, this may require a different storage implementation (see below).
  • Users who have a role that gets deleted should have that role changed into another one. Or, deleting roles that have users attached to it should not be allowed.
  • Define connection between global and local roles
  • User import through csv / xml files: role specification
  • An overview for normal users to see what rights they have in which courses
  • People who get the ability to edit the rights values in the roles and rights overview page of a course should only be able to grant rights that they have themselves.
  • Further refine default set of rights
  • Further refine user interface, listening to feedback of users
  • Find a good way to add a button/link to every tool page so course admins can adjust the rights settings there
  • More use of description of roles e.g. when one is displayed somewhere in a detail page, when editing a specific role, when changing the user's local role,...

Database design

When storing all Dokeos locations inside the system, this must be efficient and performant. Storing hundreds or thousands of locations as strings - e.g. "|platform|courses|course,001|tool,document|category,002" would be very wasteful and inefficient. Since what we are storing is essentially a tree structure, it makes sense to use computer tree storage structures and algorithms.

Help system

  • Improve online help section in course rights page and roles and rights guide in the documentation folder
  • Online help system that explains what each right means in the current tool
  • Add roles & rights guide with translations to dokeos website

Platform admin section

  • More info - currently there is much functionality but no explanation at all
  • A filter on the locations in the platform admin section, so an admin could focus on one specific role and see not all locations (there could be thousands in large systems), but just the locations of one course (this already happens automatically in the course admin overview page, which only shows the current course and its tools).
  • Course list: button to edit the rights of that course

Detailed purpose

What do we want? We want the Dokeos administrators to have complete flexibility on dealing with the various user roles that Dokeos has. The platform admin must be able to define, and change when needed, exactly what rights a user with a certain role has. In older (1.6 and earlier) Dokeos versions, there were five existing roles: platform admin, course admin, tutor, student, and guest. The tutor and guest roles were badly defined, and the rights of these roles couldn't be changed without a lot of work. This design makes it as simple as clicking on a checkbox.

Furthermore, we want the ability to define new roles, of which the settings can be changed just as easily as the predefined roles. The platform admin will be able to define new roles; optionally, other users (e.g. course administrators) can also be allowed to define new roles. The ability to define roles is a right like any other that can be granted to the various roles.

Finally, users have roles, and it's the roles they have - the hats they wear - that determine what rights they have.

Defining the rights of roles is often done through what is called the "user role - rights matrix", several e-learning or content management systems have such a system already. Of course this is just one possible visual presentation.

Situation for standard Dokeos 1.6 and 1.8

Inside Dokeos, users have a platform-wide role, but they also have a role inside each course. This role can be different inside every course, e.g. a teacher can teach three courses, but also follow some others, a student can follow five courses but also manage a course that is used as a student community, trainers can give some trainees rights to manage course material too, etc. And the notion of a group is also very important inside every course. Once again, users in a course can have different roles inside each group of this course.

Dokeos is currently very much a traditional course based e-learning system. Some organisations are looking to extend it to have more organisation levels over, outside or between courses. Some of these are called communities. This just goes to show that roles have a certain scope to them, that we need not limit to the existing platform | course | group concepts. For example, in several universities the Faculty of Medicine and Health Sciences has teaching modules very different from ordinary courses; others too are asking for "communities". Portfolios are yet another possible extension that creates new places outside courses.

Implicit roles in Dokeos 1.6/1.8 and earlier

Dokeos 1.6 does not have any configurable roles, but there are some roles used. These roles exist in Dokeos 1.6 and earlier:

Platform roles

  • Platform admin - can manage all platform settings, go everywhere, do everything
  • teacher/trainer - can create courses, of which (s)he becomes course admin
  • student - can register for courses
  • guest - can look through the list of courses set to be open for the world

Course roles

  • course admin - can do everything inside this course
  • student - can view or participate in all tools the course admin has made public
  • guest - can view or participate in all tools the course admin has made public, if the course is open for the world

Group roles

  • tutor
  • student
  • guest

Roles and locations - new situation

We are changing the design in favour of new concepts:

  • global roles and local roles
  • basic rights
  • locations

Local roles are very important in this design. Every local role has rights according to a location: their rights can differ from place to place, their rights can be different in different locations.

Example

A typical student, enrolled in 5 courses, would receive a "normal course member" role in these 5 courses she is enrolled in. The local role "normal course member" can have certain permissions in one course, and different permissions in another course. It's still the same role. This is pretty much like the current behaviour: teachers hide or show tools in their courses. They keep seeing all tools, but they change the access rights for the local "course member" role. One teacher wants (in course A) his students (the normal course member role) to see the announcements tool, another teacher (in course B) does not. The same role has different rights according to the location: the course A announcements are visible to the role, the course B announcements are not.

In Dokeos 1.7/1.8 we'll be able to make a much clearer distinction between roles. Currently it is e.g. impossible to show two tools to guest course members and five tools to normal (enrolled) course members.

To grasp the location / hierarchy idea better, you could think of Dokeos as a hierarchical filesystem. You can change access permissions on every folder. Local permission settings can be inherited from upper folders.

Two example locations are

  • Course AAA (more technically, this is stored as platform|courses|course,AAA)
  • Course AAA, Links tool (stored as platform|courses|course,AAA|tool,link)

Global roles

Every user can have one (or multiple) global roles, these count for the whole of the Dokeos platform. Local roles are specific to a certain location, e.g. a user is a guest in one course and a teachign assistant in another; but a global role - e.g. student or teacher - counts everywhere.

We can have global roles connect to local roles; e.g. if a user with global role student enrolls into a course, she automatically gets the local role of normal course member. However, if a teacher enrolls into a course of another teacher, she gets the local role of visiting teacher. This is just one example.

Local roles

  • anonymous guest course visitor (the user has no account on the platform)
  • registered guest course visitor (the user has an account on the platform, but is not enrolled in the course)
  • normal course member (the user is actually enrolled in the course)
  • teaching assistant
  • course admin

Rights

Possible rights for local roles

  • View
  • Add
  • Edit
  • Delete
  • Sort
  • Suggest
  • Review/Publish
  • Assign Local Roles
  • Create (Local) Roles
  • Change Permissions of Local Roles

For Dokeos community release 2.0 we've concentrated on four rights: view, add, edit and delete.

All the rights for local roles are specific for a certain place in the hierarchy. For example a teacher could give course members the right to add new items to the student publications tool, but not add new items to the lins tool. Or a teacher could give students the ability to suggest new items in the links tool of course A, but not the links tool of course B.

There is no "add item to links of course A" right, there is no "add item to student publications of course B" right, there is one add rights and it can be different in different places.

Since we structure Dokeos according to a hierarchy, a place in the hierarchy can also inherit the rights of higher places. This can save teachers a lot of work.

Roles - places - rights.

User interface

What do we need for platform admins? As an absolute minimum, we need pages for the platform admin to

  • manage global and local roles (add, delete, rename)
  • adding users to roles
  • set the default role of users
  • edit the rights of roles – typically done through a user role - rights matrix, but this need not be the only way

What do we need for course admins? (or more correct for any roles that have course admin rights)

  • user tool: ability to see and sort on the role of users; edit user: ability to change local role
  • manage roles: this is a tool that can be optionally activated by the platform admin to let course admins create local roles themselves. The ability to do this is a right just like all the others, that you can set for the course admin role, or perhaps create a new "course admin with rights management" role for...
  • ability to assign different local roles to users, inside the scope the course admins control (e.g. a course)
  • it's probably convenient to have an ability to create new roles based on existing ones

Since we have a roles dimension, a rights dimension, and a place (level of hierarchy) dimension, we can have a page that allows fixing one of these dimensions so the other two can be displayed in a two-dimensional table. (Or listed in list format, which is better for accessibility for some people).

Questions, limitations and possible problems

Things not worked out yet or not discussed through completely

  • Do we need to be able to change the rights of individual users?
For the moment we're not keeping this in mind. It's not hard to do, but we risk a lot of complexity increase also in the user interface. Changing the rights of an individual user can be done technically through creating a new local role and assigning that new local role to the user. Note: it's not completely necessary that e.g. course admins are aware that they are creating a new role, this could be kept hidden so the teacher thinks she is directly editing the rights of a user. Wether this is desirable is another discussion.
  • Do we need multiple roles for a certain user in a certain scope?
It's possible, and not that difficult, to do this. We don't even need a hierarchy between roles for that, we can use basic boolean logic to implement it. Once again, tool programmers need never see this complexity. We're implementing the technical possiblity to do this, but the user interface will currently limit people to have just one local role, to keep things simple.
  • Who can modify other peoples roles?
This is easy: doing so is just another right that can be set. Example: by default, users with a course admin role have the ability to change the role of the users in their course. However, on very strictly controlled systems, the platform admins define the roles and nobody else is allowed to. Simple rule for Dokeos 1.7: platform admins are able to change everything, course admins are able to change the local role of a user inside their course.
  • Is the platform admin a role?
Platform admin is a global role. Note that in Dokeos 1.6 you could already make several people platform admin (or give them the platform admin role).
  • The local roles predefined by the platform admin should be available for all courses, but not the new local roles created by the course admins themselves. These can be restricted to one course, or to all courses where that user is course admin.

Related issues

Breadcrumbs mechanism

It's not really part of this design, but there is much similarity between the way the breadcrumbs behave and the hierarchical path. Indeed, you could see the user as always being somewhere in the Dokeos hierarchy, e.g. platform / course A / tool B. This is also more or less what the breadcrumbs currently display.

The hierarchy will have to be very clear to users, since it is very important that e.g. teachers set the rights for the correct level, etc.

Hierarchy and sharing

René: We should be very careful to preserve the possibility of sharing. For example, platform / course A / tool B / folder C might (in a future Dokeos version) be the same as platform / course X / tool B / folder C, i.e. folder C is shared between the B tools of both courses.

This also means that 'hierarchy' is strictly speaking not a real hierarchy, this folder nesting with sharing constitutes a directed acyclic graph (a "DAG") rather than a tree.

Also, the implementation should preserve the possibility that the top levels will not necessarily always be platform / course / tool. In a future version of Dokeos, additional levels might be implemented (depending on institution needs) between platform and some courses and between some courses and some tools.

The combination of (1) shared folders and (2) inheritance of rights leads to multiple inheritance, but that does not need to be frightening. Rights inherited via multiple folder hierarchies can be added to each other just like user rights when a user has multiple roles.

Implementation for Dokeos community release 2.0 and 2.1

The system will be made hierarchical so you could set permissions for certain roles at course level (easy), and for those teachers who want it set more fine-grained permissions at tool level. The course and tool levels are available in community release 2.0. In the future we'll extend the hierarchical system deeper down, to units of tools e.g. forum categories or threads, document folders...

We have improved the design through ideas Frederik learned from Plone/Zope (see presentation).

What is not possible (yet)

This section is outdated These are a list of things we already know the current implementation does not take into account. These may be left out entirely, to keep things simple, or added later (either in the standard Dokeos releases or as plugins).

  • global roles are not used yet, due to lack of time before the 1.7 release. These will be added later.
  • locations are currently restricted to the courses and their tools. A deeper hierarchy of locations will be added later.
  • multiple local roles for a user in the same course - the storage structure supports it, but the user interface does not allow it. Reason it's left out: would make things very complex, there is no clear design for this yet.
  • restrictions on what rights course admins can modify: they will be able to edit all rights for all local roles in their course in Dokeos 1.7. The platform admin cannot, for example, set restrictions the course admin cannot change. Reason it's left out: this cannot be implemented in time for 1.7, it will increase complexity, there is no clear design for this yet (forum discussions about this: [2] and [3]).

Tools converted to the new system

Tools or locations that take the view, edit, add and delete rights into account:

  • Agenda
  • Announcements
  • Course description
  • Course homepage
  • Course navigation menu
  • Documents
  • Exercise
  • (busy) Forum and forum admin
  • Introduction section in all tools
  • (busy) Learning path
  • Links
  • Student publications
  • Users

In addition, the Dropbox takes the view right into account, but not the other rights yet. Mostly these are the tools visible by students. Other tools that are only used by the course admin are not converted yet.

Hierarchy / locales

We will put all courses under the hierarchy platform/courses; e.g. platform/courses/COURSE001

this way

  • we can set default rights for roles in all courses, e.g. "view" for normal course member role is true in platform/courses
  • we can add other things outside the courses hierarchy without problem, be it platform/community/... or platform/portfolio/...

Database structure

Role table

  • role id
  • role name
  • role description
  • role type (global / local)
  • created by (user id)

Rights table

  • right id
  • right name
  • right description

Location table

  • location id
  • location (this is a string, e.g. platform|courses|course,7019|tool,forum)

Relationship users / roles

We need a table to store which users have which roles. This is a many to many relationship. Since local roles are connected to a location, we need to store that as well.

  • user id
  • role id
  • location id

Relationship role/right/location

There are many roles, many rights, and many locations. For every combination of role - right - location, there is also the value of it: is the right set or not (true or false) for that role in that location?

  • role id
  • right id
  • location id'
  • value (true/false) (1/0)

Performance

Speed can be an issue here; SQL queries are often the slowest parts in Dokeos. Luckily it is possible to cache results, we should look into that too.

What we need to take into account is that we can be searching for multiple hierarchies: if we can't find a view setting for that role and hierarchy (course,7019|tool,forum|category,5) then we should look for one level higher (course,7019|tool,forum) and so on. Is it possible to find a storage system that would give us always the best level of hierarchy in one query?

Other considerations

To do: possibility to make roles language independent so they can be translated. This is easy for the predefined roles, they can be translated just like e.g. course tools, but how do we deal with newly created roles? The database design is for the most part not that difficult. There is one difficulty and that is the hierarchical aspect. Roles do not just have rights that are set or not set, this is different for every level of hierarchy.

Code

There is a function library to help programmers deal with all this, so most complexity is hidden from them. All they usually need to know is whether a certain user has the rights to perform some action. The library is called role_right.lib.php on the filesystem, but you don't need to include it yourself in your scripts, it is included automatically when you include the global init file: 

include('../inc/claro_init_global.inc.php');

Otherwise, the library can be added to your code in this way: 

require_once(api_get_library_path().'/role_right.lib.php');

You can access the library functions by adding RolesRights:: in front of their names (they are inside a class). Example: 

RolesRights::is_allowed($role_id, $right_id, $location_id)

If you are interested in one specific right, you can use 

$is_allowed_to_edit = RolesRights::is_allowed($role_id, EDIT_RIGHT, $location_id);

But more often, inside a tool, you want to know what the user's values are for all rights. So then you use 

$is_allowed = RolesRights::is_allowed_which_rights($role_id, $location_id);

the function returns an array, with as indices the ids of all the rights. These are defined as constants in the roles/rights library, so you can write 

if ($is_allowed[ADD_RIGHT]) ...
if ($is_allowed[DELETE_RIGHT]) ...

and so on (the other two rights currently defined are VIEW_RIGHT and EDIT_RIGHT).

You need 2 parameters for the RolesRights::is_allowed_which_rights function: the role id, and the location id. There are functions in the library that help you determine this. The following piece of code demonstrates this: 

$user_id = api_get_user_id();
$course_id = api_get_course_id();
$role_id = RolesRights::get_local_user_role_id($user_id, $course_id);
$location_id = RolesRights::get_course_tool_location_id($course_id, TOOL_STUDENTPUBLICATION);
$is_allowed = RolesRights::is_allowed_which_rights($role_id, $location_id);

The above code however only takes one real course into account. We've added support for users in virtual courses as well, replacing 

$role_id = RolesRights::get_local_user_role_id($user_id, $course_id);

by 

$role_id = CourseManager::determine_local_role_in_course($user_id, $course_id, $is_courseMember);

Known bugs

  • FIXED December 2005 - the local role of a user - which is stored when enrolling into a course - isn't deleted when removing the user from a course
  • FIXED December 2005 - anonymous visitors do not get assigned a local role yet
  • FIXED December 2005 - it was possible to do some URL hacking and add view_as_role to the url so any anonymous visitor could get course admin rights
  • FIXED Januari 2006 - the upgrade procedure wrongly assumes the view right for the course tools of all courses is still the same as the default view right settings.
  • More bugs and fixes can be found on the Dokeos forum, in the Community release bugs section

See also

Retrieved from "http://www.dokeos.com/wiki/index.php/User_roles_and_rights"
Personal tools