MoodleDocs - User contributions [en]

Roles FAQ

2008-07-23T03:57:30Z

Jisner: /* Do roles have an inheritance relationsip? */

{{Roles}}
==What is the definition of a...==

;Capability
:A configurable aspect of behavior. As of version 1.9 Moodle has over 200 capabilities. Each capability has a computer friendly name like [[Capabilities/mod/forum:rate|mod/forum:rate]] and a human-friendly name like "Rate posts."
;Permission
:A capability and its value considered as a pair. There are four possible values: ''Not set'' (known as ''Inherit'' in 1.7), ''Allow'', ''Prevent'', and ''Prohibit''
;Role
:A named set of permissions, for example Teacher, Student and Forum moderator
;Context
:A functional area of Moodle, such as a course, module or block

==Why isn't my role change taking effect?==

In Moodle 1.7.x and 1.8.x, role assignments and overrides do not take effect immediately. They are delayed until the next time the user logs in. Starting with Moodle 1.9, manual role assignments and overrides take effect immediately. However automatic role assignments that result from changes to certain user policies (for example, Default front page role) may be delayed until the next login.

If you are testing a new role, [[Manage_roles#Testing_a_new_role | here are some suggestions]].

Also, please check the context in which the role is assigned. Certain capabilities e.g. [[Capabilities/moodle/user:update|moodle/user:update]] may only be applied in the System context, so giving such permissions in the course context will have no effect.

==Why are all my teacher accounts automatically added as "Teachers" in all my courses?==

If a user is assigned a role in the System context (Site administration -> Users -> Permissions -> Assign system roles) or in a Course category context, then the user will have this role in ALL courses within the context. For example, a user who is assigned the Teacher role in the System context will appear as a Teacher in all courses on the site, including the Front page course.

Except in very special cases, teachers and students should be assigned their respective roles in a Course context. When these roles are assigned in a System context, it is almost always an error on the part of the administrator.

If you have accidentally assigned a System role, go to ''Administration > Users > Permissions > Assign system roles'' unassign users using the right-facing arrow button. Then re-assign the roles in the appropriate Course context.

==Why are all students enrolled in all courses?==

Either
*Users are assigned the role of student in the site/system context rather than the course context (see FAQ above)
Or
*The default role for all users in ''Administration > Users > Permissions > User policies'' is set to Student rather than Authenticated user (Moodle 1.8 onwards).

==Why are there differences in the users listed as course participants and users assigned roles in a course?==

Users assigned roles in a higher context, for example users assigned the role of teacher in a course category context, may appear as course participants. The discussion [http://moodle.org/mod/forum/discuss.php?d=59900 Discrepancies between Assign Roles lists and Participants list] contains a longer explanation.

==How can I prevent administrators being listed as course participants?==

Ensure that administrators are not assigned another role in addition to their admin role.

==Why are hidden assignments still visible?==

Hidden assignments are not hidden from admins or teachers i.e. users with the [[Capabilities/moodle/role:viewhiddenassigns|viewhiddenassigns capability]].

==What is the difference between Prevent and Not set?==

If a role has capability ''X = Not set'', then the role is saying "I don't care about X." If a role has ''X = Prevent,'' then the role is saying "I don't want you be able to do X." Now you typically have multiple roles in a given context, and those roles may have different opinions about ''X''. If ALL of your roles have ''X = Not set'' then you will be effectively prevented from doing ''X'' because you need positive permission to do something. It's just like an election. If you are a candidate but no one votes, you don't win the election. If all of your roles except for one has ''X = Not set'' and the remaining role has ''X = Allow'', then you will be allowed to do X. Again, it's like an election where only one person votes, and they vote for you! For more complicated cases (e.g., roles assigned and overridden in different contexts) you need to understand [[How permissions are calculated]], but the principle is the same: By not voting, a role can allow other roles to determine the outcome of the election. Roles with lots of permissions Not set tend to mix well with other roles.

==What is my role here?==

This is a frequently asked question, but an improper one. The correct question is "What are my ''permissions'' here?" In any given context, you often have two or more roles. In addition, one or more role overrides may be in effect. Your permissions in a given context are a result of "adding" the individual permissions from these roles and overrides according to certain rules. As Tim Hunt writes in [http://moodle.org/mod/forum/discuss.php?d=90140 this discussion], the rules "normally do what you expect." However when permissions conflict, the results can be surprising, and it pays to understand [[How permissions are calculated]].

==How do I debug a roles-related problem?==

If you're having a problem that you suspect is related to roles, consider using [[The rolesdebug.php roles debugging script | the rolesdebug.php roles debugging script]]. You can download it from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and plugins database]. The script gives you a spatial view of your role assignments and overrides in a given context, and analyzes your permissions there. To interpret the output requires a basic understanding of roles and capabilities. If you are a complete roles novice, run the script and post the output to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities Forum].

==How can I prevent a user from changing their own password?==

To prevent a user from changing their own password, you must make sure they do not have moodle/user:changeownpassword ("Change own password") = Allow in the System context. The Authenticated user role (which is assigned to users in the System context) has moodle/user:changeownpassword = Allow by default, so you have two choices:
# edit Authenticated user, setting moodle/user:changeownpassword = Not set
# create a new role CannotChangeOwnPassword with moodle/user:changeownpassword = Prevent and all other permissions Not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (1) will prevent ''all'' users from changing their passwords (except for the administrator, who can do anything). To selectively allow selected users (say teachers) to change their passwords, you could create a new role CanChangeOwnPassword with moodle/user:changeownpassword = Allow and all other permissions not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (2) allows you to be selective, but if you have a lot of users that you want to prevent (say, all students), you will have to make a lot of role assignments in the System context. There is currently no convenient way to do this, so you might consider choice (1).

Note that you MUST deal with this permission in the System context.

==How can I prevent a user from editing their own profile?==

See [[Roles_FAQ#How can I prevent a user from changing their own password? | How can I prevent a user from changing their own password?]] The answer to this question is the same if you substitute ''edit their own profile'' for ''change their own password'' and ''moodle/user:editownprofile'' for ''moodle/user:changeownpassword.''

==Do roles have an inheritance relationship?==

No. Roles are completely independent.

* When you create a new role by copying an existing role, it is just like copying a file: the original and the copy are identical at the outset, but the copy has no ongoing relationship with the original. Changes to the original do not affect the copy and ''vice versa''.
* When you create a new role and select a value such as LEGACY:Student from the Legacy role type dropdown, you are not "inheriting" from the Student role. You are simply indicating that you want your role to have the same defaults as Student.
* Course creator does not "inherit" from Teacher (a common misconception). As with all roles, the two roles are completely independent. Course creator is actually a very simple role that can basically only create courses and not much else. However a user who creates a course is automatically assigned the role of Teacher in the newly-created course. This is how a course creator gets her teaching abilities within a course.

==Are there any differences in Roles in Moodle 1.7 and 1.8?==

In addition to many Roles fixes and refinements (see the list of [http://tracker.moodle.org/secure/IssueNavigator.jspa?mode=hide&requestId=10221 Roles improvements] in the Tracker), in Moodle 1.8 the ''system'' context is separated from the ''front page'' context. Roles may be assigned in the front page context via ''Administration > Front Page > Front Page roles''.

A "Duplicate role" button has been added in Moodle 1.8, which makes creating new roles based on predefined roles much quicker.

==How do I change the name for "teacher" in the course description?==

Either
* Edit the role of Teacher via ''Administration > Users > Permissions > Define roles'' and rename it. The new name will apply site-wide.
Or
* Create a duplicate teacher role with an alternative name and assign users the duplicate teacher role as appropriate in the course context. In ''Administration > Appearance > Course manager'' select the alternative name for teacher that you wish to be displayed in the course description.
Or
* One more way to do it in 1.8 is to create new "dummy" roles (no capabilities) with those names and assign them to teachers along with the real roles. In the course manager settings you can choose which roles display on the front page under each course. (The feature request [http://tracker.moodle.org/browse/MDL-9182 Ability to assign or display custom title for role of person in course] contains this further method.)

{{Moodle 1.9}}From Moodle 1.9 onwards, names for different roles in a course may be changed in the [[Course settings|course settings]].

==How do I enable teachers to set role overrides?==

#Access ''Administration > Users > Permissions > Define roles''.
#Edit the teacher role and change the capability [[Capabilities/moodle/role:override|moodle/role:override]] to allow.
#Click the button "Save changes".
#Click the tab "Allow role overrides" (in ''Administration > Users > Permissions > Define roles'').
#Check the appropriate box to allow a teacher to override the student role.
#Click the button "Save changes".

==How do I enable teachers to assign other teachers in a course?==

This is disabled by default but it can be switched on by modifying the teacher's role. In ''Administration > Users > Permissions > Define roles'' select the "Allow role assignments" tab and tick the checkbox where Teacher and Teacher intersect.

==Why doesn't "Switch role to.." within a course seem to work properly for a course creator?==

This feature is intended for teachers so that they can see how their course appears for students. It doesn't work reliably outside the course.

Further information about this feature can be found in [[Switch roles]] and the paragraph on testing a new role in [[Manage roles]].

==Are there any example roles?==

Yes, as follows:

*[[Inspector role|Inspector]] - for providing external inspectors with permission to view all courses (without being required to enrol)
*[[Parent role|Parent]] - for providing parents/mentors/tutors with permission to view certain information about their children/mentees/tutees
*[[Demo teacher role|Demo teacher]] - for providing a demonstration teacher account with a password which can't be changed
*[[Forum moderator role|Forum moderator]] - for providing a user with permission in a particular forum to edit or delete forum posts, split discussions and move discussions to other forums
*[[Calendar editor role|Calendar editor]] - for providing a user with permission to add site events to the calendar
*[[Blogger role|Blogger]] - for limiting blogging to specific users only
*[[Quiz user with unlimited time role|Quiz user with unlimited time]] - for allowing a user unlimited time to attempt a quiz which has a time limit set
*[[Question creator role|Question creator]] - for enabling students to create questions for use in quizzes

==Logged-in users can't read the site news. What can I do?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override permissions" link
#Click on "Authenticated User"
#Scroll down to '''Forum'''
#Change the capability [[Capabilities/mod/forum:viewdiscussion|mod/forum:viewdiscussion]] to ''allow''
#Click the "Save changes" button at the bottom of the page

Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I enable logged-in users to participate in front page activities?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override roles" link
#Click on "Authenticated User"
#Change capabilities to ''allow'' for all required activities e.g. record a choice, reply to posts
#Click the "Save changes" button at the bottom of the page

Note that for this to work, you need to make the default role for all users "authenticated user". This is the default for new versions of Moodle. In older versions, the default setting is guest, so if you have recently upgraded, you may have to change this setting. You can change the setting via ''Site Administration > Permissions > User Policies''.

Or:
#Access ''Site Administration > Front Page > Front Page roles''
#Click on Student
#Select all users in the potential users list, and use the left-facing arrow button to add them to the existing users list

{{Moodle 1.9}}Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I copy a custom role from one Moodle site to another==

There is no import and export facility for roles, but it can be achieved nearly as easily using backup and restore.

# Create an empty course with all the default settings
# Assign anybody to your custom role (or roles) within the course
# Backup the course (all defaults are fine)
# Download the backup file
# Upload the backup file to the site files of the target Moodle
# Restore the course (all defaults are fine)
# Delete the course.

You will find that the custom roles have been recreated in the target site.

==See also==

*Using Moodle [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]

[[Category:FAQ]]

[[de:Rollen FAQ]]
[[es:FAQ_roles]]
[[fr:FAQ des rôles]]
[[ja:ロールFAQ]]
[[ru:FAQ по ролям]]

Roles FAQ

2008-07-22T16:48:54Z

Jisner: /* Do roles have an inheritance relationsip? */

{{Roles}}
==What is the definition of a...==

;Capability
:A configurable aspect of behavior. As of version 1.9 Moodle has over 200 capabilities. Each capability has a computer friendly name like [[Capabilities/mod/forum:rate|mod/forum:rate]] and a human-friendly name like "Rate posts."
;Permission
:A capability and its value considered as a pair. There are four possible values: ''Not set'' (known as ''Inherit'' in 1.7), ''Allow'', ''Prevent'', and ''Prohibit''
;Role
:A named set of permissions, for example Teacher, Student and Forum moderator
;Context
:A functional area of Moodle, such as a course, module or block

==Why isn't my role change taking effect?==

In Moodle 1.7.x and 1.8.x, role assignments and overrides do not take effect immediately. They are delayed until the next time the user logs in. Starting with Moodle 1.9, manual role assignments and overrides take effect immediately. However automatic role assignments that result from changes to certain user policies (for example, Default front page role) may be delayed until the next login.

If you are testing a new role, [[Manage_roles#Testing_a_new_role | here are some suggestions]].

Also, please check the context in which the role is assigned. Certain capabilities e.g. [[Capabilities/moodle/user:update|moodle/user:update]] may only be applied in the System context, so giving such permissions in the course context will have no effect.

==Why are all my teacher accounts automatically added as "Teachers" in all my courses?==

If a user is assigned a role in the System context (Site administration -> Users -> Permissions -> Assign system roles) or in a Course category context, then the user will have this role in ALL courses within the context. For example, a user who is assigned the Teacher role in the System context will appear as a Teacher in all courses on the site, including the Front page course.

Except in very special cases, teachers and students should be assigned their respective roles in a Course context. When these roles are assigned in a System context, it is almost always an error on the part of the administrator.

If you have accidentally assigned a System role, go to ''Administration > Users > Permissions > Assign system roles'' unassign users using the right-facing arrow button. Then re-assign the roles in the appropriate Course context.

==Why are all students enrolled in all courses?==

Either
*Users are assigned the role of student in the site/system context rather than the course context (see FAQ above)
Or
*The default role for all users in ''Administration > Users > Permissions > User policies'' is set to Student rather than Authenticated user (Moodle 1.8 onwards).

==Why are there differences in the users listed as course participants and users assigned roles in a course?==

Users assigned roles in a higher context, for example users assigned the role of teacher in a course category context, may appear as course participants. The discussion [http://moodle.org/mod/forum/discuss.php?d=59900 Discrepancies between Assign Roles lists and Participants list] contains a longer explanation.

==How can I prevent administrators being listed as course participants?==

Ensure that administrators are not assigned another role in addition to their admin role.

==Why are hidden assignments still visible?==

Hidden assignments are not hidden from admins or teachers i.e. users with the [[Capabilities/moodle/role:viewhiddenassigns|viewhiddenassigns capability]].

==What is the difference between Prevent and Not set?==

If a role has capability ''X = Not set'', then the role is saying "I don't care about X." If a role has ''X = Prevent,'' then the role is saying "I don't want you be able to do X." Now you typically have multiple roles in a given context, and those roles may have different opinions about ''X''. If ALL of your roles have ''X = Not set'' then you will be effectively prevented from doing ''X'' because you need positive permission to do something. It's just like an election. If you are a candidate but no one votes, you don't win the election. If all of your roles except for one has ''X = Not set'' and the remaining role has ''X = Allow'', then you will be allowed to do X. Again, it's like an election where only one person votes, and they vote for you! For more complicated cases (e.g., roles assigned and overridden in different contexts) you need to understand [[How permissions are calculated]], but the principle is the same: By not voting, a role can allow other roles to determine the outcome of the election. Roles with lots of permissions Not set tend to mix well with other roles.

==What is my role here?==

This is a frequently asked question, but an improper one. The correct question is "What are my ''permissions'' here?" In any given context, you often have two or more roles. In addition, one or more role overrides may be in effect. Your permissions in a given context are a result of "adding" the individual permissions from these roles and overrides according to certain rules. As Tim Hunt writes in [http://moodle.org/mod/forum/discuss.php?d=90140 this discussion], the rules "normally do what you expect." However when permissions conflict, the results can be surprising, and it pays to understand [[How permissions are calculated]].

==How do I debug a roles-related problem?==

If you're having a problem that you suspect is related to roles, consider using [[The rolesdebug.php roles debugging script | the rolesdebug.php roles debugging script]]. You can download it from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and plugins database]. The script gives you a spatial view of your role assignments and overrides in a given context, and analyzes your permissions there. To interpret the output requires a basic understanding of roles and capabilities. If you are a complete roles novice, run the script and post the output to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities Forum].

==How can I prevent a user from changing their own password?==

To prevent a user from changing their own password, you must make sure they do not have moodle/user:changeownpassword ("Change own password") = Allow in the System context. The Authenticated user role (which is assigned to users in the System context) has moodle/user:changeownpassword = Allow by default, so you have two choices:
# edit Authenticated user, setting moodle/user:changeownpassword = Not set
# create a new role CannotChangeOwnPassword with moodle/user:changeownpassword = Prevent and all other permissions Not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (1) will prevent ''all'' users from changing their passwords (except for the administrator, who can do anything). To selectively allow selected users (say teachers) to change their passwords, you could create a new role CanChangeOwnPassword with moodle/user:changeownpassword = Allow and all other permissions not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (2) allows you to be selective, but if you have a lot of users that you want to prevent (say, all students), you will have to make a lot of role assignments in the System context. There is currently no convenient way to do this, so you might consider choice (1).

Note that you MUST deal with this permission in the System context.

==How can I prevent a user from editing their own profile?==

See [[Roles_FAQ#How can I prevent a user from changing their own password? | How can I prevent a user from changing their own password?]] The answer to this question is the same if you substitute ''edit their own profile'' for ''change their own password'' and ''moodle/user:editownprofile'' for ''moodle/user:changeownpassword.''

==Do roles have an inheritance relationsip?==

No. Roles are completely independent.

* When you create a new role by copying an existing role, it is just like copying a file: the original and the copy are identical at the outset, but the copy has no ongoing relationship with the original. Changes to the original do not affect the copy and ''vice versa''.
* When you create a new role and select a value such as LEGACY:Student from the Legacy role type dropdown, you are not "inheriting" from the Student role. You are simply indicating that you want your role to have the same defaults as Student.
* Course creator does not "inherit" from Teacher (a common misconception). As with all roles, the two roles are completely independent. Course creator is actually a very simple role that can basically only create courses and not much else. However a user who creates a course is automatically assigned the role of Teacher in the newly-created course. This is how a course creator gets her teaching abilities within a course.

==Are there any differences in Roles in Moodle 1.7 and 1.8?==

In addition to many Roles fixes and refinements (see the list of [http://tracker.moodle.org/secure/IssueNavigator.jspa?mode=hide&requestId=10221 Roles improvements] in the Tracker), in Moodle 1.8 the ''system'' context is separated from the ''front page'' context. Roles may be assigned in the front page context via ''Administration > Front Page > Front Page roles''.

A "Duplicate role" button has been added in Moodle 1.8, which makes creating new roles based on predefined roles much quicker.

==How do I change the name for "teacher" in the course description?==

Either
* Edit the role of Teacher via ''Administration > Users > Permissions > Define roles'' and rename it. The new name will apply site-wide.
Or
* Create a duplicate teacher role with an alternative name and assign users the duplicate teacher role as appropriate in the course context. In ''Administration > Appearance > Course manager'' select the alternative name for teacher that you wish to be displayed in the course description.
Or
* One more way to do it in 1.8 is to create new "dummy" roles (no capabilities) with those names and assign them to teachers along with the real roles. In the course manager settings you can choose which roles display on the front page under each course. (The feature request [http://tracker.moodle.org/browse/MDL-9182 Ability to assign or display custom title for role of person in course] contains this further method.)

{{Moodle 1.9}}From Moodle 1.9 onwards, names for different roles in a course may be changed in the [[Course settings|course settings]].

==How do I enable teachers to set role overrides?==

#Access ''Administration > Users > Permissions > Define roles''.
#Edit the teacher role and change the capability [[Capabilities/moodle/role:override|moodle/role:override]] to allow.
#Click the button "Save changes".
#Click the tab "Allow role overrides" (in ''Administration > Users > Permissions > Define roles'').
#Check the appropriate box to allow a teacher to override the student role.
#Click the button "Save changes".

==How do I enable teachers to assign other teachers in a course?==

This is disabled by default but it can be switched on by modifying the teacher's role. In ''Administration > Users > Permissions > Define roles'' select the "Allow role assignments" tab and tick the checkbox where Teacher and Teacher intersect.

==Why doesn't "Switch role to.." within a course seem to work properly for a course creator?==

This feature is intended for teachers so that they can see how their course appears for students. It doesn't work reliably outside the course.

Further information about this feature can be found in [[Switch roles]] and the paragraph on testing a new role in [[Manage roles]].

==Are there any example roles?==

Yes, as follows:

*[[Inspector role|Inspector]] - for providing external inspectors with permission to view all courses (without being required to enrol)
*[[Parent role|Parent]] - for providing parents/mentors/tutors with permission to view certain information about their children/mentees/tutees
*[[Demo teacher role|Demo teacher]] - for providing a demonstration teacher account with a password which can't be changed
*[[Forum moderator role|Forum moderator]] - for providing a user with permission in a particular forum to edit or delete forum posts, split discussions and move discussions to other forums
*[[Calendar editor role|Calendar editor]] - for providing a user with permission to add site events to the calendar
*[[Blogger role|Blogger]] - for limiting blogging to specific users only
*[[Quiz user with unlimited time role|Quiz user with unlimited time]] - for allowing a user unlimited time to attempt a quiz which has a time limit set
*[[Question creator role|Question creator]] - for enabling students to create questions for use in quizzes

==Logged-in users can't read the site news. What can I do?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override permissions" link
#Click on "Authenticated User"
#Scroll down to '''Forum'''
#Change the capability [[Capabilities/mod/forum:viewdiscussion|mod/forum:viewdiscussion]] to ''allow''
#Click the "Save changes" button at the bottom of the page

Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I enable logged-in users to participate in front page activities?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override roles" link
#Click on "Authenticated User"
#Change capabilities to ''allow'' for all required activities e.g. record a choice, reply to posts
#Click the "Save changes" button at the bottom of the page

Note that for this to work, you need to make the default role for all users "authenticated user". This is the default for new versions of Moodle. In older versions, the default setting is guest, so if you have recently upgraded, you may have to change this setting. You can change the setting via ''Site Administration > Permissions > User Policies''.

Or:
#Access ''Site Administration > Front Page > Front Page roles''
#Click on Student
#Select all users in the potential users list, and use the left-facing arrow button to add them to the existing users list

{{Moodle 1.9}}Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I copy a custom role from one Moodle site to another==

There is no import and export facility for roles, but it can be achieved nearly as easily using backup and restore.

# Create an empty course with all the default settings
# Assign anybody to your custom role (or roles) within the course
# Backup the course (all defaults are fine)
# Download the backup file
# Upload the backup file to the site files of the target Moodle
# Restore the course (all defaults are fine)
# Delete the course.

You will find that the custom roles have been recreated in the target site.

==See also==

*Using Moodle [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]

[[Category:FAQ]]

[[de:Rollen FAQ]]
[[es:FAQ_roles]]
[[fr:FAQ des rôles]]
[[ja:ロールFAQ]]
[[ru:FAQ по ролям]]

Roles FAQ

2008-07-22T16:43:41Z

Jisner:

{{Roles}}
==What is the definition of a...==

;Capability
:A configurable aspect of behavior. As of version 1.9 Moodle has over 200 capabilities. Each capability has a computer friendly name like [[Capabilities/mod/forum:rate|mod/forum:rate]] and a human-friendly name like "Rate posts."
;Permission
:A capability and its value considered as a pair. There are four possible values: ''Not set'' (known as ''Inherit'' in 1.7), ''Allow'', ''Prevent'', and ''Prohibit''
;Role
:A named set of permissions, for example Teacher, Student and Forum moderator
;Context
:A functional area of Moodle, such as a course, module or block

==Why isn't my role change taking effect?==

In Moodle 1.7.x and 1.8.x, role assignments and overrides do not take effect immediately. They are delayed until the next time the user logs in. Starting with Moodle 1.9, manual role assignments and overrides take effect immediately. However automatic role assignments that result from changes to certain user policies (for example, Default front page role) may be delayed until the next login.

If you are testing a new role, [[Manage_roles#Testing_a_new_role | here are some suggestions]].

Also, please check the context in which the role is assigned. Certain capabilities e.g. [[Capabilities/moodle/user:update|moodle/user:update]] may only be applied in the System context, so giving such permissions in the course context will have no effect.

==Why are all my teacher accounts automatically added as "Teachers" in all my courses?==

If a user is assigned a role in the System context (Site administration -> Users -> Permissions -> Assign system roles) or in a Course category context, then the user will have this role in ALL courses within the context. For example, a user who is assigned the Teacher role in the System context will appear as a Teacher in all courses on the site, including the Front page course.

Except in very special cases, teachers and students should be assigned their respective roles in a Course context. When these roles are assigned in a System context, it is almost always an error on the part of the administrator.

If you have accidentally assigned a System role, go to ''Administration > Users > Permissions > Assign system roles'' unassign users using the right-facing arrow button. Then re-assign the roles in the appropriate Course context.

==Why are all students enrolled in all courses?==

Either
*Users are assigned the role of student in the site/system context rather than the course context (see FAQ above)
Or
*The default role for all users in ''Administration > Users > Permissions > User policies'' is set to Student rather than Authenticated user (Moodle 1.8 onwards).

==Why are there differences in the users listed as course participants and users assigned roles in a course?==

Users assigned roles in a higher context, for example users assigned the role of teacher in a course category context, may appear as course participants. The discussion [http://moodle.org/mod/forum/discuss.php?d=59900 Discrepancies between Assign Roles lists and Participants list] contains a longer explanation.

==How can I prevent administrators being listed as course participants?==

Ensure that administrators are not assigned another role in addition to their admin role.

==Why are hidden assignments still visible?==

Hidden assignments are not hidden from admins or teachers i.e. users with the [[Capabilities/moodle/role:viewhiddenassigns|viewhiddenassigns capability]].

==What is the difference between Prevent and Not set?==

If a role has capability ''X = Not set'', then the role is saying "I don't care about X." If a role has ''X = Prevent,'' then the role is saying "I don't want you be able to do X." Now you typically have multiple roles in a given context, and those roles may have different opinions about ''X''. If ALL of your roles have ''X = Not set'' then you will be effectively prevented from doing ''X'' because you need positive permission to do something. It's just like an election. If you are a candidate but no one votes, you don't win the election. If all of your roles except for one has ''X = Not set'' and the remaining role has ''X = Allow'', then you will be allowed to do X. Again, it's like an election where only one person votes, and they vote for you! For more complicated cases (e.g., roles assigned and overridden in different contexts) you need to understand [[How permissions are calculated]], but the principle is the same: By not voting, a role can allow other roles to determine the outcome of the election. Roles with lots of permissions Not set tend to mix well with other roles.

==What is my role here?==

This is a frequently asked question, but an improper one. The correct question is "What are my ''permissions'' here?" In any given context, you often have two or more roles. In addition, one or more role overrides may be in effect. Your permissions in a given context are a result of "adding" the individual permissions from these roles and overrides according to certain rules. As Tim Hunt writes in [http://moodle.org/mod/forum/discuss.php?d=90140 this discussion], the rules "normally do what you expect." However when permissions conflict, the results can be surprising, and it pays to understand [[How permissions are calculated]].

==How do I debug a roles-related problem?==

If you're having a problem that you suspect is related to roles, consider using [[The rolesdebug.php roles debugging script | the rolesdebug.php roles debugging script]]. You can download it from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and plugins database]. The script gives you a spatial view of your role assignments and overrides in a given context, and analyzes your permissions there. To interpret the output requires a basic understanding of roles and capabilities. If you are a complete roles novice, run the script and post the output to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities Forum].

==How can I prevent a user from changing their own password?==

To prevent a user from changing their own password, you must make sure they do not have moodle/user:changeownpassword ("Change own password") = Allow in the System context. The Authenticated user role (which is assigned to users in the System context) has moodle/user:changeownpassword = Allow by default, so you have two choices:
# edit Authenticated user, setting moodle/user:changeownpassword = Not set
# create a new role CannotChangeOwnPassword with moodle/user:changeownpassword = Prevent and all other permissions Not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (1) will prevent ''all'' users from changing their passwords (except for the administrator, who can do anything). To selectively allow selected users (say teachers) to change their passwords, you could create a new role CanChangeOwnPassword with moodle/user:changeownpassword = Allow and all other permissions not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (2) allows you to be selective, but if you have a lot of users that you want to prevent (say, all students), you will have to make a lot of role assignments in the System context. There is currently no convenient way to do this, so you might consider choice (1).

Note that you MUST deal with this permission in the System context.

==How can I prevent a user from editing their own profile?==

See [[Roles_FAQ#How can I prevent a user from changing their own password? | How can I prevent a user from changing their own password?]] The answer to this question is the same if you substitute ''edit their own profile'' for ''change their own password'' and ''moodle/user:editownprofile'' for ''moodle/user:changeownpassword.''

==Do roles have an inheritance relationsip?==

No. Roles are completely independent.

* When you create a new role by copying an existing role, it is just like copying a file: the original and the copy are identical at the outset, but the copy has no ongoing relationship with the original. Changes to the original do not affect the copy and ''vice versa''.
* When you create a new role and select a value other such as LEGACY:Student from the Legacy role type dropdown, you are not "inheriting" from the Student role. You are simply indicating that you want your role to have the same defaults as Student.
* Course creator does not "inherit" from Teacher (a common misconception). As with all roles, the two roles are completely independent. Course creator is actually a very simple role that can basically only create courses and not much else. However a user who creates a course is automatically assigned the role of Teacher in the newly-created course. This is how a course creator gets her teaching abilities within a course.

==Are there any differences in Roles in Moodle 1.7 and 1.8?==

In addition to many Roles fixes and refinements (see the list of [http://tracker.moodle.org/secure/IssueNavigator.jspa?mode=hide&requestId=10221 Roles improvements] in the Tracker), in Moodle 1.8 the ''system'' context is separated from the ''front page'' context. Roles may be assigned in the front page context via ''Administration > Front Page > Front Page roles''.

A "Duplicate role" button has been added in Moodle 1.8, which makes creating new roles based on predefined roles much quicker.

==How do I change the name for "teacher" in the course description?==

Either
* Edit the role of Teacher via ''Administration > Users > Permissions > Define roles'' and rename it. The new name will apply site-wide.
Or
* Create a duplicate teacher role with an alternative name and assign users the duplicate teacher role as appropriate in the course context. In ''Administration > Appearance > Course manager'' select the alternative name for teacher that you wish to be displayed in the course description.
Or
* One more way to do it in 1.8 is to create new "dummy" roles (no capabilities) with those names and assign them to teachers along with the real roles. In the course manager settings you can choose which roles display on the front page under each course. (The feature request [http://tracker.moodle.org/browse/MDL-9182 Ability to assign or display custom title for role of person in course] contains this further method.)

{{Moodle 1.9}}From Moodle 1.9 onwards, names for different roles in a course may be changed in the [[Course settings|course settings]].

==How do I enable teachers to set role overrides?==

#Access ''Administration > Users > Permissions > Define roles''.
#Edit the teacher role and change the capability [[Capabilities/moodle/role:override|moodle/role:override]] to allow.
#Click the button "Save changes".
#Click the tab "Allow role overrides" (in ''Administration > Users > Permissions > Define roles'').
#Check the appropriate box to allow a teacher to override the student role.
#Click the button "Save changes".

==How do I enable teachers to assign other teachers in a course?==

This is disabled by default but it can be switched on by modifying the teacher's role. In ''Administration > Users > Permissions > Define roles'' select the "Allow role assignments" tab and tick the checkbox where Teacher and Teacher intersect.

==Why doesn't "Switch role to.." within a course seem to work properly for a course creator?==

This feature is intended for teachers so that they can see how their course appears for students. It doesn't work reliably outside the course.

Further information about this feature can be found in [[Switch roles]] and the paragraph on testing a new role in [[Manage roles]].

==Are there any example roles?==

Yes, as follows:

*[[Inspector role|Inspector]] - for providing external inspectors with permission to view all courses (without being required to enrol)
*[[Parent role|Parent]] - for providing parents/mentors/tutors with permission to view certain information about their children/mentees/tutees
*[[Demo teacher role|Demo teacher]] - for providing a demonstration teacher account with a password which can't be changed
*[[Forum moderator role|Forum moderator]] - for providing a user with permission in a particular forum to edit or delete forum posts, split discussions and move discussions to other forums
*[[Calendar editor role|Calendar editor]] - for providing a user with permission to add site events to the calendar
*[[Blogger role|Blogger]] - for limiting blogging to specific users only
*[[Quiz user with unlimited time role|Quiz user with unlimited time]] - for allowing a user unlimited time to attempt a quiz which has a time limit set
*[[Question creator role|Question creator]] - for enabling students to create questions for use in quizzes

==Logged-in users can't read the site news. What can I do?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override permissions" link
#Click on "Authenticated User"
#Scroll down to '''Forum'''
#Change the capability [[Capabilities/mod/forum:viewdiscussion|mod/forum:viewdiscussion]] to ''allow''
#Click the "Save changes" button at the bottom of the page

Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I enable logged-in users to participate in front page activities?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override roles" link
#Click on "Authenticated User"
#Change capabilities to ''allow'' for all required activities e.g. record a choice, reply to posts
#Click the "Save changes" button at the bottom of the page

Note that for this to work, you need to make the default role for all users "authenticated user". This is the default for new versions of Moodle. In older versions, the default setting is guest, so if you have recently upgraded, you may have to change this setting. You can change the setting via ''Site Administration > Permissions > User Policies''.

Or:
#Access ''Site Administration > Front Page > Front Page roles''
#Click on Student
#Select all users in the potential users list, and use the left-facing arrow button to add them to the existing users list

{{Moodle 1.9}}Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I copy a custom role from one Moodle site to another==

There is no import and export facility for roles, but it can be achieved nearly as easily using backup and restore.

# Create an empty course with all the default settings
# Assign anybody to your custom role (or roles) within the course
# Backup the course (all defaults are fine)
# Download the backup file
# Upload the backup file to the site files of the target Moodle
# Restore the course (all defaults are fine)
# Delete the course.

You will find that the custom roles have been recreated in the target site.

==See also==

*Using Moodle [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]

[[Category:FAQ]]

[[de:Rollen FAQ]]
[[es:FAQ_roles]]
[[fr:FAQ des rôles]]
[[ja:ロールFAQ]]
[[ru:FAQ по ролям]]

Roles FAQ

2008-07-22T16:22:51Z

Jisner: /* Why isn't my role change taking effect? */

{{Roles}}
==What is the definition of a...==

;Capability
:A configurable aspect of behavior. As of version 1.9 Moodle has over 200 capabilities. Each capability has a computer friendly name like [[Capabilities/mod/forum:rate|mod/forum:rate]] and a human-friendly name like "Rate posts."
;Permission
:A capability and its value considered as a pair. There are four possible values: ''Not set'' (known as ''Inherit'' in 1.7), ''Allow'', ''Prevent'', and ''Prohibit''
;Role
:A named set of permissions, for example Teacher, Student and Forum moderator
;Context
:A functional area of Moodle, such as a course, module or block

==Why isn't my role change taking effect?==

In Moodle 1.7.x and 1.8.x, role assignments and overrides do not take effect immediately. They are delayed until the next time the user logs in. Starting with Moodle 1.9, manual role assignments and overrides take effect immediately. However automatic role assignments that result from changes to certain user policies (for example, Default front page role) may be delayed until the next login.

If you are testing a new role, [[Manage_roles#Testing_a_new_role | here are some suggestions]].

Also, please check the context in which the role is assigned. Certain capabilities e.g. [[Capabilities/moodle/user:update|moodle/user:update]] may only be applied in the System context, so giving such permissions in the course context will have no effect.

==Why are all my teacher accounts automatically added as "Teachers" in all my courses?==

If a user is assigned a role in the System context (Site administration -> Users -> Permissions -> Assign system roles) or in a Course category context, then the user will have this role in ALL courses within the context. For example, a user who is assigned the Teacher role in the System context will appear as a Teacher in all courses on the site, including the Front page course.

Except in very special cases, teachers and students should be assigned their respective roles in a Course context. When these roles are assigned in a System context, it is almost always an error on the part of the administrator.

If you have accidentally assigned a System role, go to ''Administration > Users > Permissions > Assign system roles'' unassign users using the right-facing arrow button. Then re-assign the roles in the appropriate Course context.

==Why are all students enrolled in all courses?==

Either
*Users are assigned the role of student in the site/system context rather than the course context (see FAQ above)
Or
*The default role for all users in ''Administration > Users > Permissions > User policies'' is set to Student rather than Authenticated user (Moodle 1.8 onwards).

==Why are there differences in the users listed as course participants and users assigned roles in a course?==

Users assigned roles in a higher context, for example users assigned the role of teacher in a course category context, may appear as course participants. The discussion [http://moodle.org/mod/forum/discuss.php?d=59900 Discrepancies between Assign Roles lists and Participants list] contains a longer explanation.

==How can I prevent administrators being listed as course participants?==

Ensure that administrators are not assigned another role in addition to their admin role.

==Why are hidden assignments still visible?==

Hidden assignments are not hidden from admins or teachers i.e. users with the [[Capabilities/moodle/role:viewhiddenassigns|viewhiddenassigns capability]].

==What is the difference between Prevent and Not set?==

If a role has capability ''X = Not set'', then the role is saying "I don't care about X." If a role has ''X = Prevent,'' then the role is saying "I don't want you be able to do X." Now you typically have multiple roles in a given context, and those roles may have different opinions about ''X''. If ALL of your roles have ''X = Not set'' then you will be effectively prevented from doing ''X'' because you need positive permission to do something. It's just like an election. If you are a candidate but no one votes, you don't win the election. If all of your roles except for one has ''X = Not set'' and the remaining role has ''X = Allow'', then you will be allowed to do X. Again, it's like an election where only one person votes, and they vote for you! For more complicated cases (e.g., roles assigned and overridden in different contexts) you need to understand [[How permissions are calculated]], but the principle is the same: By not voting, a role can allow other roles to determine the outcome of the election. Roles with lots of permissions Not set tend to mix well with other roles.

==What is my role here?==

This is a frequently asked question, but an improper one. The correct question is "What are my ''permissions'' here?" In any given context, you often have two or more roles. In addition, one or more role overrides may be in effect. Your permissions in a given context are a result of "adding" the individual permissions from these roles and overrides according to certain rules. As Tim Hunt writes in [http://moodle.org/mod/forum/discuss.php?d=90140 this discussion], the rules "normally do what you expect." However when permissions conflict, the results can be surprising, and it pays to understand [[How permissions are calculated]].

==How do I debug a roles-related problem?==

If you're having a problem that you suspect is related to roles, consider using [[The rolesdebug.php roles debugging script | the rolesdebug.php roles debugging script]]. You can download it from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and plugins database]. The script gives you a spatial view of your role assignments and overrides in a given context, and analyzes your permissions there. To interpret the output requires a basic understanding of roles and capabilities. If you are a complete roles novice, run the script and post the output to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities Forum].

==How can I prevent a user from changing their own password?==

To prevent a user from changing their own password, you must make sure they do not have moodle/user:changeownpassword ("Change own password") = Allow in the System context. The Authenticated user role (which is assigned to users in the System context) has moodle/user:changeownpassword = Allow by default, so you have two choices:
# edit Authenticated user, setting moodle/user:changeownpassword = Not set
# create a new role CannotChangeOwnPassword with moodle/user:changeownpassword = Prevent and all other permissions Not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (1) will prevent ''all'' users from changing their passwords (except for the administrator, who can do anything). To selectively allow selected users (say teachers) to change their passwords, you could create a new role CanChangeOwnPassword with moodle/user:changeownpassword = Allow and all other permissions not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (2) allows you to be selective, but if you have a lot of users that you want to prevent (say, all students), you will have to make a lot of role assignments in the System context. There is currently no convenient way to do this, so you might consider choice (1).

Note that you MUST deal with this permission in the System context.

==How can I prevent a user from editing their own profile?==

See [[Roles_FAQ#How can I prevent a user from changing their own password? | How can I prevent a user from changing their own password?]] The answer to this question is the same if you substitute ''edit their own profile'' for ''change their own password'' and ''moodle/user:editownprofile'' for ''moodle/user:changeownpassword.''

==Are there any differences in Roles in Moodle 1.7 and 1.8?==

In addition to many Roles fixes and refinements (see the list of [http://tracker.moodle.org/secure/IssueNavigator.jspa?mode=hide&requestId=10221 Roles improvements] in the Tracker), in Moodle 1.8 the ''system'' context is separated from the ''front page'' context. Roles may be assigned in the front page context via ''Administration > Front Page > Front Page roles''.

A "Duplicate role" button has been added in Moodle 1.8, which makes creating new roles based on predefined roles much quicker.

==How do I change the name for "teacher" in the course description?==

Either
* Edit the role of Teacher via ''Administration > Users > Permissions > Define roles'' and rename it. The new name will apply site-wide.
Or
* Create a duplicate teacher role with an alternative name and assign users the duplicate teacher role as appropriate in the course context. In ''Administration > Appearance > Course manager'' select the alternative name for teacher that you wish to be displayed in the course description.
Or
* One more way to do it in 1.8 is to create new "dummy" roles (no capabilities) with those names and assign them to teachers along with the real roles. In the course manager settings you can choose which roles display on the front page under each course. (The feature request [http://tracker.moodle.org/browse/MDL-9182 Ability to assign or display custom title for role of person in course] contains this further method.)

{{Moodle 1.9}}From Moodle 1.9 onwards, names for different roles in a course may be changed in the [[Course settings|course settings]].

==How do I enable teachers to set role overrides?==

#Access ''Administration > Users > Permissions > Define roles''.
#Edit the teacher role and change the capability [[Capabilities/moodle/role:override|moodle/role:override]] to allow.
#Click the button "Save changes".
#Click the tab "Allow role overrides" (in ''Administration > Users > Permissions > Define roles'').
#Check the appropriate box to allow a teacher to override the student role.
#Click the button "Save changes".

==How do I enable teachers to assign other teachers in a course?==

This is disabled by default but it can be switched on by modifying the teacher's role. In ''Administration > Users > Permissions > Define roles'' select the "Allow role assignments" tab and tick the checkbox where Teacher and Teacher intersect.

==Why doesn't "Switch role to.." within a course seem to work properly for a course creator?==

This feature is intended for teachers so that they can see how their course appears for students. It doesn't work reliably outside the course.

Further information about this feature can be found in [[Switch roles]] and the paragraph on testing a new role in [[Manage roles]].

==Are there any example roles?==

Yes, as follows:

*[[Inspector role|Inspector]] - for providing external inspectors with permission to view all courses (without being required to enrol)
*[[Parent role|Parent]] - for providing parents/mentors/tutors with permission to view certain information about their children/mentees/tutees
*[[Demo teacher role|Demo teacher]] - for providing a demonstration teacher account with a password which can't be changed
*[[Forum moderator role|Forum moderator]] - for providing a user with permission in a particular forum to edit or delete forum posts, split discussions and move discussions to other forums
*[[Calendar editor role|Calendar editor]] - for providing a user with permission to add site events to the calendar
*[[Blogger role|Blogger]] - for limiting blogging to specific users only
*[[Quiz user with unlimited time role|Quiz user with unlimited time]] - for allowing a user unlimited time to attempt a quiz which has a time limit set
*[[Question creator role|Question creator]] - for enabling students to create questions for use in quizzes

==Logged-in users can't read the site news. What can I do?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override permissions" link
#Click on "Authenticated User"
#Scroll down to '''Forum'''
#Change the capability [[Capabilities/mod/forum:viewdiscussion|mod/forum:viewdiscussion]] to ''allow''
#Click the "Save changes" button at the bottom of the page

Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I enable logged-in users to participate in front page activities?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override roles" link
#Click on "Authenticated User"
#Change capabilities to ''allow'' for all required activities e.g. record a choice, reply to posts
#Click the "Save changes" button at the bottom of the page

Note that for this to work, you need to make the default role for all users "authenticated user". This is the default for new versions of Moodle. In older versions, the default setting is guest, so if you have recently upgraded, you may have to change this setting. You can change the setting via ''Site Administration > Permissions > User Policies''.

Or:
#Access ''Site Administration > Front Page > Front Page roles''
#Click on Student
#Select all users in the potential users list, and use the left-facing arrow button to add them to the existing users list

{{Moodle 1.9}}Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I copy a custom role from one Moodle site to another==

There is no import and export facility for roles, but it can be achieved nearly as easily using backup and restore.

# Create an empty course with all the default settings
# Assign anybody to your custom role (or roles) within the course
# Backup the course (all defaults are fine)
# Download the backup file
# Upload the backup file to the site files of the target Moodle
# Restore the course (all defaults are fine)
# Delete the course.

You will find that the custom roles have been recreated in the target site.

==See also==

*Using Moodle [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]

[[Category:FAQ]]

[[de:Rollen FAQ]]
[[es:FAQ_roles]]
[[fr:FAQ des rôles]]
[[ja:ロールFAQ]]
[[ru:FAQ по ролям]]

Roles FAQ

2008-07-22T16:19:29Z

Jisner: /* What is the definition of a... */

{{Roles}}
==What is the definition of a...==

;Capability
:A configurable aspect of behavior. As of version 1.9 Moodle has over 200 capabilities. Each capability has a computer friendly name like [[Capabilities/mod/forum:rate|mod/forum:rate]] and a human-friendly name like "Rate posts."
;Permission
:A capability and its value considered as a pair. There are four possible values: ''Not set'' (known as ''Inherit'' in 1.7), ''Allow'', ''Prevent'', and ''Prohibit''
;Role
:A named set of permissions, for example Teacher, Student and Forum moderator
;Context
:A functional area of Moodle, such as a course, module or block

==Why isn't my role change taking effect?==

In Moodle 1.7.x and 1.8.x, role assignments and overrides do not take effect immediately. They are delayed until the next time the user logs in. Starting with Moodle 1.9, explicit role assignments and overrides take effect immediately. However role assignments resulting from changes to certain user policies (for example, changing the default front page role) may be delayed until the next login.

If you are testing a new role, [[Manage_roles#Testing_a_new_role | here are some suggestions]].

Also, please check the context in which the role is assigned. Certain capabilities e.g. [[Capabilities/moodle/user:update|moodle/user:update]] may only be applied in the system context, so assigning a role in the course context will result in the role change not taking effect.

==Why are all my teacher accounts automatically added as "Teachers" in all my courses?==

If a user is assigned a role in the System context (Site administration -> Users -> Permissions -> Assign system roles) or in a Course category context, then the user will have this role in ALL courses within the context. For example, a user who is assigned the Teacher role in the System context will appear as a Teacher in all courses on the site, including the Front page course.

Except in very special cases, teachers and students should be assigned their respective roles in a Course context. When these roles are assigned in a System context, it is almost always an error on the part of the administrator.

If you have accidentally assigned a System role, go to ''Administration > Users > Permissions > Assign system roles'' unassign users using the right-facing arrow button. Then re-assign the roles in the appropriate Course context.

==Why are all students enrolled in all courses?==

Either
*Users are assigned the role of student in the site/system context rather than the course context (see FAQ above)
Or
*The default role for all users in ''Administration > Users > Permissions > User policies'' is set to Student rather than Authenticated user (Moodle 1.8 onwards).

==Why are there differences in the users listed as course participants and users assigned roles in a course?==

Users assigned roles in a higher context, for example users assigned the role of teacher in a course category context, may appear as course participants. The discussion [http://moodle.org/mod/forum/discuss.php?d=59900 Discrepancies between Assign Roles lists and Participants list] contains a longer explanation.

==How can I prevent administrators being listed as course participants?==

Ensure that administrators are not assigned another role in addition to their admin role.

==Why are hidden assignments still visible?==

Hidden assignments are not hidden from admins or teachers i.e. users with the [[Capabilities/moodle/role:viewhiddenassigns|viewhiddenassigns capability]].

==What is the difference between Prevent and Not set?==

If a role has capability ''X = Not set'', then the role is saying "I don't care about X." If a role has ''X = Prevent,'' then the role is saying "I don't want you be able to do X." Now you typically have multiple roles in a given context, and those roles may have different opinions about ''X''. If ALL of your roles have ''X = Not set'' then you will be effectively prevented from doing ''X'' because you need positive permission to do something. It's just like an election. If you are a candidate but no one votes, you don't win the election. If all of your roles except for one has ''X = Not set'' and the remaining role has ''X = Allow'', then you will be allowed to do X. Again, it's like an election where only one person votes, and they vote for you! For more complicated cases (e.g., roles assigned and overridden in different contexts) you need to understand [[How permissions are calculated]], but the principle is the same: By not voting, a role can allow other roles to determine the outcome of the election. Roles with lots of permissions Not set tend to mix well with other roles.

==What is my role here?==

This is a frequently asked question, but an improper one. The correct question is "What are my ''permissions'' here?" In any given context, you often have two or more roles. In addition, one or more role overrides may be in effect. Your permissions in a given context are a result of "adding" the individual permissions from these roles and overrides according to certain rules. As Tim Hunt writes in [http://moodle.org/mod/forum/discuss.php?d=90140 this discussion], the rules "normally do what you expect." However when permissions conflict, the results can be surprising, and it pays to understand [[How permissions are calculated]].

==How do I debug a roles-related problem?==

If you're having a problem that you suspect is related to roles, consider using [[The rolesdebug.php roles debugging script | the rolesdebug.php roles debugging script]]. You can download it from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and plugins database]. The script gives you a spatial view of your role assignments and overrides in a given context, and analyzes your permissions there. To interpret the output requires a basic understanding of roles and capabilities. If you are a complete roles novice, run the script and post the output to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities Forum].

==How can I prevent a user from changing their own password?==

To prevent a user from changing their own password, you must make sure they do not have moodle/user:changeownpassword ("Change own password") = Allow in the System context. The Authenticated user role (which is assigned to users in the System context) has moodle/user:changeownpassword = Allow by default, so you have two choices:
# edit Authenticated user, setting moodle/user:changeownpassword = Not set
# create a new role CannotChangeOwnPassword with moodle/user:changeownpassword = Prevent and all other permissions Not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (1) will prevent ''all'' users from changing their passwords (except for the administrator, who can do anything). To selectively allow selected users (say teachers) to change their passwords, you could create a new role CanChangeOwnPassword with moodle/user:changeownpassword = Allow and all other permissions not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (2) allows you to be selective, but if you have a lot of users that you want to prevent (say, all students), you will have to make a lot of role assignments in the System context. There is currently no convenient way to do this, so you might consider choice (1).

Note that you MUST deal with this permission in the System context.

==How can I prevent a user from editing their own profile?==

See [[Roles_FAQ#How can I prevent a user from changing their own password? | How can I prevent a user from changing their own password?]] The answer to this question is the same if you substitute ''edit their own profile'' for ''change their own password'' and ''moodle/user:editownprofile'' for ''moodle/user:changeownpassword.''

==Are there any differences in Roles in Moodle 1.7 and 1.8?==

In addition to many Roles fixes and refinements (see the list of [http://tracker.moodle.org/secure/IssueNavigator.jspa?mode=hide&requestId=10221 Roles improvements] in the Tracker), in Moodle 1.8 the ''system'' context is separated from the ''front page'' context. Roles may be assigned in the front page context via ''Administration > Front Page > Front Page roles''.

A "Duplicate role" button has been added in Moodle 1.8, which makes creating new roles based on predefined roles much quicker.

==How do I change the name for "teacher" in the course description?==

Either
* Edit the role of Teacher via ''Administration > Users > Permissions > Define roles'' and rename it. The new name will apply site-wide.
Or
* Create a duplicate teacher role with an alternative name and assign users the duplicate teacher role as appropriate in the course context. In ''Administration > Appearance > Course manager'' select the alternative name for teacher that you wish to be displayed in the course description.
Or
* One more way to do it in 1.8 is to create new "dummy" roles (no capabilities) with those names and assign them to teachers along with the real roles. In the course manager settings you can choose which roles display on the front page under each course. (The feature request [http://tracker.moodle.org/browse/MDL-9182 Ability to assign or display custom title for role of person in course] contains this further method.)

{{Moodle 1.9}}From Moodle 1.9 onwards, names for different roles in a course may be changed in the [[Course settings|course settings]].

==How do I enable teachers to set role overrides?==

#Access ''Administration > Users > Permissions > Define roles''.
#Edit the teacher role and change the capability [[Capabilities/moodle/role:override|moodle/role:override]] to allow.
#Click the button "Save changes".
#Click the tab "Allow role overrides" (in ''Administration > Users > Permissions > Define roles'').
#Check the appropriate box to allow a teacher to override the student role.
#Click the button "Save changes".

==How do I enable teachers to assign other teachers in a course?==

This is disabled by default but it can be switched on by modifying the teacher's role. In ''Administration > Users > Permissions > Define roles'' select the "Allow role assignments" tab and tick the checkbox where Teacher and Teacher intersect.

==Why doesn't "Switch role to.." within a course seem to work properly for a course creator?==

This feature is intended for teachers so that they can see how their course appears for students. It doesn't work reliably outside the course.

Further information about this feature can be found in [[Switch roles]] and the paragraph on testing a new role in [[Manage roles]].

==Are there any example roles?==

Yes, as follows:

*[[Inspector role|Inspector]] - for providing external inspectors with permission to view all courses (without being required to enrol)
*[[Parent role|Parent]] - for providing parents/mentors/tutors with permission to view certain information about their children/mentees/tutees
*[[Demo teacher role|Demo teacher]] - for providing a demonstration teacher account with a password which can't be changed
*[[Forum moderator role|Forum moderator]] - for providing a user with permission in a particular forum to edit or delete forum posts, split discussions and move discussions to other forums
*[[Calendar editor role|Calendar editor]] - for providing a user with permission to add site events to the calendar
*[[Blogger role|Blogger]] - for limiting blogging to specific users only
*[[Quiz user with unlimited time role|Quiz user with unlimited time]] - for allowing a user unlimited time to attempt a quiz which has a time limit set
*[[Question creator role|Question creator]] - for enabling students to create questions for use in quizzes

==Logged-in users can't read the site news. What can I do?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override permissions" link
#Click on "Authenticated User"
#Scroll down to '''Forum'''
#Change the capability [[Capabilities/mod/forum:viewdiscussion|mod/forum:viewdiscussion]] to ''allow''
#Click the "Save changes" button at the bottom of the page

Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I enable logged-in users to participate in front page activities?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override roles" link
#Click on "Authenticated User"
#Change capabilities to ''allow'' for all required activities e.g. record a choice, reply to posts
#Click the "Save changes" button at the bottom of the page

Note that for this to work, you need to make the default role for all users "authenticated user". This is the default for new versions of Moodle. In older versions, the default setting is guest, so if you have recently upgraded, you may have to change this setting. You can change the setting via ''Site Administration > Permissions > User Policies''.

Or:
#Access ''Site Administration > Front Page > Front Page roles''
#Click on Student
#Select all users in the potential users list, and use the left-facing arrow button to add them to the existing users list

{{Moodle 1.9}}Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I copy a custom role from one Moodle site to another==

There is no import and export facility for roles, but it can be achieved nearly as easily using backup and restore.

# Create an empty course with all the default settings
# Assign anybody to your custom role (or roles) within the course
# Backup the course (all defaults are fine)
# Download the backup file
# Upload the backup file to the site files of the target Moodle
# Restore the course (all defaults are fine)
# Delete the course.

You will find that the custom roles have been recreated in the target site.

==See also==

*Using Moodle [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]

[[Category:FAQ]]

[[de:Rollen FAQ]]
[[es:FAQ_roles]]
[[fr:FAQ des rôles]]
[[ja:ロールFAQ]]
[[ru:FAQ по ролям]]

Roles FAQ

2008-07-22T16:16:00Z

Jisner: /* What is the definition of a... */

{{Roles}}
==What is the definition of a...==

;Capability
:A configurable aspect of behavior, for example [[Capabilities/mod/forum:rate|mod/forum:rate]]
;Permission
:A capability and its value considered as a pair. There are four possible values: ''Not set'' (known as ''Inherit'' in 1.7), ''Allow'', ''Prevent'', and ''Prohibit''
;Role
:A named set of permissions, for example Teacher, Student and Forum moderator
;Context
:A functional area of Moodle, such as a course, module or block

==Why isn't my role change taking effect?==

In Moodle 1.7.x and 1.8.x, role assignments and overrides do not take effect immediately. They are delayed until the next time the user logs in. Starting with Moodle 1.9, explicit role assignments and overrides take effect immediately. However role assignments resulting from changes to certain user policies (for example, changing the default front page role) may be delayed until the next login.

If you are testing a new role, [[Manage_roles#Testing_a_new_role | here are some suggestions]].

Also, please check the context in which the role is assigned. Certain capabilities e.g. [[Capabilities/moodle/user:update|moodle/user:update]] may only be applied in the system context, so assigning a role in the course context will result in the role change not taking effect.

==Why are all my teacher accounts automatically added as "Teachers" in all my courses?==

If a user is assigned a role in the System context (Site administration -> Users -> Permissions -> Assign system roles) or in a Course category context, then the user will have this role in ALL courses within the context. For example, a user who is assigned the Teacher role in the System context will appear as a Teacher in all courses on the site, including the Front page course.

Except in very special cases, teachers and students should be assigned their respective roles in a Course context. When these roles are assigned in a System context, it is almost always an error on the part of the administrator.

If you have accidentally assigned a System role, go to ''Administration > Users > Permissions > Assign system roles'' unassign users using the right-facing arrow button. Then re-assign the roles in the appropriate Course context.

==Why are all students enrolled in all courses?==

Either
*Users are assigned the role of student in the site/system context rather than the course context (see FAQ above)
Or
*The default role for all users in ''Administration > Users > Permissions > User policies'' is set to Student rather than Authenticated user (Moodle 1.8 onwards).

==Why are there differences in the users listed as course participants and users assigned roles in a course?==

Users assigned roles in a higher context, for example users assigned the role of teacher in a course category context, may appear as course participants. The discussion [http://moodle.org/mod/forum/discuss.php?d=59900 Discrepancies between Assign Roles lists and Participants list] contains a longer explanation.

==How can I prevent administrators being listed as course participants?==

Ensure that administrators are not assigned another role in addition to their admin role.

==Why are hidden assignments still visible?==

Hidden assignments are not hidden from admins or teachers i.e. users with the [[Capabilities/moodle/role:viewhiddenassigns|viewhiddenassigns capability]].

==What is the difference between Prevent and Not set?==

If a role has capability ''X = Not set'', then the role is saying "I don't care about X." If a role has ''X = Prevent,'' then the role is saying "I don't want you be able to do X." Now you typically have multiple roles in a given context, and those roles may have different opinions about ''X''. If ALL of your roles have ''X = Not set'' then you will be effectively prevented from doing ''X'' because you need positive permission to do something. It's just like an election. If you are a candidate but no one votes, you don't win the election. If all of your roles except for one has ''X = Not set'' and the remaining role has ''X = Allow'', then you will be allowed to do X. Again, it's like an election where only one person votes, and they vote for you! For more complicated cases (e.g., roles assigned and overridden in different contexts) you need to understand [[How permissions are calculated]], but the principle is the same: By not voting, a role can allow other roles to determine the outcome of the election. Roles with lots of permissions Not set tend to mix well with other roles.

==What is my role here?==

This is a frequently asked question, but an improper one. The correct question is "What are my ''permissions'' here?" In any given context, you often have two or more roles. In addition, one or more role overrides may be in effect. Your permissions in a given context are a result of "adding" the individual permissions from these roles and overrides according to certain rules. As Tim Hunt writes in [http://moodle.org/mod/forum/discuss.php?d=90140 this discussion], the rules "normally do what you expect." However when permissions conflict, the results can be surprising, and it pays to understand [[How permissions are calculated]].

==How do I debug a roles-related problem?==

If you're having a problem that you suspect is related to roles, consider using [[The rolesdebug.php roles debugging script | the rolesdebug.php roles debugging script]]. You can download it from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and plugins database]. The script gives you a spatial view of your role assignments and overrides in a given context, and analyzes your permissions there. To interpret the output requires a basic understanding of roles and capabilities. If you are a complete roles novice, run the script and post the output to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities Forum].

==How can I prevent a user from changing their own password?==

To prevent a user from changing their own password, you must make sure they do not have moodle/user:changeownpassword ("Change own password") = Allow in the System context. The Authenticated user role (which is assigned to users in the System context) has moodle/user:changeownpassword = Allow by default, so you have two choices:
# edit Authenticated user, setting moodle/user:changeownpassword = Not set
# create a new role CannotChangeOwnPassword with moodle/user:changeownpassword = Prevent and all other permissions Not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (1) will prevent ''all'' users from changing their passwords (except for the administrator, who can do anything). To selectively allow selected users (say teachers) to change their passwords, you could create a new role CanChangeOwnPassword with moodle/user:changeownpassword = Allow and all other permissions not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (2) allows you to be selective, but if you have a lot of users that you want to prevent (say, all students), you will have to make a lot of role assignments in the System context. There is currently no convenient way to do this, so you might consider choice (1).

Note that you MUST deal with this permission in the System context.

==How can I prevent a user from editing their own profile?==

See [[Roles_FAQ#How can I prevent a user from changing their own password? | How can I prevent a user from changing their own password?]] The answer to this question is the same if you substitute ''edit their own profile'' for ''change their own password'' and ''moodle/user:editownprofile'' for ''moodle/user:changeownpassword.''

==Are there any differences in Roles in Moodle 1.7 and 1.8?==

In addition to many Roles fixes and refinements (see the list of [http://tracker.moodle.org/secure/IssueNavigator.jspa?mode=hide&requestId=10221 Roles improvements] in the Tracker), in Moodle 1.8 the ''system'' context is separated from the ''front page'' context. Roles may be assigned in the front page context via ''Administration > Front Page > Front Page roles''.

A "Duplicate role" button has been added in Moodle 1.8, which makes creating new roles based on predefined roles much quicker.

==How do I change the name for "teacher" in the course description?==

Either
* Edit the role of Teacher via ''Administration > Users > Permissions > Define roles'' and rename it. The new name will apply site-wide.
Or
* Create a duplicate teacher role with an alternative name and assign users the duplicate teacher role as appropriate in the course context. In ''Administration > Appearance > Course manager'' select the alternative name for teacher that you wish to be displayed in the course description.
Or
* One more way to do it in 1.8 is to create new "dummy" roles (no capabilities) with those names and assign them to teachers along with the real roles. In the course manager settings you can choose which roles display on the front page under each course. (The feature request [http://tracker.moodle.org/browse/MDL-9182 Ability to assign or display custom title for role of person in course] contains this further method.)

{{Moodle 1.9}}From Moodle 1.9 onwards, names for different roles in a course may be changed in the [[Course settings|course settings]].

==How do I enable teachers to set role overrides?==

#Access ''Administration > Users > Permissions > Define roles''.
#Edit the teacher role and change the capability [[Capabilities/moodle/role:override|moodle/role:override]] to allow.
#Click the button "Save changes".
#Click the tab "Allow role overrides" (in ''Administration > Users > Permissions > Define roles'').
#Check the appropriate box to allow a teacher to override the student role.
#Click the button "Save changes".

==How do I enable teachers to assign other teachers in a course?==

This is disabled by default but it can be switched on by modifying the teacher's role. In ''Administration > Users > Permissions > Define roles'' select the "Allow role assignments" tab and tick the checkbox where Teacher and Teacher intersect.

==Why doesn't "Switch role to.." within a course seem to work properly for a course creator?==

This feature is intended for teachers so that they can see how their course appears for students. It doesn't work reliably outside the course.

Further information about this feature can be found in [[Switch roles]] and the paragraph on testing a new role in [[Manage roles]].

==Are there any example roles?==

Yes, as follows:

*[[Inspector role|Inspector]] - for providing external inspectors with permission to view all courses (without being required to enrol)
*[[Parent role|Parent]] - for providing parents/mentors/tutors with permission to view certain information about their children/mentees/tutees
*[[Demo teacher role|Demo teacher]] - for providing a demonstration teacher account with a password which can't be changed
*[[Forum moderator role|Forum moderator]] - for providing a user with permission in a particular forum to edit or delete forum posts, split discussions and move discussions to other forums
*[[Calendar editor role|Calendar editor]] - for providing a user with permission to add site events to the calendar
*[[Blogger role|Blogger]] - for limiting blogging to specific users only
*[[Quiz user with unlimited time role|Quiz user with unlimited time]] - for allowing a user unlimited time to attempt a quiz which has a time limit set
*[[Question creator role|Question creator]] - for enabling students to create questions for use in quizzes

==Logged-in users can't read the site news. What can I do?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override permissions" link
#Click on "Authenticated User"
#Scroll down to '''Forum'''
#Change the capability [[Capabilities/mod/forum:viewdiscussion|mod/forum:viewdiscussion]] to ''allow''
#Click the "Save changes" button at the bottom of the page

Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I enable logged-in users to participate in front page activities?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override roles" link
#Click on "Authenticated User"
#Change capabilities to ''allow'' for all required activities e.g. record a choice, reply to posts
#Click the "Save changes" button at the bottom of the page

Note that for this to work, you need to make the default role for all users "authenticated user". This is the default for new versions of Moodle. In older versions, the default setting is guest, so if you have recently upgraded, you may have to change this setting. You can change the setting via ''Site Administration > Permissions > User Policies''.

Or:
#Access ''Site Administration > Front Page > Front Page roles''
#Click on Student
#Select all users in the potential users list, and use the left-facing arrow button to add them to the existing users list

{{Moodle 1.9}}Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I copy a custom role from one Moodle site to another==

There is no import and export facility for roles, but it can be achieved nearly as easily using backup and restore.

# Create an empty course with all the default settings
# Assign anybody to your custom role (or roles) within the course
# Backup the course (all defaults are fine)
# Download the backup file
# Upload the backup file to the site files of the target Moodle
# Restore the course (all defaults are fine)
# Delete the course.

You will find that the custom roles have been recreated in the target site.

==See also==

*Using Moodle [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]

[[Category:FAQ]]

[[de:Rollen FAQ]]
[[es:FAQ_roles]]
[[fr:FAQ des rôles]]
[[ja:ロールFAQ]]
[[ru:FAQ по ролям]]

Enrolment FAQ

2008-07-22T01:11:37Z

Jisner: /* How do I prevent users from enrolling themselves on courses? */

{{FAQ}}
==How do I prevent students from enrolling themselves in a course?==

Student-initiated enrollment (also known as [[Internal enrolment]]) is one of the standard enrollment methods supported by Moodle. In fact, it is the only method that cannot be disabled sitewide by the administrator. Fortunately, there are a few methods you can use to effectively prevent students from enrolling themselves in your course.
*Set ''Course enrollable'' to ''No'' in the course settings. This disables internal enrollment for your course.
*Set an [[Enrolment key|enrolment key]] in the course settings. Students will only be able to enroll if they know the key. Naturally, you will keep the key secret.

Note that neither method prevents teachers from [[Enrolment#Manual enrolment|manually enrolling]] students (Course administration -> Assign roles).

== Why are users being unenrolled for no apparent reason? ==

Please check the following:
*The ''longtimenosee'' variable in ''Site Administration > Server > Cleanup'' (or Administration > Configuration > Variables in Moodle 1.6) which specifies the time limit for which, if students haven't logged in, they are unenrolled from courses.
*The ''Enrolment duration'' in the [[course/edit|Course settings]] which unenrols students after the specified time has elapsed.

(See [[Unenrolment]] for a full list of what controls unenrolment.)

==Why are all students enrolled in all courses?==

If the default role for all users in ''Site Administration > Users > Permissions > User policies'' is set to student rather than authenticated user (the default setting), this will result in all students being enrolled in all courses.

Another possibility is that users are assigned the system role of student. Check ''Site Administration > Users > Permissions > Assign system roles'' and unassign users as necessary, then reassign them the role of student in the course context.

==Why can't I select "External Database" from the enrolment plugins drop-down menu in the course settings?==

Only ''interactive'' enrolment methods may be chosen in the course settings. Non-interactive enrolment plugins are set for the entire site in ''Site Administration'' > ''Enrolment''. Please refer to the interactive enrolment section of [[Enrolment plugins]].

==How do I enable students to unenrol themselves from courses?==

#Access ''Site Administration > Users > Permissions > Define roles''.
#Click the edit icon opposite the student role.
#Change the [[Capabilities/moodle/role:unassignself|moodle/role:unassignself]] capability from not set to allow.
#Click the "Save changes" button at the bottom of the page.

(See [[Unenrolment]] for instructions on how to enable students to unenrol themselves from a particular course.)

==How do I prevent teachers from unenrolling themselves from their course by mistake?==

#Access ''Site Administration > Users > Permissions > Define roles''.
#Click the edit icon opposite the teacher role.
#Change the [[Capabilities/moodle/role:unassignself|moodle/role:unassignself]] capability from allow to not set.
#Click the "Save changes" button at the bottom of the page.

==How do I change the spelling of "enrol" to "enroll"?==

Simply install the American English language pack (en_us) then choose it as the default language for the site. Or [[Language editing|edit your language]] settings.

==Is there a way for teachers to be notified when students enrol in a course?==

No notifications will be sent when students are allowed to enrol by the [[Internal enrolment]] process. It can be done by changing the open source code, but not by through the interface. Other enrolment methods (for example [[Flat file]]) can allow emails when enrolment is complete but these are not student initiated.

==When a student enrols using an enrolment key, they get a welcome e-mail message. Can a teacher customise this at the course level?==

Entering text for the message is described [[Email_processing#Email_confirmation_or_registration_words.2C_and_how_to_edit_them| Documentation here]]. But at the course level, not possible without a hack.

==Where in the database is the relationship between user and course?==

Prior to Moodle 1.7, enrollments were represented by two simple tables: mdl_user_students and mdl_user_teachers. Under the new Roles and Capabilities System introduced in Moodle 1.7, the concept of enrollment has been generalized. The word "Enroll" should literally be read as "Assign a role to." To accomodate this flexibility, the database model has changed. There is now a mdl_role_assignments table that holds the equivalent information. For more information, see [[Development:Roles|the roles development documentation]]

[[Category:Enrolment]]

Enrolment FAQ

2008-07-22T00:54:20Z

Jisner:

{{FAQ}}
==How do I prevent users from enrolling themselves on courses?==

There are several methods to prevent or restrict [[Internal enrolment]] by a student.
*Set an [[Enrolment key|enrolment key]] in the course settings, so whilst the student can automatically enrol, they will need the key to complete the process.
*Set ''Course enrollable'' to ''No'' in the course settings. This stops the internal enrolment (student initiated enrolment) process.

Note that neither method will prevent [[Enrolment#Manual enrolment|manual enrolments]] or [[Enrolment plugins]] from working.

== Why are users being unenrolled for no apparent reason? ==

Please check the following:
*The ''longtimenosee'' variable in ''Site Administration > Server > Cleanup'' (or Administration > Configuration > Variables in Moodle 1.6) which specifies the time limit for which, if students haven't logged in, they are unenrolled from courses.
*The ''Enrolment duration'' in the [[course/edit|Course settings]] which unenrols students after the specified time has elapsed.

(See [[Unenrolment]] for a full list of what controls unenrolment.)

==Why are all students enrolled in all courses?==

If the default role for all users in ''Site Administration > Users > Permissions > User policies'' is set to student rather than authenticated user (the default setting), this will result in all students being enrolled in all courses.

Another possibility is that users are assigned the system role of student. Check ''Site Administration > Users > Permissions > Assign system roles'' and unassign users as necessary, then reassign them the role of student in the course context.

==Why can't I select "External Database" from the enrolment plugins drop-down menu in the course settings?==

Only ''interactive'' enrolment methods may be chosen in the course settings. Non-interactive enrolment plugins are set for the entire site in ''Site Administration'' > ''Enrolment''. Please refer to the interactive enrolment section of [[Enrolment plugins]].

==How do I enable students to unenrol themselves from courses?==

#Access ''Site Administration > Users > Permissions > Define roles''.
#Click the edit icon opposite the student role.
#Change the [[Capabilities/moodle/role:unassignself|moodle/role:unassignself]] capability from not set to allow.
#Click the "Save changes" button at the bottom of the page.

(See [[Unenrolment]] for instructions on how to enable students to unenrol themselves from a particular course.)

==How do I prevent teachers from unenrolling themselves from their course by mistake?==

#Access ''Site Administration > Users > Permissions > Define roles''.
#Click the edit icon opposite the teacher role.
#Change the [[Capabilities/moodle/role:unassignself|moodle/role:unassignself]] capability from allow to not set.
#Click the "Save changes" button at the bottom of the page.

==How do I change the spelling of "enrol" to "enroll"?==

Simply install the American English language pack (en_us) then choose it as the default language for the site. Or [[Language editing|edit your language]] settings.

==Is there a way for teachers to be notified when students enrol in a course?==

No notifications will be sent when students are allowed to enrol by the [[Internal enrolment]] process. It can be done by changing the open source code, but not by through the interface. Other enrolment methods (for example [[Flat file]]) can allow emails when enrolment is complete but these are not student initiated.

==When a student enrols using an enrolment key, they get a welcome e-mail message. Can a teacher customise this at the course level?==

Entering text for the message is described [[Email_processing#Email_confirmation_or_registration_words.2C_and_how_to_edit_them| Documentation here]]. But at the course level, not possible without a hack.

==Where in the database is the relationship between user and course?==

Prior to Moodle 1.7, enrollments were represented by two simple tables: mdl_user_students and mdl_user_teachers. Under the new Roles and Capabilities System introduced in Moodle 1.7, the concept of enrollment has been generalized. The word "Enroll" should literally be read as "Assign a role to." To accomodate this flexibility, the database model has changed. There is now a mdl_role_assignments table that holds the equivalent information. For more information, see [[Development:Roles|the roles development documentation]]

[[Category:Enrolment]]

Enrolment FAQ

2008-07-22T00:53:30Z

Jisner: /* Where in the database is the relationship between user and course? */

{{FAQ}}
==How do I prevent users from enrolling themselves on courses?==

There are several methods to prevent or restrict [[Internal enrolment]] by a student.
*Set an [[Enrolment key|enrolment key]] in the course settings, so whilst the student can automatically enrol, they will need the key to complete the process.
*Set ''Course enrollable'' to ''No'' in the course settings. This stops the internal enrolment (student initiated enrolment) process.

Note that neither method will prevent [[Enrolment#Manual enrolment|manual enrolments]] or [[Enrolment plugins]] from working.

== Why are users being unenrolled for no apparent reason? ==

Please check the following:
*The ''longtimenosee'' variable in ''Site Administration > Server > Cleanup'' (or Administration > Configuration > Variables in Moodle 1.6) which specifies the time limit for which, if students haven't logged in, they are unenrolled from courses.
*The ''Enrolment duration'' in the [[course/edit|Course settings]] which unenrols students after the specified time has elapsed.

(See [[Unenrolment]] for a full list of what controls unenrolment.)

==Why are all students enrolled in all courses?==

If the default role for all users in ''Site Administration > Users > Permissions > User policies'' is set to student rather than authenticated user (the default setting), this will result in all students being enrolled in all courses.

Another possibility is that users are assigned the system role of student. Check ''Site Administration > Users > Permissions > Assign system roles'' and unassign users as necessary, then reassign them the role of student in the course context.

==Why can't I select "External Database" from the enrolment plugins drop-down menu in the course settings?==

Only ''interactive'' enrolment methods may be chosen in the course settings. Non-interactive enrolment plugins are set for the entire site in ''Site Administration'' > ''Enrolment''. Please refer to the interactive enrolment section of [[Enrolment plugins]].

==How do I enable students to unenrol themselves from courses?==

#Access ''Site Administration > Users > Permissions > Define roles''.
#Click the edit icon opposite the student role.
#Change the [[Capabilities/moodle/role:unassignself|moodle/role:unassignself]] capability from not set to allow.
#Click the "Save changes" button at the bottom of the page.

(See [[Unenrolment]] for instructions on how to enable students to unenrol themselves from a particular course.)

==How do I prevent teachers from unenrolling themselves from their course by mistake?==

#Access ''Site Administration > Users > Permissions > Define roles''.
#Click the edit icon opposite the teacher role.
#Change the [[Capabilities/moodle/role:unassignself|moodle/role:unassignself]] capability from allow to not set.
#Click the "Save changes" button at the bottom of the page.

==How do I change the spelling of "enrol" to "enroll"?==

Simply install the American English language pack (en_us) then choose it as the default language for the site. Or [[Language editing|edit your language]] settings.

==Is there a way for lecturers to be notified when students enrol in a course?==

No notifications will be sent when students are allowed to enrol by the [[Internal enrolment]] process. It can be done by changing the open source code, but not by through the interface. Other enrolment methods (for example [[Flat file]]) can allow emails when enrolment is complete but these are not student initiated.

==When a student enrols using an enrolment key, they get a welcome e-mail message. Can a lecturer customise this at the course level?==

Entering text for the message is described [[Email_processing#Email_confirmation_or_registration_words.2C_and_how_to_edit_them| Documentation here]]. But at the course level, not possible without a hack.

==Where in the database is the relationship between user and course?==

Prior to Moodle 1.7, enrollments were represented by two simple tables: mdl_user_students and mdl_user_teachers. Under the new Roles and Capabilities System introduced in Moodle 1.7, the concept of enrollment has been generalized. The word "Enroll" should literally be read as "Assign a role to." To accomodate this flexibility, the database model has changed. There is now a mdl_role_assignments table that holds the equivalent information. For more information, see [[Development:Roles|the roles development documentation]]

[[Category:Enrolment]]

Enrolment FAQ

2008-07-22T00:50:27Z

Jisner:

{{FAQ}}
==How do I prevent users from enrolling themselves on courses?==

There are several methods to prevent or restrict [[Internal enrolment]] by a student.
*Set an [[Enrolment key|enrolment key]] in the course settings, so whilst the student can automatically enrol, they will need the key to complete the process.
*Set ''Course enrollable'' to ''No'' in the course settings. This stops the internal enrolment (student initiated enrolment) process.

Note that neither method will prevent [[Enrolment#Manual enrolment|manual enrolments]] or [[Enrolment plugins]] from working.

== Why are users being unenrolled for no apparent reason? ==

Please check the following:
*The ''longtimenosee'' variable in ''Site Administration > Server > Cleanup'' (or Administration > Configuration > Variables in Moodle 1.6) which specifies the time limit for which, if students haven't logged in, they are unenrolled from courses.
*The ''Enrolment duration'' in the [[course/edit|Course settings]] which unenrols students after the specified time has elapsed.

(See [[Unenrolment]] for a full list of what controls unenrolment.)

==Why are all students enrolled in all courses?==

If the default role for all users in ''Site Administration > Users > Permissions > User policies'' is set to student rather than authenticated user (the default setting), this will result in all students being enrolled in all courses.

Another possibility is that users are assigned the system role of student. Check ''Site Administration > Users > Permissions > Assign system roles'' and unassign users as necessary, then reassign them the role of student in the course context.

==Why can't I select "External Database" from the enrolment plugins drop-down menu in the course settings?==

Only ''interactive'' enrolment methods may be chosen in the course settings. Non-interactive enrolment plugins are set for the entire site in ''Site Administration'' > ''Enrolment''. Please refer to the interactive enrolment section of [[Enrolment plugins]].

==How do I enable students to unenrol themselves from courses?==

#Access ''Site Administration > Users > Permissions > Define roles''.
#Click the edit icon opposite the student role.
#Change the [[Capabilities/moodle/role:unassignself|moodle/role:unassignself]] capability from not set to allow.
#Click the "Save changes" button at the bottom of the page.

(See [[Unenrolment]] for instructions on how to enable students to unenrol themselves from a particular course.)

==How do I prevent teachers from unenrolling themselves from their course by mistake?==

#Access ''Site Administration > Users > Permissions > Define roles''.
#Click the edit icon opposite the teacher role.
#Change the [[Capabilities/moodle/role:unassignself|moodle/role:unassignself]] capability from allow to not set.
#Click the "Save changes" button at the bottom of the page.

==How do I change the spelling of "enrol" to "enroll"?==

Simply install the American English language pack (en_us) then choose it as the default language for the site. Or [[Language editing|edit your language]] settings.

==Is there a way for lecturers to be notified when students enrol in a course?==

No notifications will be sent when students are allowed to enrol by the [[Internal enrolment]] process. It can be done by changing the open source code, but not by through the interface. Other enrolment methods (for example [[Flat file]]) can allow emails when enrolment is complete but these are not student initiated.

==When a student enrols using an enrolment key, they get a welcome e-mail message. Can a lecturer customise this at the course level?==

Entering text for the message is described [[Email_processing#Email_confirmation_or_registration_words.2C_and_how_to_edit_them| Documentation here]]. But at the course level, not possible without a hack.

==Where in the database is the relationship between user and course?==

Prior to Moodle 1.7, enrollments were represented by two simple tables: mdl_user_students and mdl_user_teachers. Under the new Roles and Capabilities System introduced in Moodle 1.7, the concept of enrollment has been generalized. The word "Enroll" should litterally be read as "Assign a role to." The data base model has become considerably more complicated. There is now a mdl_role_assignments table that holds the equivalent information. For more information, see [[Development:Roles|the roles development documentation]]

[[Category:Enrolment]]

Roles FAQ

2008-07-21T20:07:54Z

Jisner: /* Why are all my teacher accounts automatically added as "Teachers" to all my courses? */

{{Roles}}
==What is the definition of a...==

;Role
:An identifier of the user's status in some context, for example Teacher, Student and Forum moderator
;Capability
:A description of a particular Moodle feature, for example [[Capabilities/moodle/blog:create|moodle/blog:create]]
;Permission
:A setting for a capability - inherit, allow, prevent or prohibit
;Context
:A "space" in Moodle, such as courses, activity modules or blocks

==Why isn't my role change taking effect?==

In Moodle 1.7.x and 1.8.x, role assignments and overrides do not take effect immediately. They are delayed until the next time the user logs in. Starting with Moodle 1.9, explicit role assignments and overrides take effect immediately. However role assignments resulting from changes to certain user policies (for example, changing the default front page role) may be delayed until the next login.

If you are testing a new role, [[Manage_roles#Testing_a_new_role | here are some suggestions]].

Also, please check the context in which the role is assigned. Certain capabilities e.g. [[Capabilities/moodle/user:update|moodle/user:update]] may only be applied in the system context, so assigning a role in the course context will result in the role change not taking effect.

==Why are all my teacher accounts automatically added as "Teachers" in all my courses?==

If a user is assigned a role in the System context (Site administration -> Users -> Permissions -> Assign system roles) or in a Course category context, then the user will have this role in ALL courses within the context. For example, a user who is assigned the Teacher role in the System context will appear as a Teacher in all courses on the site, including the Front page course.

Except in very special cases, teachers and students should be assigned their respective roles in a Course context. When these roles are assigned in a System context, it is almost always an error on the part of the administrator.

If you have accidentally assigned a System role, go to ''Administration > Users > Permissions > Assign system roles'' unassign users using the right-facing arrow button. Then re-assign the roles in the appropriate Course context.

==Why are all students enrolled in all courses?==

Either
*Users are assigned the role of student in the site/system context rather than the course context (see FAQ above)
Or
*The default role for all users in ''Administration > Users > Permissions > User policies'' is set to Student rather than Authenticated user (Moodle 1.8 onwards).

==Why are there differences in the users listed as course participants and users assigned roles in a course?==

Users assigned roles in a higher context, for example users assigned the role of teacher in a course category context, may appear as course participants. The discussion [http://moodle.org/mod/forum/discuss.php?d=59900 Discrepancies between Assign Roles lists and Participants list] contains a longer explanation.

==How can I prevent administrators being listed as course participants?==

Ensure that administrators are not assigned another role in addition to their admin role.

==Why are hidden assignments still visible?==

Hidden assignments are not hidden from admins or teachers i.e. users with the [[Capabilities/moodle/role:viewhiddenassigns|viewhiddenassigns capability]].

==What is the difference between Prevent and Not set?==

If a role has capability ''X = Not set'', then the role is saying "I don't care about X." If a role has ''X = Prevent,'' then the role is saying "I don't want you be able to do X." Now you typically have multiple roles in a given context, and those roles may have different opinions about ''X''. If ALL of your roles have ''X = Not set'' then you will be effectively prevented from doing ''X'' because you need positive permission to do something. It's just like an election. If you are a candidate but no one votes, you don't win the election. If all of your roles except for one has ''X = Not set'' and the remaining role has ''X = Allow'', then you will be allowed to do X. Again, it's like an election where only one person votes, and they vote for you! For more complicated cases (e.g., roles assigned and overridden in different contexts) you need to understand [[How permissions are calculated]], but the principle is the same: By not voting, a role can allow other roles to determine the outcome of the election. Roles with lots of permissions Not set tend to mix well with other roles.

==What is my role here?==

This is a frequently asked question, but an improper one. The correct question is "What are my ''permissions'' here?" In any given context, you often have two or more roles. In addition, one or more role overrides may be in effect. Your permissions in a given context are a result of "adding" the individual permissions from these roles and overrides according to certain rules. As Tim Hunt writes in [http://moodle.org/mod/forum/discuss.php?d=90140 this discussion], the rules "normally do what you expect." However when permissions conflict, the results can be surprising, and it pays to understand [[How permissions are calculated]].

==How do I debug a roles-related problem?==

If you're having a problem that you suspect is related to roles, consider using [[The rolesdebug.php roles debugging script | the rolesdebug.php roles debugging script]]. You can download it from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and plugins database]. The script gives you a spatial view of your role assignments and overrides in a given context, and analyzes your permissions there. To interpret the output requires a basic understanding of roles and capabilities. If you are a complete roles novice, run the script and post the output to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities Forum].

==How can I prevent a user from changing their own password?==

To prevent a user from changing their own password, you must make sure they do not have moodle/user:changeownpassword ("Change own password") = Allow in the System context. The Authenticated user role (which is assigned to users in the System context) has moodle/user:changeownpassword = Allow by default, so you have two choices:
# edit Authenticated user, setting moodle/user:changeownpassword = Not set
# create a new role CannotChangeOwnPassword with moodle/user:changeownpassword = Prevent and all other permissions Not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (1) will prevent ''all'' users from changing their passwords (except for the administrator, who can do anything). To selectively allow selected users (say teachers) to change their passwords, you could create a new role CanChangeOwnPassword with moodle/user:changeownpassword = Allow and all other permissions not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (2) allows you to be selective, but if you have a lot of users that you want to prevent (say, all students), you will have to make a lot of role assignments in the System context. There is currently no convenient way to do this, so you might consider choice (1).

Note that you MUST deal with this permission in the System context.

==How can I prevent a user from editing their own profile?==

See [[Roles_FAQ#How can I prevent a user from changing their own password? | How can I prevent a user from changing their own password?]] The answer to this question is the same if you substitute ''edit their own profile'' for ''change their own password'' and ''moodle/user:editownprofile'' for ''moodle/user:changeownpassword.''

==Are there any differences in Roles in Moodle 1.7 and 1.8?==

In addition to many Roles fixes and refinements (see the list of [http://tracker.moodle.org/secure/IssueNavigator.jspa?mode=hide&requestId=10221 Roles improvements] in the Tracker), in Moodle 1.8 the ''system'' context is separated from the ''front page'' context. Roles may be assigned in the front page context via ''Administration > Front Page > Front Page roles''.

A "Duplicate role" button has been added in Moodle 1.8, which makes creating new roles based on predefined roles much quicker.

==How do I change the name for "teacher" in the course description?==

Either
* Edit the role of Teacher via ''Administration > Users > Permissions > Define roles'' and rename it. The new name will apply site-wide.
Or
* Create a duplicate teacher role with an alternative name and assign users the duplicate teacher role as appropriate in the course context. In ''Administration > Appearance > Course manager'' select the alternative name for teacher that you wish to be displayed in the course description.
Or
* One more way to do it in 1.8 is to create new "dummy" roles (no capabilities) with those names and assign them to teachers along with the real roles. In the course manager settings you can choose which roles display on the front page under each course. (The feature request [http://tracker.moodle.org/browse/MDL-9182 Ability to assign or display custom title for role of person in course] contains this further method.)

{{Moodle 1.9}}From Moodle 1.9 onwards, names for different roles in a course may be changed in the [[Course settings|course settings]].

==How do I enable teachers to set role overrides?==

#Access ''Administration > Users > Permissions > Define roles''.
#Edit the teacher role and change the capability [[Capabilities/moodle/role:override|moodle/role:override]] to allow.
#Click the button "Save changes".
#Click the tab "Allow role overrides" (in ''Administration > Users > Permissions > Define roles'').
#Check the appropriate box to allow a teacher to override the student role.
#Click the button "Save changes".

==How do I enable teachers to assign other teachers in a course?==

This is disabled by default but it can be switched on by modifying the teacher's role. In ''Administration > Users > Permissions > Define roles'' select the "Allow role assignments" tab and tick the checkbox where Teacher and Teacher intersect.

==Why doesn't "Switch role to.." within a course seem to work properly for a course creator?==

This feature is intended for teachers so that they can see how their course appears for students. It doesn't work reliably outside the course.

Further information about this feature can be found in [[Switch roles]] and the paragraph on testing a new role in [[Manage roles]].

==Are there any example roles?==

Yes, as follows:

*[[Inspector role|Inspector]] - for providing external inspectors with permission to view all courses (without being required to enrol)
*[[Parent role|Parent]] - for providing parents/mentors/tutors with permission to view certain information about their children/mentees/tutees
*[[Demo teacher role|Demo teacher]] - for providing a demonstration teacher account with a password which can't be changed
*[[Forum moderator role|Forum moderator]] - for providing a user with permission in a particular forum to edit or delete forum posts, split discussions and move discussions to other forums
*[[Calendar editor role|Calendar editor]] - for providing a user with permission to add site events to the calendar
*[[Blogger role|Blogger]] - for limiting blogging to specific users only
*[[Quiz user with unlimited time role|Quiz user with unlimited time]] - for allowing a user unlimited time to attempt a quiz which has a time limit set
*[[Question creator role|Question creator]] - for enabling students to create questions for use in quizzes

==Logged-in users can't read the site news. What can I do?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override permissions" link
#Click on "Authenticated User"
#Scroll down to '''Forum'''
#Change the capability [[Capabilities/mod/forum:viewdiscussion|mod/forum:viewdiscussion]] to ''allow''
#Click the "Save changes" button at the bottom of the page

Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I enable logged-in users to participate in front page activities?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override roles" link
#Click on "Authenticated User"
#Change capabilities to ''allow'' for all required activities e.g. record a choice, reply to posts
#Click the "Save changes" button at the bottom of the page

Note that for this to work, you need to make the default role for all users "authenticated user". This is the default for new versions of Moodle. In older versions, the default setting is guest, so if you have recently upgraded, you may have to change this setting. You can change the setting via ''Site Administration > Permissions > User Policies''.

Or:
#Access ''Site Administration > Front Page > Front Page roles''
#Click on Student
#Select all users in the potential users list, and use the left-facing arrow button to add them to the existing users list

{{Moodle 1.9}}Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I copy a custom role from one Moodle site to another==

There is no import and export facility for roles, but it can be achieved nearly as easily using backup and restore.

# Create an empty course with all the default settings
# Assign anybody to your custom role (or roles) within the course
# Backup the course (all defaults are fine)
# Download the backup file
# Upload the backup file to the site files of the target Moodle
# Restore the course (all defaults are fine)
# Delete the course.

You will find that the custom roles have been recreated in the target site.

==See also==

*Using Moodle [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]

[[Category:FAQ]]

[[de:Rollen FAQ]]
[[es:FAQ_roles]]
[[fr:FAQ des rôles]]
[[ja:ロールFAQ]]
[[ru:FAQ по ролям]]

Roles FAQ

2008-07-21T20:06:01Z

Jisner: /* Why are participants being added automatically when a new course is created? */

{{Roles}}
==What is the definition of a...==

;Role
:An identifier of the user's status in some context, for example Teacher, Student and Forum moderator
;Capability
:A description of a particular Moodle feature, for example [[Capabilities/moodle/blog:create|moodle/blog:create]]
;Permission
:A setting for a capability - inherit, allow, prevent or prohibit
;Context
:A "space" in Moodle, such as courses, activity modules or blocks

==Why isn't my role change taking effect?==

In Moodle 1.7.x and 1.8.x, role assignments and overrides do not take effect immediately. They are delayed until the next time the user logs in. Starting with Moodle 1.9, explicit role assignments and overrides take effect immediately. However role assignments resulting from changes to certain user policies (for example, changing the default front page role) may be delayed until the next login.

If you are testing a new role, [[Manage_roles#Testing_a_new_role | here are some suggestions]].

Also, please check the context in which the role is assigned. Certain capabilities e.g. [[Capabilities/moodle/user:update|moodle/user:update]] may only be applied in the system context, so assigning a role in the course context will result in the role change not taking effect.

==Why are all my teacher accounts automatically added as "Teachers" to all my courses?==

If a user is assigned a role in the System context (Site administration -> Users -> Permissions -> Assign system roles) or in a Course category context, then the user will have this role in ALL courses within the context. For example, a user who is assigned the Teacher role in the System context will appear as a Teacher in all courses on the site, including the Front page course.

Except in very special cases, teachers and students should be assigned their respective roles in a Course context. When these roles are assigned in a System context, it is almost always an error on the part of the administrator.

If you have accidentally assigned a System role, go to ''Administration > Users > Permissions > Assign system roles'' unassign users using the right-facing arrow button. Then re-assign the roles in the appropriate Course context.

==Why are all students enrolled in all courses?==

Either
*Users are assigned the role of student in the site/system context rather than the course context (see FAQ above)
Or
*The default role for all users in ''Administration > Users > Permissions > User policies'' is set to Student rather than Authenticated user (Moodle 1.8 onwards).

==Why are there differences in the users listed as course participants and users assigned roles in a course?==

Users assigned roles in a higher context, for example users assigned the role of teacher in a course category context, may appear as course participants. The discussion [http://moodle.org/mod/forum/discuss.php?d=59900 Discrepancies between Assign Roles lists and Participants list] contains a longer explanation.

==How can I prevent administrators being listed as course participants?==

Ensure that administrators are not assigned another role in addition to their admin role.

==Why are hidden assignments still visible?==

Hidden assignments are not hidden from admins or teachers i.e. users with the [[Capabilities/moodle/role:viewhiddenassigns|viewhiddenassigns capability]].

==What is the difference between Prevent and Not set?==

If a role has capability ''X = Not set'', then the role is saying "I don't care about X." If a role has ''X = Prevent,'' then the role is saying "I don't want you be able to do X." Now you typically have multiple roles in a given context, and those roles may have different opinions about ''X''. If ALL of your roles have ''X = Not set'' then you will be effectively prevented from doing ''X'' because you need positive permission to do something. It's just like an election. If you are a candidate but no one votes, you don't win the election. If all of your roles except for one has ''X = Not set'' and the remaining role has ''X = Allow'', then you will be allowed to do X. Again, it's like an election where only one person votes, and they vote for you! For more complicated cases (e.g., roles assigned and overridden in different contexts) you need to understand [[How permissions are calculated]], but the principle is the same: By not voting, a role can allow other roles to determine the outcome of the election. Roles with lots of permissions Not set tend to mix well with other roles.

==What is my role here?==

This is a frequently asked question, but an improper one. The correct question is "What are my ''permissions'' here?" In any given context, you often have two or more roles. In addition, one or more role overrides may be in effect. Your permissions in a given context are a result of "adding" the individual permissions from these roles and overrides according to certain rules. As Tim Hunt writes in [http://moodle.org/mod/forum/discuss.php?d=90140 this discussion], the rules "normally do what you expect." However when permissions conflict, the results can be surprising, and it pays to understand [[How permissions are calculated]].

==How do I debug a roles-related problem?==

If you're having a problem that you suspect is related to roles, consider using [[The rolesdebug.php roles debugging script | the rolesdebug.php roles debugging script]]. You can download it from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and plugins database]. The script gives you a spatial view of your role assignments and overrides in a given context, and analyzes your permissions there. To interpret the output requires a basic understanding of roles and capabilities. If you are a complete roles novice, run the script and post the output to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities Forum].

==How can I prevent a user from changing their own password?==

To prevent a user from changing their own password, you must make sure they do not have moodle/user:changeownpassword ("Change own password") = Allow in the System context. The Authenticated user role (which is assigned to users in the System context) has moodle/user:changeownpassword = Allow by default, so you have two choices:
# edit Authenticated user, setting moodle/user:changeownpassword = Not set
# create a new role CannotChangeOwnPassword with moodle/user:changeownpassword = Prevent and all other permissions Not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (1) will prevent ''all'' users from changing their passwords (except for the administrator, who can do anything). To selectively allow selected users (say teachers) to change their passwords, you could create a new role CanChangeOwnPassword with moodle/user:changeownpassword = Allow and all other permissions not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (2) allows you to be selective, but if you have a lot of users that you want to prevent (say, all students), you will have to make a lot of role assignments in the System context. There is currently no convenient way to do this, so you might consider choice (1).

Note that you MUST deal with this permission in the System context.

==How can I prevent a user from editing their own profile?==

See [[Roles_FAQ#How can I prevent a user from changing their own password? | How can I prevent a user from changing their own password?]] The answer to this question is the same if you substitute ''edit their own profile'' for ''change their own password'' and ''moodle/user:editownprofile'' for ''moodle/user:changeownpassword.''

==Are there any differences in Roles in Moodle 1.7 and 1.8?==

In addition to many Roles fixes and refinements (see the list of [http://tracker.moodle.org/secure/IssueNavigator.jspa?mode=hide&requestId=10221 Roles improvements] in the Tracker), in Moodle 1.8 the ''system'' context is separated from the ''front page'' context. Roles may be assigned in the front page context via ''Administration > Front Page > Front Page roles''.

A "Duplicate role" button has been added in Moodle 1.8, which makes creating new roles based on predefined roles much quicker.

==How do I change the name for "teacher" in the course description?==

Either
* Edit the role of Teacher via ''Administration > Users > Permissions > Define roles'' and rename it. The new name will apply site-wide.
Or
* Create a duplicate teacher role with an alternative name and assign users the duplicate teacher role as appropriate in the course context. In ''Administration > Appearance > Course manager'' select the alternative name for teacher that you wish to be displayed in the course description.
Or
* One more way to do it in 1.8 is to create new "dummy" roles (no capabilities) with those names and assign them to teachers along with the real roles. In the course manager settings you can choose which roles display on the front page under each course. (The feature request [http://tracker.moodle.org/browse/MDL-9182 Ability to assign or display custom title for role of person in course] contains this further method.)

{{Moodle 1.9}}From Moodle 1.9 onwards, names for different roles in a course may be changed in the [[Course settings|course settings]].

==How do I enable teachers to set role overrides?==

#Access ''Administration > Users > Permissions > Define roles''.
#Edit the teacher role and change the capability [[Capabilities/moodle/role:override|moodle/role:override]] to allow.
#Click the button "Save changes".
#Click the tab "Allow role overrides" (in ''Administration > Users > Permissions > Define roles'').
#Check the appropriate box to allow a teacher to override the student role.
#Click the button "Save changes".

==How do I enable teachers to assign other teachers in a course?==

This is disabled by default but it can be switched on by modifying the teacher's role. In ''Administration > Users > Permissions > Define roles'' select the "Allow role assignments" tab and tick the checkbox where Teacher and Teacher intersect.

==Why doesn't "Switch role to.." within a course seem to work properly for a course creator?==

This feature is intended for teachers so that they can see how their course appears for students. It doesn't work reliably outside the course.

Further information about this feature can be found in [[Switch roles]] and the paragraph on testing a new role in [[Manage roles]].

==Are there any example roles?==

Yes, as follows:

*[[Inspector role|Inspector]] - for providing external inspectors with permission to view all courses (without being required to enrol)
*[[Parent role|Parent]] - for providing parents/mentors/tutors with permission to view certain information about their children/mentees/tutees
*[[Demo teacher role|Demo teacher]] - for providing a demonstration teacher account with a password which can't be changed
*[[Forum moderator role|Forum moderator]] - for providing a user with permission in a particular forum to edit or delete forum posts, split discussions and move discussions to other forums
*[[Calendar editor role|Calendar editor]] - for providing a user with permission to add site events to the calendar
*[[Blogger role|Blogger]] - for limiting blogging to specific users only
*[[Quiz user with unlimited time role|Quiz user with unlimited time]] - for allowing a user unlimited time to attempt a quiz which has a time limit set
*[[Question creator role|Question creator]] - for enabling students to create questions for use in quizzes

==Logged-in users can't read the site news. What can I do?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override permissions" link
#Click on "Authenticated User"
#Scroll down to '''Forum'''
#Change the capability [[Capabilities/mod/forum:viewdiscussion|mod/forum:viewdiscussion]] to ''allow''
#Click the "Save changes" button at the bottom of the page

Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I enable logged-in users to participate in front page activities?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override roles" link
#Click on "Authenticated User"
#Change capabilities to ''allow'' for all required activities e.g. record a choice, reply to posts
#Click the "Save changes" button at the bottom of the page

Note that for this to work, you need to make the default role for all users "authenticated user". This is the default for new versions of Moodle. In older versions, the default setting is guest, so if you have recently upgraded, you may have to change this setting. You can change the setting via ''Site Administration > Permissions > User Policies''.

Or:
#Access ''Site Administration > Front Page > Front Page roles''
#Click on Student
#Select all users in the potential users list, and use the left-facing arrow button to add them to the existing users list

{{Moodle 1.9}}Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I copy a custom role from one Moodle site to another==

There is no import and export facility for roles, but it can be achieved nearly as easily using backup and restore.

# Create an empty course with all the default settings
# Assign anybody to your custom role (or roles) within the course
# Backup the course (all defaults are fine)
# Download the backup file
# Upload the backup file to the site files of the target Moodle
# Restore the course (all defaults are fine)
# Delete the course.

You will find that the custom roles have been recreated in the target site.

==See also==

*Using Moodle [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]

[[Category:FAQ]]

[[de:Rollen FAQ]]
[[es:FAQ_roles]]
[[fr:FAQ des rôles]]
[[ja:ロールFAQ]]
[[ru:FAQ по ролям]]

Roles FAQ

2008-07-21T20:01:08Z

Jisner: /* Why are participants being added automatically when a new course is created? */

{{Roles}}
==What is the definition of a...==

;Role
:An identifier of the user's status in some context, for example Teacher, Student and Forum moderator
;Capability
:A description of a particular Moodle feature, for example [[Capabilities/moodle/blog:create|moodle/blog:create]]
;Permission
:A setting for a capability - inherit, allow, prevent or prohibit
;Context
:A "space" in Moodle, such as courses, activity modules or blocks

==Why isn't my role change taking effect?==

In Moodle 1.7.x and 1.8.x, role assignments and overrides do not take effect immediately. They are delayed until the next time the user logs in. Starting with Moodle 1.9, explicit role assignments and overrides take effect immediately. However role assignments resulting from changes to certain user policies (for example, changing the default front page role) may be delayed until the next login.

If you are testing a new role, [[Manage_roles#Testing_a_new_role | here are some suggestions]].

Also, please check the context in which the role is assigned. Certain capabilities e.g. [[Capabilities/moodle/user:update|moodle/user:update]] may only be applied in the system context, so assigning a role in the course context will result in the role change not taking effect.

==Why are participants being added automatically when a new course is created?==

If a user is assigned a role in the System context (Site administration -> Users -> Permissions -> Assign system roles) or in a Course category context, then the user will have this role in ALL courses within the context. For example, a user who is assigned the Teacher role in the System context will appear as a Teacher in all courses on the site, including the Front page course.

Except in very special cases, teachers and students should be assigned their respective roles in a Course context. When these roles are assigned in a System context, it is almost always an error on the part of the administrator.

If you have accidentally assigned a System role, go to ''Administration > Users > Permissions > Assign system roles'' unassign users using the right-facing arrow button. Then re-assign the roles in the appropriate Course context.

==Why are all students enrolled in all courses?==

Either
*Users are assigned the role of student in the site/system context rather than the course context (see FAQ above)
Or
*The default role for all users in ''Administration > Users > Permissions > User policies'' is set to Student rather than Authenticated user (Moodle 1.8 onwards).

==Why are there differences in the users listed as course participants and users assigned roles in a course?==

Users assigned roles in a higher context, for example users assigned the role of teacher in a course category context, may appear as course participants. The discussion [http://moodle.org/mod/forum/discuss.php?d=59900 Discrepancies between Assign Roles lists and Participants list] contains a longer explanation.

==How can I prevent administrators being listed as course participants?==

Ensure that administrators are not assigned another role in addition to their admin role.

==Why are hidden assignments still visible?==

Hidden assignments are not hidden from admins or teachers i.e. users with the [[Capabilities/moodle/role:viewhiddenassigns|viewhiddenassigns capability]].

==What is the difference between Prevent and Not set?==

If a role has capability ''X = Not set'', then the role is saying "I don't care about X." If a role has ''X = Prevent,'' then the role is saying "I don't want you be able to do X." Now you typically have multiple roles in a given context, and those roles may have different opinions about ''X''. If ALL of your roles have ''X = Not set'' then you will be effectively prevented from doing ''X'' because you need positive permission to do something. It's just like an election. If you are a candidate but no one votes, you don't win the election. If all of your roles except for one has ''X = Not set'' and the remaining role has ''X = Allow'', then you will be allowed to do X. Again, it's like an election where only one person votes, and they vote for you! For more complicated cases (e.g., roles assigned and overridden in different contexts) you need to understand [[How permissions are calculated]], but the principle is the same: By not voting, a role can allow other roles to determine the outcome of the election. Roles with lots of permissions Not set tend to mix well with other roles.

==What is my role here?==

This is a frequently asked question, but an improper one. The correct question is "What are my ''permissions'' here?" In any given context, you often have two or more roles. In addition, one or more role overrides may be in effect. Your permissions in a given context are a result of "adding" the individual permissions from these roles and overrides according to certain rules. As Tim Hunt writes in [http://moodle.org/mod/forum/discuss.php?d=90140 this discussion], the rules "normally do what you expect." However when permissions conflict, the results can be surprising, and it pays to understand [[How permissions are calculated]].

==How do I debug a roles-related problem?==

If you're having a problem that you suspect is related to roles, consider using [[The rolesdebug.php roles debugging script | the rolesdebug.php roles debugging script]]. You can download it from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and plugins database]. The script gives you a spatial view of your role assignments and overrides in a given context, and analyzes your permissions there. To interpret the output requires a basic understanding of roles and capabilities. If you are a complete roles novice, run the script and post the output to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities Forum].

==How can I prevent a user from changing their own password?==

To prevent a user from changing their own password, you must make sure they do not have moodle/user:changeownpassword ("Change own password") = Allow in the System context. The Authenticated user role (which is assigned to users in the System context) has moodle/user:changeownpassword = Allow by default, so you have two choices:
# edit Authenticated user, setting moodle/user:changeownpassword = Not set
# create a new role CannotChangeOwnPassword with moodle/user:changeownpassword = Prevent and all other permissions Not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (1) will prevent ''all'' users from changing their passwords (except for the administrator, who can do anything). To selectively allow selected users (say teachers) to change their passwords, you could create a new role CanChangeOwnPassword with moodle/user:changeownpassword = Allow and all other permissions not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (2) allows you to be selective, but if you have a lot of users that you want to prevent (say, all students), you will have to make a lot of role assignments in the System context. There is currently no convenient way to do this, so you might consider choice (1).

Note that you MUST deal with this permission in the System context.

==How can I prevent a user from editing their own profile?==

See [[Roles_FAQ#How can I prevent a user from changing their own password? | How can I prevent a user from changing their own password?]] The answer to this question is the same if you substitute ''edit their own profile'' for ''change their own password'' and ''moodle/user:editownprofile'' for ''moodle/user:changeownpassword.''

==Are there any differences in Roles in Moodle 1.7 and 1.8?==

In addition to many Roles fixes and refinements (see the list of [http://tracker.moodle.org/secure/IssueNavigator.jspa?mode=hide&requestId=10221 Roles improvements] in the Tracker), in Moodle 1.8 the ''system'' context is separated from the ''front page'' context. Roles may be assigned in the front page context via ''Administration > Front Page > Front Page roles''.

A "Duplicate role" button has been added in Moodle 1.8, which makes creating new roles based on predefined roles much quicker.

==How do I change the name for "teacher" in the course description?==

Either
* Edit the role of Teacher via ''Administration > Users > Permissions > Define roles'' and rename it. The new name will apply site-wide.
Or
* Create a duplicate teacher role with an alternative name and assign users the duplicate teacher role as appropriate in the course context. In ''Administration > Appearance > Course manager'' select the alternative name for teacher that you wish to be displayed in the course description.
Or
* One more way to do it in 1.8 is to create new "dummy" roles (no capabilities) with those names and assign them to teachers along with the real roles. In the course manager settings you can choose which roles display on the front page under each course. (The feature request [http://tracker.moodle.org/browse/MDL-9182 Ability to assign or display custom title for role of person in course] contains this further method.)

{{Moodle 1.9}}From Moodle 1.9 onwards, names for different roles in a course may be changed in the [[Course settings|course settings]].

==How do I enable teachers to set role overrides?==

#Access ''Administration > Users > Permissions > Define roles''.
#Edit the teacher role and change the capability [[Capabilities/moodle/role:override|moodle/role:override]] to allow.
#Click the button "Save changes".
#Click the tab "Allow role overrides" (in ''Administration > Users > Permissions > Define roles'').
#Check the appropriate box to allow a teacher to override the student role.
#Click the button "Save changes".

==How do I enable teachers to assign other teachers in a course?==

This is disabled by default but it can be switched on by modifying the teacher's role. In ''Administration > Users > Permissions > Define roles'' select the "Allow role assignments" tab and tick the checkbox where Teacher and Teacher intersect.

==Why doesn't "Switch role to.." within a course seem to work properly for a course creator?==

This feature is intended for teachers so that they can see how their course appears for students. It doesn't work reliably outside the course.

Further information about this feature can be found in [[Switch roles]] and the paragraph on testing a new role in [[Manage roles]].

==Are there any example roles?==

Yes, as follows:

*[[Inspector role|Inspector]] - for providing external inspectors with permission to view all courses (without being required to enrol)
*[[Parent role|Parent]] - for providing parents/mentors/tutors with permission to view certain information about their children/mentees/tutees
*[[Demo teacher role|Demo teacher]] - for providing a demonstration teacher account with a password which can't be changed
*[[Forum moderator role|Forum moderator]] - for providing a user with permission in a particular forum to edit or delete forum posts, split discussions and move discussions to other forums
*[[Calendar editor role|Calendar editor]] - for providing a user with permission to add site events to the calendar
*[[Blogger role|Blogger]] - for limiting blogging to specific users only
*[[Quiz user with unlimited time role|Quiz user with unlimited time]] - for allowing a user unlimited time to attempt a quiz which has a time limit set
*[[Question creator role|Question creator]] - for enabling students to create questions for use in quizzes

==Logged-in users can't read the site news. What can I do?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override permissions" link
#Click on "Authenticated User"
#Scroll down to '''Forum'''
#Change the capability [[Capabilities/mod/forum:viewdiscussion|mod/forum:viewdiscussion]] to ''allow''
#Click the "Save changes" button at the bottom of the page

Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I enable logged-in users to participate in front page activities?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override roles" link
#Click on "Authenticated User"
#Change capabilities to ''allow'' for all required activities e.g. record a choice, reply to posts
#Click the "Save changes" button at the bottom of the page

Note that for this to work, you need to make the default role for all users "authenticated user". This is the default for new versions of Moodle. In older versions, the default setting is guest, so if you have recently upgraded, you may have to change this setting. You can change the setting via ''Site Administration > Permissions > User Policies''.

Or:
#Access ''Site Administration > Front Page > Front Page roles''
#Click on Student
#Select all users in the potential users list, and use the left-facing arrow button to add them to the existing users list

{{Moodle 1.9}}Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I copy a custom role from one Moodle site to another==

There is no import and export facility for roles, but it can be achieved nearly as easily using backup and restore.

# Create an empty course with all the default settings
# Assign anybody to your custom role (or roles) within the course
# Backup the course (all defaults are fine)
# Download the backup file
# Upload the backup file to the site files of the target Moodle
# Restore the course (all defaults are fine)
# Delete the course.

You will find that the custom roles have been recreated in the target site.

==See also==

*Using Moodle [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]

[[Category:FAQ]]

[[de:Rollen FAQ]]
[[es:FAQ_roles]]
[[fr:FAQ des rôles]]
[[ja:ロールFAQ]]
[[ru:FAQ по ролям]]

Roles FAQ

2008-07-21T19:53:19Z

Jisner:

{{Roles}}
==What is the definition of a...==

;Role
:An identifier of the user's status in some context, for example Teacher, Student and Forum moderator
;Capability
:A description of a particular Moodle feature, for example [[Capabilities/moodle/blog:create|moodle/blog:create]]
;Permission
:A setting for a capability - inherit, allow, prevent or prohibit
;Context
:A "space" in Moodle, such as courses, activity modules or blocks

==Why isn't my role change taking effect?==

In Moodle 1.7.x and 1.8.x, role assignments and overrides do not take effect immediately. They are delayed until the next time the user logs in. Starting with Moodle 1.9, explicit role assignments and overrides take effect immediately. However role assignments resulting from changes to certain user policies (for example, changing the default front page role) may be delayed until the next login.

If you are testing a new role, [[Manage_roles#Testing_a_new_role | here are some suggestions]].

Also, please check the context in which the role is assigned. Certain capabilities e.g. [[Capabilities/moodle/user:update|moodle/user:update]] may only be applied in the system context, so assigning a role in the course context will result in the role change not taking effect.

==Why are participants being added automatically when a new course is created?==

If a user is assigned a system role or a role in the course category context then the user has this role in ALL courses in that context. Thus users who are students or teachers at the category level appear as course participants in all courses in that category.

Please check ''Administration > Users > Permissions > Assign system roles'' and also the Assign roles link in course categories page and unassign users as necessary.

==Why are all students enrolled in all courses?==

Either
*Users are assigned the role of student in the site/system context rather than the course context (see FAQ above)
Or
*The default role for all users in ''Administration > Users > Permissions > User policies'' is set to Student rather than Authenticated user (Moodle 1.8 onwards).

==Why are there differences in the users listed as course participants and users assigned roles in a course?==

Users assigned roles in a higher context, for example users assigned the role of teacher in a course category context, may appear as course participants. The discussion [http://moodle.org/mod/forum/discuss.php?d=59900 Discrepancies between Assign Roles lists and Participants list] contains a longer explanation.

==How can I prevent administrators being listed as course participants?==

Ensure that administrators are not assigned another role in addition to their admin role.

==Why are hidden assignments still visible?==

Hidden assignments are not hidden from admins or teachers i.e. users with the [[Capabilities/moodle/role:viewhiddenassigns|viewhiddenassigns capability]].

==What is the difference between Prevent and Not set?==

If a role has capability ''X = Not set'', then the role is saying "I don't care about X." If a role has ''X = Prevent,'' then the role is saying "I don't want you be able to do X." Now you typically have multiple roles in a given context, and those roles may have different opinions about ''X''. If ALL of your roles have ''X = Not set'' then you will be effectively prevented from doing ''X'' because you need positive permission to do something. It's just like an election. If you are a candidate but no one votes, you don't win the election. If all of your roles except for one has ''X = Not set'' and the remaining role has ''X = Allow'', then you will be allowed to do X. Again, it's like an election where only one person votes, and they vote for you! For more complicated cases (e.g., roles assigned and overridden in different contexts) you need to understand [[How permissions are calculated]], but the principle is the same: By not voting, a role can allow other roles to determine the outcome of the election. Roles with lots of permissions Not set tend to mix well with other roles.

==What is my role here?==

This is a frequently asked question, but an improper one. The correct question is "What are my ''permissions'' here?" In any given context, you often have two or more roles. In addition, one or more role overrides may be in effect. Your permissions in a given context are a result of "adding" the individual permissions from these roles and overrides according to certain rules. As Tim Hunt writes in [http://moodle.org/mod/forum/discuss.php?d=90140 this discussion], the rules "normally do what you expect." However when permissions conflict, the results can be surprising, and it pays to understand [[How permissions are calculated]].

==How do I debug a roles-related problem?==

If you're having a problem that you suspect is related to roles, consider using [[The rolesdebug.php roles debugging script | the rolesdebug.php roles debugging script]]. You can download it from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and plugins database]. The script gives you a spatial view of your role assignments and overrides in a given context, and analyzes your permissions there. To interpret the output requires a basic understanding of roles and capabilities. If you are a complete roles novice, run the script and post the output to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities Forum].

==How can I prevent a user from changing their own password?==

To prevent a user from changing their own password, you must make sure they do not have moodle/user:changeownpassword ("Change own password") = Allow in the System context. The Authenticated user role (which is assigned to users in the System context) has moodle/user:changeownpassword = Allow by default, so you have two choices:
# edit Authenticated user, setting moodle/user:changeownpassword = Not set
# create a new role CannotChangeOwnPassword with moodle/user:changeownpassword = Prevent and all other permissions Not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (1) will prevent ''all'' users from changing their passwords (except for the administrator, who can do anything). To selectively allow selected users (say teachers) to change their passwords, you could create a new role CanChangeOwnPassword with moodle/user:changeownpassword = Allow and all other permissions not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (2) allows you to be selective, but if you have a lot of users that you want to prevent (say, all students), you will have to make a lot of role assignments in the System context. There is currently no convenient way to do this, so you might consider choice (1).

Note that you MUST deal with this permission in the System context.

==How can I prevent a user from editing their own profile?==

See [[Roles_FAQ#How can I prevent a user from changing their own password? | How can I prevent a user from changing their own password?]] The answer to this question is the same if you substitute ''edit their own profile'' for ''change their own password'' and ''moodle/user:editownprofile'' for ''moodle/user:changeownpassword.''

==Are there any differences in Roles in Moodle 1.7 and 1.8?==

In addition to many Roles fixes and refinements (see the list of [http://tracker.moodle.org/secure/IssueNavigator.jspa?mode=hide&requestId=10221 Roles improvements] in the Tracker), in Moodle 1.8 the ''system'' context is separated from the ''front page'' context. Roles may be assigned in the front page context via ''Administration > Front Page > Front Page roles''.

A "Duplicate role" button has been added in Moodle 1.8, which makes creating new roles based on predefined roles much quicker.

==How do I change the name for "teacher" in the course description?==

Either
* Edit the role of Teacher via ''Administration > Users > Permissions > Define roles'' and rename it. The new name will apply site-wide.
Or
* Create a duplicate teacher role with an alternative name and assign users the duplicate teacher role as appropriate in the course context. In ''Administration > Appearance > Course manager'' select the alternative name for teacher that you wish to be displayed in the course description.
Or
* One more way to do it in 1.8 is to create new "dummy" roles (no capabilities) with those names and assign them to teachers along with the real roles. In the course manager settings you can choose which roles display on the front page under each course. (The feature request [http://tracker.moodle.org/browse/MDL-9182 Ability to assign or display custom title for role of person in course] contains this further method.)

{{Moodle 1.9}}From Moodle 1.9 onwards, names for different roles in a course may be changed in the [[Course settings|course settings]].

==How do I enable teachers to set role overrides?==

#Access ''Administration > Users > Permissions > Define roles''.
#Edit the teacher role and change the capability [[Capabilities/moodle/role:override|moodle/role:override]] to allow.
#Click the button "Save changes".
#Click the tab "Allow role overrides" (in ''Administration > Users > Permissions > Define roles'').
#Check the appropriate box to allow a teacher to override the student role.
#Click the button "Save changes".

==How do I enable teachers to assign other teachers in a course?==

This is disabled by default but it can be switched on by modifying the teacher's role. In ''Administration > Users > Permissions > Define roles'' select the "Allow role assignments" tab and tick the checkbox where Teacher and Teacher intersect.

==Why doesn't "Switch role to.." within a course seem to work properly for a course creator?==

This feature is intended for teachers so that they can see how their course appears for students. It doesn't work reliably outside the course.

Further information about this feature can be found in [[Switch roles]] and the paragraph on testing a new role in [[Manage roles]].

==Are there any example roles?==

Yes, as follows:

*[[Inspector role|Inspector]] - for providing external inspectors with permission to view all courses (without being required to enrol)
*[[Parent role|Parent]] - for providing parents/mentors/tutors with permission to view certain information about their children/mentees/tutees
*[[Demo teacher role|Demo teacher]] - for providing a demonstration teacher account with a password which can't be changed
*[[Forum moderator role|Forum moderator]] - for providing a user with permission in a particular forum to edit or delete forum posts, split discussions and move discussions to other forums
*[[Calendar editor role|Calendar editor]] - for providing a user with permission to add site events to the calendar
*[[Blogger role|Blogger]] - for limiting blogging to specific users only
*[[Quiz user with unlimited time role|Quiz user with unlimited time]] - for allowing a user unlimited time to attempt a quiz which has a time limit set
*[[Question creator role|Question creator]] - for enabling students to create questions for use in quizzes

==Logged-in users can't read the site news. What can I do?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override permissions" link
#Click on "Authenticated User"
#Scroll down to '''Forum'''
#Change the capability [[Capabilities/mod/forum:viewdiscussion|mod/forum:viewdiscussion]] to ''allow''
#Click the "Save changes" button at the bottom of the page

Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I enable logged-in users to participate in front page activities?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override roles" link
#Click on "Authenticated User"
#Change capabilities to ''allow'' for all required activities e.g. record a choice, reply to posts
#Click the "Save changes" button at the bottom of the page

Note that for this to work, you need to make the default role for all users "authenticated user". This is the default for new versions of Moodle. In older versions, the default setting is guest, so if you have recently upgraded, you may have to change this setting. You can change the setting via ''Site Administration > Permissions > User Policies''.

Or:
#Access ''Site Administration > Front Page > Front Page roles''
#Click on Student
#Select all users in the potential users list, and use the left-facing arrow button to add them to the existing users list

{{Moodle 1.9}}Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I copy a custom role from one Moodle site to another==

There is no import and export facility for roles, but it can be achieved nearly as easily using backup and restore.

# Create an empty course with all the default settings
# Assign anybody to your custom role (or roles) within the course
# Backup the course (all defaults are fine)
# Download the backup file
# Upload the backup file to the site files of the target Moodle
# Restore the course (all defaults are fine)
# Delete the course.

You will find that the custom roles have been recreated in the target site.

==See also==

*Using Moodle [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]

[[Category:FAQ]]

[[de:Rollen FAQ]]
[[es:FAQ_roles]]
[[fr:FAQ des rôles]]
[[ja:ロールFAQ]]
[[ru:FAQ по ролям]]

Roles FAQ

2008-07-21T19:16:58Z

Jisner:

{{Roles}}
==What is the definition of a...==

;Role
:An identifier of the user's status in some context, for example Teacher, Student and Forum moderator
;Capability
:A description of a particular Moodle feature, for example [[Capabilities/moodle/blog:create|moodle/blog:create]]
;Permission
:A setting for a capability - inherit, allow, prevent or prohibit
;Context
:A "space" in Moodle, such as courses, activity modules or blocks

==Why isn't my role change taking effect?==

In Moodle 1.7.x and 1.8.x, role assignments and overrides do not take effect immediately. They are delayed until the next time the user logs in. Starting with Moodle 1.9, explicit role assignments and overrides take effect immediately. However role assignments resulting from changes to certain user policies (for example, changing the default front page role) may be delayed until the next login.

If you are testing a new role, [[Manage_roles#Testing_a_new_role | here are some suggestions]].

Also, please check the context in which the role is assigned. Certain capabilities e.g. [[Capabilities/moodle/user:update|moodle/user:update]] may only be applied in the system context, so assigning a role in the course context will result in the role change not taking effect.

==Why are participants being added automatically when a new course is created?==

If a user is assigned a system role or a role in the course category context then the user has this role in ALL courses in that context. Thus users who are students or teachers at the category level appear as course participants in all courses in that category.

Please check ''Administration > Users > Permissions > Assign system roles'' and also the Assign roles link in course categories page and unassign users as necessary.

==Why are all students enrolled in all courses?==

Either
*Users are assigned the role of student in the site/system context rather than the course context (see FAQ above)
Or
*The default role for all users in ''Administration > Users > Permissions > User policies'' is set to Student rather than Authenticated user (Moodle 1.8 onwards).

==Why are there differences in the users listed as course participants and users assigned roles in a course?==

Users assigned roles in a higher context, for example users assigned the role of teacher in a course category context, may appear as course participants. The discussion [http://moodle.org/mod/forum/discuss.php?d=59900 Discrepancies between Assign Roles lists and Participants list] contains a longer explanation.

==How can I prevent administrators being listed as course participants?==

Ensure that administrators are not assigned another role in addition to their admin role.

==Why are hidden assignments still visible?==

Hidden assignments are not hidden from admins or teachers i.e. users with the [[Capabilities/moodle/role:viewhiddenassigns|viewhiddenassigns capability]].

==Where are permissions inherited from?==

Permissions are inherited from a role assigned in a higher-level context which has permissions set to allow for particular capabilities. If permission is "Not set" in any context and not allowed in any higher context (in particular, if you are creating or editing a role at the site level), then a user will have no permission for that capability.

For example, the Student role has permission not set for the change site configuration capability. The permission is never allowed in any context so users assigned the role of Student cannot change the site configuration.

==What is my role here?==

This is a frequently asked question, but an improper one. The correct question is "What are my ''permissions'' here?" In any given context, you often have two or more roles. In addition, one or more role overrides may be in effect. Your permissions in a given context are a result of "adding" the individual permissions from these roles and overrides according to certain rules. As Tim Hunt writes in [http://moodle.org/mod/forum/discuss.php?d=90140 this discussion], the rules "normally do what you expect." However when permissions conflict, the results can be surprising, and it pays to understand [[How permissions are calculated]].

==How do I debug a roles-related problem?==

If you're having a problem that you suspect is related to roles, consider using [[The rolesdebug.php roles debugging script | the rolesdebug.php roles debugging script]]. You can download it from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and plugins database]. The script gives you a spatial view of your role assignments and overrides in a given context, and analyzes your permissions there. To interpret the output requires a basic understanding of roles and capabilities. If you are a complete roles novice, run the script and post the output to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities Forum].

==How can I prevent a user from changing their own password?==

To prevent a user from changing their own password, you must make sure they do not have moodle/user:changeownpassword ("Change own password") = Allow in the System context. The Authenticated user role (which is assigned to users in the System context) has moodle/user:changeownpassword = Allow by default, so you have two choices:
# edit Authenticated user, setting moodle/user:changeownpassword = Not set
# create a new role CannotChangeOwnPassword with moodle/user:changeownpassword = Prevent and all other permissions Not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (1) will prevent ''all'' users from changing their passwords (except for the administrator, who can do anything). To selectively allow selected users (say teachers) to change their passwords, you could create a new role CanChangeOwnPassword with moodle/user:changeownpassword = Allow and all other permissions not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (2) allows you to be selective, but if you have a lot of users that you want to prevent (say, all students), you will have to make a lot of role assignments in the System context. There is currently no convenient way to do this, so you might consider choice (1).

Note that you MUST deal with this permission in the System context.

==How can I prevent a user from editing their own profile?==

See [[Roles_FAQ#How can I prevent a user from changing their own password? | How can I prevent a user from changing their own password?]] The answer to this question is the same if you substitute ''edit their own profile'' for ''change their own password'' and ''moodle/user:editownprofile'' for ''moodle/user:changeownpassword.''

==Are there any differences in Roles in Moodle 1.7 and 1.8?==

In addition to many Roles fixes and refinements (see the list of [http://tracker.moodle.org/secure/IssueNavigator.jspa?mode=hide&requestId=10221 Roles improvements] in the Tracker), in Moodle 1.8 the ''system'' context is separated from the ''front page'' context. Roles may be assigned in the front page context via ''Administration > Front Page > Front Page roles''.

A "Duplicate role" button has been added in Moodle 1.8, which makes creating new roles based on predefined roles much quicker.

==How do I change the name for "teacher" in the course description?==

Either
* Edit the role of Teacher via ''Administration > Users > Permissions > Define roles'' and rename it. The new name will apply site-wide.
Or
* Create a duplicate teacher role with an alternative name and assign users the duplicate teacher role as appropriate in the course context. In ''Administration > Appearance > Course manager'' select the alternative name for teacher that you wish to be displayed in the course description.
Or
* One more way to do it in 1.8 is to create new "dummy" roles (no capabilities) with those names and assign them to teachers along with the real roles. In the course manager settings you can choose which roles display on the front page under each course. (The feature request [http://tracker.moodle.org/browse/MDL-9182 Ability to assign or display custom title for role of person in course] contains this further method.)

{{Moodle 1.9}}From Moodle 1.9 onwards, names for different roles in a course may be changed in the [[Course settings|course settings]].

==How do I enable teachers to set role overrides?==

#Access ''Administration > Users > Permissions > Define roles''.
#Edit the teacher role and change the capability [[Capabilities/moodle/role:override|moodle/role:override]] to allow.
#Click the button "Save changes".
#Click the tab "Allow role overrides" (in ''Administration > Users > Permissions > Define roles'').
#Check the appropriate box to allow a teacher to override the student role.
#Click the button "Save changes".

==How do I enable teachers to assign other teachers in a course?==

This is disabled by default but it can be switched on by modifying the teacher's role. In ''Administration > Users > Permissions > Define roles'' select the "Allow role assignments" tab and tick the checkbox where Teacher and Teacher intersect.

==Why doesn't "Switch role to.." within a course seem to work properly for a course creator?==

This feature is intended for teachers so that they can see how their course appears for students. It doesn't work reliably outside the course.

Further information about this feature can be found in [[Switch roles]] and the paragraph on testing a new role in [[Manage roles]].

==Are there any example roles?==

Yes, as follows:

*[[Inspector role|Inspector]] - for providing external inspectors with permission to view all courses (without being required to enrol)
*[[Parent role|Parent]] - for providing parents/mentors/tutors with permission to view certain information about their children/mentees/tutees
*[[Demo teacher role|Demo teacher]] - for providing a demonstration teacher account with a password which can't be changed
*[[Forum moderator role|Forum moderator]] - for providing a user with permission in a particular forum to edit or delete forum posts, split discussions and move discussions to other forums
*[[Calendar editor role|Calendar editor]] - for providing a user with permission to add site events to the calendar
*[[Blogger role|Blogger]] - for limiting blogging to specific users only
*[[Quiz user with unlimited time role|Quiz user with unlimited time]] - for allowing a user unlimited time to attempt a quiz which has a time limit set
*[[Question creator role|Question creator]] - for enabling students to create questions for use in quizzes

==Logged-in users can't read the site news. What can I do?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override permissions" link
#Click on "Authenticated User"
#Scroll down to '''Forum'''
#Change the capability [[Capabilities/mod/forum:viewdiscussion|mod/forum:viewdiscussion]] to ''allow''
#Click the "Save changes" button at the bottom of the page

Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I enable logged-in users to participate in front page activities?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override roles" link
#Click on "Authenticated User"
#Change capabilities to ''allow'' for all required activities e.g. record a choice, reply to posts
#Click the "Save changes" button at the bottom of the page

Note that for this to work, you need to make the default role for all users "authenticated user". This is the default for new versions of Moodle. In older versions, the default setting is guest, so if you have recently upgraded, you may have to change this setting. You can change the setting via ''Site Administration > Permissions > User Policies''.

Or:
#Access ''Site Administration > Front Page > Front Page roles''
#Click on Student
#Select all users in the potential users list, and use the left-facing arrow button to add them to the existing users list

{{Moodle 1.9}}Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I copy a custom role from one Moodle site to another==

There is no import and export facility for roles, but it can be achieved nearly as easily using backup and restore.

# Create an empty course with all the default settings
# Assign anybody to your custom role (or roles) within the course
# Backup the course (all defaults are fine)
# Download the backup file
# Upload the backup file to the site files of the target Moodle
# Restore the course (all defaults are fine)
# Delete the course.

You will find that the custom roles have been recreated in the target site.

==See also==

*Using Moodle [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]

[[Category:FAQ]]

[[de:Rollen FAQ]]
[[es:FAQ_roles]]
[[fr:FAQ des rôles]]
[[ja:ロールFAQ]]
[[ru:FAQ по ролям]]

Roles FAQ

2008-07-21T19:11:23Z

Jisner:

{{Roles}}
==What is the definition of a...==

;Role
:An identifier of the user's status in some context, for example Teacher, Student and Forum moderator
;Capability
:A description of a particular Moodle feature, for example [[Capabilities/moodle/blog:create|moodle/blog:create]]
;Permission
:A setting for a capability - inherit, allow, prevent or prohibit
;Context
:A "space" in Moodle, such as courses, activity modules or blocks

==Why isn't my role change taking effect?==

In Moodle 1.7.x and 1.8.x, role assignments and overrides do not take effect immediately. They are delayed until the next time the user logs in. Starting with Moodle 1.9, explicit role assignments and overrides take effect immediately. However role assignments resulting from changes to certain user policies (for example, changing the default front page role) may be delayed until the next login.

If you are testing a new role, [[Manage_roles#Testing_a_new_role | here are some suggestions]].

Also, please check the context in which the role is assigned. Certain capabilities e.g. [[Capabilities/moodle/user:update|moodle/user:update]] may only be applied in the system context, so assigning a role in the course context will result in the role change not taking effect.

==Why are participants being added automatically when a new course is created?==

If a user is assigned a system role or a role in the course category context then the user has this role in ALL courses in that context. Thus users who are students or teachers at the category level appear as course participants in all courses in that category.

Please check ''Administration > Users > Permissions > Assign system roles'' and also the Assign roles link in course categories page and unassign users as necessary.

==Why are all students enrolled in all courses?==

Either
*Users are assigned the role of student in the site/system context rather than the course context (see FAQ above)
Or
*The default role for all users in ''Administration > Users > Permissions > User policies'' is set to Student rather than Authenticated user (Moodle 1.8 onwards).

==Why are there differences in the users listed as course participants and users assigned roles in a course?==

Users assigned roles in a higher context, for example users assigned the role of teacher in a course category context, may appear as course participants. The discussion [http://moodle.org/mod/forum/discuss.php?d=59900 Discrepancies between Assign Roles lists and Participants list] contains a longer explanation.

==How can I prevent administrators being listed as course participants?==

Ensure that administrators are not assigned another role in addition to their admin role.

==Why are hidden assignments still visible?==

Hidden assignments are not hidden from admins or teachers i.e. users with the [[Capabilities/moodle/role:viewhiddenassigns|viewhiddenassigns capability]].

==Where are permissions inherited from?==

Permissions are inherited from a role assigned in a higher-level context which has permissions set to allow for particular capabilities. If permission is "Not set" in any context and not allowed in any higher context (in particular, if you are creating or editing a role at the site level), then a user will have no permission for that capability.

For example, the Student role has permission not set for the change site configuration capability. The permission is never allowed in any context so users assigned the role of Student cannot change the site configuration.

==What is my role here?==

This is a frequently asked question, but an improper one. The correct question is "What are my ''permissions'' here?" In any given context, you often have two or more roles. In addition, one or more role overrides may be in effect. Your permissions in a given context are a result of "adding" the individual permissions from these roles and overrides according to certain rules. As Tim Hunt writes in [http://moodle.org/mod/forum/discuss.php?d=90140 this discussion], the rules "normally do what you expect." However when permissions conflict, the results can be surprising, and it pays to understand [[How permissions are calculated]].

==How do I debug a roles-related problem?==

If you're having a problem that you suspect is related to roles, consider using [[The rolesdebug.php roles debugging script | the rolesdebug.php roles debugging script]]. You can download it from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and plugins database]. The script gives you a spatial view of your role assignments and overrides in a given context, and analyzes your permissions there. To interpret the output requires a basic understanding of roles and capabilities. If you are a complete roles novice, run the script and post the output to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities Forum].

==How can I prevent a user from changing their own password?==

To prevent a user from changing their own password, you must make sure they do not have moodle/user:changeownpassword ("Change own password") = Allow in the System context. The Authenticated user role (which is assigned to users in the System context) has moodle/user:changeownpassword = Allow by default, so you have two choices:
# edit Authenticated user, setting moodle/user:changeownpassword = Not set
# create a new role CannotChangeOwnPassword with moodle/user:changeownpassword = Prevent and all other permissions Not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (1) will prevent ''all'' users from changing their passwords (except for the administrator, who can do anything). To selectively allow selected users (say teachers) to change their passwords, you could create a new role CanChangeOwnPassword with moodle/user:changeownpassword = Allow and all other permissions not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (2) allows you to be selective, but if you have a lot of users that you want to prevent (say, all students), you will have to make a lot of role assignments in the System context. There is currently no convenient way to do this, so you might consider choice (1).

Note that you MUST deal with this permission in the System context.

==How can I prevent a user from editing their own profile?==

See "How can I prevent a user from chaning their own password?" The answer to this question is the same if you substitute "edit their own profile" for "change their own password" and "moodle/user:editownprofile" for "moodle/user:changeownpassword."

==Are there any differences in Roles in Moodle 1.7 and 1.8?==

In addition to many Roles fixes and refinements (see the list of [http://tracker.moodle.org/secure/IssueNavigator.jspa?mode=hide&requestId=10221 Roles improvements] in the Tracker), in Moodle 1.8 the ''system'' context is separated from the ''front page'' context. Roles may be assigned in the front page context via ''Administration > Front Page > Front Page roles''.

A "Duplicate role" button has been added in Moodle 1.8, which makes creating new roles based on predefined roles much quicker.

==How do I change the name for "teacher" in the course description?==

Either
* Edit the role of Teacher via ''Administration > Users > Permissions > Define roles'' and rename it. The new name will apply site-wide.
Or
* Create a duplicate teacher role with an alternative name and assign users the duplicate teacher role as appropriate in the course context. In ''Administration > Appearance > Course manager'' select the alternative name for teacher that you wish to be displayed in the course description.
Or
* One more way to do it in 1.8 is to create new "dummy" roles (no capabilities) with those names and assign them to teachers along with the real roles. In the course manager settings you can choose which roles display on the front page under each course. (The feature request [http://tracker.moodle.org/browse/MDL-9182 Ability to assign or display custom title for role of person in course] contains this further method.)

{{Moodle 1.9}}From Moodle 1.9 onwards, names for different roles in a course may be changed in the [[Course settings|course settings]].

==How do I enable teachers to set role overrides?==

#Access ''Administration > Users > Permissions > Define roles''.
#Edit the teacher role and change the capability [[Capabilities/moodle/role:override|moodle/role:override]] to allow.
#Click the button "Save changes".
#Click the tab "Allow role overrides" (in ''Administration > Users > Permissions > Define roles'').
#Check the appropriate box to allow a teacher to override the student role.
#Click the button "Save changes".

==How do I enable teachers to assign other teachers in a course?==

This is disabled by default but it can be switched on by modifying the teacher's role. In ''Administration > Users > Permissions > Define roles'' select the "Allow role assignments" tab and tick the checkbox where Teacher and Teacher intersect.

==Why doesn't "Switch role to.." within a course seem to work properly for a course creator?==

This feature is intended for teachers so that they can see how their course appears for students. It doesn't work reliably outside the course.

Further information about this feature can be found in [[Switch roles]] and the paragraph on testing a new role in [[Manage roles]].

==Are there any example roles?==

Yes, as follows:

*[[Inspector role|Inspector]] - for providing external inspectors with permission to view all courses (without being required to enrol)
*[[Parent role|Parent]] - for providing parents/mentors/tutors with permission to view certain information about their children/mentees/tutees
*[[Demo teacher role|Demo teacher]] - for providing a demonstration teacher account with a password which can't be changed
*[[Forum moderator role|Forum moderator]] - for providing a user with permission in a particular forum to edit or delete forum posts, split discussions and move discussions to other forums
*[[Calendar editor role|Calendar editor]] - for providing a user with permission to add site events to the calendar
*[[Blogger role|Blogger]] - for limiting blogging to specific users only
*[[Quiz user with unlimited time role|Quiz user with unlimited time]] - for allowing a user unlimited time to attempt a quiz which has a time limit set
*[[Question creator role|Question creator]] - for enabling students to create questions for use in quizzes

==Logged-in users can't read the site news. What can I do?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override permissions" link
#Click on "Authenticated User"
#Scroll down to '''Forum'''
#Change the capability [[Capabilities/mod/forum:viewdiscussion|mod/forum:viewdiscussion]] to ''allow''
#Click the "Save changes" button at the bottom of the page

Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I enable logged-in users to participate in front page activities?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override roles" link
#Click on "Authenticated User"
#Change capabilities to ''allow'' for all required activities e.g. record a choice, reply to posts
#Click the "Save changes" button at the bottom of the page

Note that for this to work, you need to make the default role for all users "authenticated user". This is the default for new versions of Moodle. In older versions, the default setting is guest, so if you have recently upgraded, you may have to change this setting. You can change the setting via ''Site Administration > Permissions > User Policies''.

Or:
#Access ''Site Administration > Front Page > Front Page roles''
#Click on Student
#Select all users in the potential users list, and use the left-facing arrow button to add them to the existing users list

{{Moodle 1.9}}Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

==How do I copy a custom role from one Moodle site to another==

There is no import and export facility for roles, but it can be achieved nearly as easily using backup and restore.

# Create an empty course with all the default settings
# Assign anybody to your custom role (or roles) within the course
# Backup the course (all defaults are fine)
# Download the backup file
# Upload the backup file to the site files of the target Moodle
# Restore the course (all defaults are fine)
# Delete the course.

You will find that the custom roles have been recreated in the target site.

==See also==

*Using Moodle [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]

[[Category:FAQ]]

[[de:Rollen FAQ]]
[[es:FAQ_roles]]
[[fr:FAQ des rôles]]
[[ja:ロールFAQ]]
[[ru:FAQ по ролям]]

Keyholder role

2008-07-21T13:55:36Z

Jisner: Undo revision 39978 by Jisner (Talk)

The role of '''Keyholder''' may be used to set the person named as holding a course [[Enrolment key|enrolment key]].

''Note that from Moodle 1.8.3 you can specify the role of the keyholder in the [[Internal enrolment]] settings, making this tip effectively redundant (although it will still work as described if the keyholder is not set).''

==Role set-up==

#Access ''Administration > Users > Permissions > Define roles''
#Click the button "Add a new role"
#Give the role a name e.g. Keyholder, short name and description
#Change the capability [[Capabilities/moodle/course:update|moodle/course:update]] to allow
#Click the button "Add a new role"
#Use the up arrows in the edit column to move the Keyholder role above the Teacher role in the list

==Role assignment==

# Access the Assign roles page in a particular course via the Assign roles link in course administration block
# Choose the Keyholder role to assign
# Select the user holding the course enrolment key in the potential users list, and use the left-facing arrow button to add it to the existing users list

[[Category:Roles]]

[[fr:Rôle gardien de clé]]
[[ja:キー保持者ロール]]
[[de:Kursschlüsselverwalter-Rolle]]

Keyholder role

2008-07-21T13:55:20Z

Jisner: Undo revision 39979 by Jisner (Talk)

The role of '''Keyholder''' may be used to set the person named as holding a course [[Enrolment key|enrolment key]].

''Note that from Moodle 1.8.3 you can specify the role of the keyholder in the [[Internal enrolment]] settings, making this tip effectively redundant (although it will still work as described if the keyholder is not set).''

==Role set-up==

#Access ''Site Administration > Users > Permissions > Define roles''
#Click the button "Add a new role"
#Give the role a name e.g. Keyholder, short name and description
#Change the capability [[Capabilities/moodle/course:update|moodle/course:update]] to allow
#Click the button "Add a new role"
#Use the up arrows in the edit column to move the Keyholder role above the Teacher role in the list
#Go to ''Site administration > Courses > Enrolments'' and click the Edit link next to Internal Enrolments. Choose "Keyholder" from the enrol_manual_keyholder dropdown list. Save changes.

==Role assignment==

# Access the Assign roles page in a particular course via the Assign roles link in course administration block
# Choose the Keyholder role to assign
# Select the user holding the course enrolment key in the potential users list, and use the left-facing arrow button to add it to the existing users list

[[Category:Roles]]

[[fr:Rôle gardien de clé]]
[[ja:キー保持者ロール]]
[[de:Kursschlüsselverwalter-Rolle]]

Keyholder role

2008-07-21T13:54:06Z

Jisner: Undo revision 40134 by Jisner (Talk)

The role of '''Keyholder''' may be used to set the person named as holding a course [[Enrolment key|enrolment key]].

''Note that from Moodle 1.8.3 you can specify the role of the keyholder in the [[Internal enrolment]] settings, making this tip effectively redundant (although it will still work as described if the keyholder is not set).''

==Role set-up==

#Access ''Site Administration > Users > Permissions > Define roles''
#Click the button "Add a new role"
#Give the role a name e.g. Keyholder, short name and description
#Change the capability [[Capabilities/moodle/course:update|moodle/course:update]] to allow
#Click the button "Add a new role"
#Use the up arrows in the edit column to move the Keyholder role above the Teacher role in the list
#Go to ''Site administration > Courses > Enrolments'' and click the Edit link next to Internal Enrolments. Choose "Keyholder" from the enrol_manual_keyholder dropdown list. Save changes.

==Role assignment==

# Access the Assign roles page in a particular course via the Assign roles link in course administration block
# Choose the Keyholder role to assign
# Select the user holding the course enrolment key in the potential users list, and use the left-facing arrow button to add it to the existing users list

Note: Currently, you ''must'' assign the role in a Course context. If you assign it in a higher context (Category or System) the mechanism does not work. See MDL-14566.

[[Category:Roles]]

[[fr:Rôle gardien de clé]]
[[ja:キー保持者ロール]]
[[de:Kursschlüsselverwalter-Rolle]]

Keyholder role

2008-07-21T13:53:32Z

Jisner: Undo revision 39979 by Jisner (Talk)

The role of '''Keyholder''' may be used to set the person named as holding a course [[Enrolment key|enrolment key]].

''Note that from Moodle 1.8.3 you can specify the role of the keyholder in the [[Internal enrolment]] settings, making this tip effectively redundant (although it will still work as described if the keyholder is not set).''

==Role set-up==

#Access ''Site Administration > Users > Permissions > Define roles''
#Click the button "Add a new role"
#Give the role a name e.g. Keyholder, short name and description
#Change the capability [[Capabilities/moodle/course:update|moodle/course:update]] to allow
#Click the button "Add a new role"
#Use the up arrows in the edit column to move the Keyholder role above the Teacher role in the list
#Go to ''Site administration > Courses > Enrolments'' and click the Edit link next to Internal Enrolments. Choose "Keyholder" from the enrol_manual_keyholder dropdown list. Save changes.

==Role assignment==

# Access the Assign roles page in a particular course via the Assign roles link in course administration block
# Choose the Keyholder role to assign
# Select the user holding the course enrolment key in the potential users list, and use the left-facing arrow button to add it to the existing users list

[[Category:Roles]]

[[fr:Rôle gardien de clé]]
[[ja:キー保持者ロール]]
[[de:Kursschlüsselverwalter-Rolle]]

Keyholder role

2008-07-18T15:03:12Z

Jisner: /* Role assignment */

The role of '''Keyholder''' may be used to set the person named as holding a course [[Enrolment key|enrolment key]].

''Note that from Moodle 1.8.3 you can specify the role of the keyholder in the [[Internal enrolment]] settings, making this tip effectively redundant (although it will still work as described if the keyholder is not set).''

==Role set-up==

#Access ''Site Administration > Users > Permissions > Define roles''
#Click the button "Add a new role"
#Give the role a name e.g. Keyholder, short name and description
#Change the capability [[Capabilities/moodle/course:update|moodle/course:update]] to allow
#Click the button "Add a new role"
#Use the up arrows in the edit column to move the Keyholder role above the Teacher role in the list
#Go to ''Site administration > Courses > Enrolments'' and click the Edit link next to Internal Enrolments. Choose "Keyholder" from the enrol_manual_keyholder dropdown list. Save changes.

==Role assignment==

# Access the Assign roles page in a particular course via the Assign roles link in course administration block
# Choose the Keyholder role to assign
# Select the user holding the course enrolment key in the potential users list, and use the left-facing arrow button to add it to the existing users list

Note: Currently, you ''must'' assign the role in a Course context. If you assign it in a higher context (Category or System) the mechanism does not work. See MDL-14566.

[[Category:Roles]]

[[fr:Rôle gardien de clé]]
[[ja:キー保持者ロール]]
[[de:Kursschlüsselverwalter-Rolle]]

Keyholder role

2008-07-18T15:00:24Z

Jisner: /* Role set-up */

The role of '''Keyholder''' may be used to set the person named as holding a course [[Enrolment key|enrolment key]].

''Note that from Moodle 1.8.3 you can specify the role of the keyholder in the [[Internal enrolment]] settings, making this tip effectively redundant (although it will still work as described if the keyholder is not set).''

==Role set-up==

#Access ''Site Administration > Users > Permissions > Define roles''
#Click the button "Add a new role"
#Give the role a name e.g. Keyholder, short name and description
#Change the capability [[Capabilities/moodle/course:update|moodle/course:update]] to allow
#Click the button "Add a new role"
#Use the up arrows in the edit column to move the Keyholder role above the Teacher role in the list
#Go to ''Site administration > Courses > Enrolments'' and click the Edit link next to Internal Enrolments. Choose "Keyholder" from the enrol_manual_keyholder dropdown list. Save changes.

==Role assignment==

# Access the Assign roles page in a particular course via the Assign roles link in course administration block
# Choose the Keyholder role to assign
# Select the user holding the course enrolment key in the potential users list, and use the left-facing arrow button to add it to the existing users list

[[Category:Roles]]

[[fr:Rôle gardien de clé]]
[[ja:キー保持者ロール]]
[[de:Kursschlüsselverwalter-Rolle]]

Forum ratings

2008-07-17T19:57:41Z

Jisner: /* How to use */

{{Forums}}
Forum ratings allow users to evaluate posts in a forum.

==How to use==
If a user has mod/forum:rate ("Rate posts") = Allow in a forum context, the user will be able to rate posts in that forum (see below). Note that the predefined Teacher role has mod/forum:rate ("Rate posts") = Allow, while the predefined Student role has mod/forum:rate ("Rate posts") = Not set. As a result, only teachers are allowed to rate forum posts by default. To allow students to rate posts, see [[Forum_permissions#Enabling_students_to_rate_posts | enabling students to rate posts]].

A user who is allowed to rate posts will see, at the end of each post (except, of course, for his own posts) a label "Rate this post" with a pulldown menu. The menu displays a [[Scales|scale]] that the forum creator selected in the [[Adding/editing_a_forum#Grade|Forum grade settings]]. The rating can become part of the [[Grades|Gradebook]].

[[Image:Forum rating example1 mu.png|thumb|center|Teacher view of a previously rated student post]]

==Tips and Tricks==
*Not all your students are seeing stars? It is all about their browser settings, language and installed fonts.
**If this is a problem, stick with the basics in you scale. Perhaps create a scale that uses Numbers and words.

==See also==
*[[Course level ratings]]
*[[Scales]]
*[[Grades]]

Forum ratings

2008-07-17T19:54:38Z

Jisner:

{{Forums}}
Forum ratings allow users to evaluate posts in a forum.

==How to use==
If a user has mod/forum:rate ("Rate posts") = Allow in a forum context, the user will be able to rate posts in that forum (see below). Note that the predefined Teacher role has mod/forum:rate ("Rate posts") = Allow, while the predefined Student role has mod/forum:rate ("Rate posts") = Not set. As a result, only teachers are allowed to rate forum posts by default.

A user who is allowed to rate posts will see, at the end of each post (except, of course, for his own posts) a label "Rate this post" with a pulldown menu. The menu displays a [[Scales|scale]] that the forum creator selected in the [[Adding/editing_a_forum#Grade|Forum grade settings]]. The rating can become part of the [[Grades|Gradebook]].

[[Image:Forum rating example1 mu.png|thumb|center|Teacher view of a previously rated student post]]

==Tips and Tricks==
*Not all your students are seeing stars? It is all about their browser settings, language and installed fonts.
**If this is a problem, stick with the basics in you scale. Perhaps create a scale that uses Numbers and words.

==See also==
*[[Course level ratings]]
*[[Scales]]
*[[Grades]]

Forum ratings

2008-07-17T19:51:24Z

Jisner: /* How to use */

{{Forums}}
Forum ratings allow either the teacher and/or students to evaluate posts in a forum.

==How to use==
If a user has mod/forum:rate ("Rate posts") = Allow in a forum context, the user will see a label "Rate this post" with a pulldown menu at the bottom of each post (except, of course, for his own posts). The menu displays a [[Scales|scale]] that the forum creator selected in the [[Adding/editing_a_forum#Grade|Forum grade settings]]. The rating can become part of the [[Grades|Gradebook]]. Note that the predefined Teacher role has mod/forum:rate ("Rate posts") = Allow, while the predefined Student role has mod/forum:rate ("Rate posts") = Not set. As a result, only teachers are allowed to rate forum posts by default.

[[Image:Forum rating example1 mu.png|thumb|center|Teacher view of a previously rated student post]]

==Tips and Tricks==
*Not all your students are seeing stars? It is all about their browser settings, language and installed fonts.
**If this is a problem, stick with the basics in you scale. Perhaps create a scale that uses Numbers and words.

==See also==
*[[Course level ratings]]
*[[Scales]]
*[[Grades]]

How permissions are calculated

2008-07-04T03:58:44Z

Jisner: /* Representing the data in tabular form */

{{Roles}}
One of the most frequently asked question is: ''What are my permissions in this context?'' This article will document the function that Moodle uses to answer this question. The article is written for non-programmers as well as programmers, since it describes ''what'' the function does, not ''how''. The ''how'' is complicated. The ''what'' turns out to be relatively simple! If you are a programmer and you insist on reading the code, look for ''has_capability()'' in ''lib/accesslib.php''.

Given a user, a capability, and a context, ''has_capability()'' returns ''true'' if the user is allowed to perform the action controlled by the capability in the given context, and ''false'' otherwise. In calculating the permission, the function considers all of the relevant permission data, which include role definitions, assignments, and overrides.

Moodle never calculates a user's complete set of permissions. To do so would be very costly and also wasteful, since most permissions are never tested. Instead, Moodle calculates permissions only as needed. It does not store the permissions that it calculates, but recalculates them every time it needs to test them. This is why role assignments and overrides no longer have delayed effects, as they did in Moodle 1.7 and 1.8.

Incidentally, you can generate permission tables like the ones in this article using [[The rolesdebug.php roles debugging script]].

==The calculation==

When a user attempts an action that is controlled by a capability, Moodle calls has_capability to see if the action should be permitted. The function is called as follows:

has_capability(CAP,CONTEXT,USER);

where
*CAP is the capability that controls the action (e.g., mod/quiz:attempt)
*CONTEXT is the context in which the capability is being tested
*USER is the user attempting the action

The function returns a true/false result

* ''true'' means the user should be allowed to perform the action
* ''false'' means the user should be prevented from perfoming the action

===Data used by the function===

Suppose USER is about to attempt a quiz (''CAP = mod/quiz:attempt'') in a Module context nested four levels deep within System.

System
|
Category A
|
Subcategory B
|
Course
|
Quiz <--- the user is here

The quiz module will call ''has_capability()'' to see if the user should be allowed to perform this action.

''has_capability()'' considers the following permission data:

* ''Role definitions'' (these are in the System context)
* ''Role assignments'' which may occur in any of the five contexts
* ''Role overrides'' which may occur in any of the contexts except System (there is no concept of override in System).

''has_capability()'' ignores capabilities other than CAP. This simplification lets us view each role or override as if it contains a ''single permission'' having one of the following values

N - Not set
A - Allow
P - Prevent
X - Prohibit

We use the following notation: for a role ''R1'' with permission ''P'', we write ''R1(P)''.

===An example===

In the quiz example, suppose that the user has four roles (''R1'', ''R2'', ''R3'', and ''R4'') and each of the roles has been assigned and overridden as follows:

0 System <---- define R1(A), R2(N), R3(N), R4(P)
| assign R1
|
1 Category A <-------------- overide R1(N) and R4(N)
|
|
2 Subcategory B <---- assign R2 and R3
|
|
3 Course <-------------- override R2(X) and R3(A)
|
|
4 Quiz <---- assign R4 and R1

Note that ''R1'' has been assigned in two different contexts. This is an unusual practice (it is probably someone's error), but since it is legal, we have to consider the possibility that it can happen. In fact this entire example has been contrived to explore the edge cases of the algorithm. In practice, the calculation of permissions is trivial and the function calculates the result you would expect based on common sense and simple mental analysis (for further discussion of this, see [[#A note about the algorithm|A note about the algorithm]] near the end of this article.

===Representing the data in tabular form===

We will set up a table to hold the permission data. The table has
*a column for each context, ordered from highest level (System) to lowest (the context where we want to calculate the permission).
*a row for each context, also listed from highest to lowest.

[[Image:Calculation-3A.png|Empty table]]

The role definitions go in the first row. Put each definition in the column(s) coresponding to the context(s) in which the role is assigned:

[[Image:Calculation-5A.png|Table with assignments added]]

The overrides go in the remaining rows. Each override goes
*in the same column as the role being overridden
*in the row corresponding the context in which the override is made.

To illustrate, let's add just one of the overrides:

[[Image:Calculation-6A.png|Table with just one override]]

R2(X) represents the override to role R2 made in the course context. Let's add the rest of the overrides:

[[Image:Calculation-7A.png|Table with remaining overrides shown]]

The table is now fully populated, and we are ready to calculate the permission.

===The algorithm===

The algorithm follows a path through the table indicated by nodes and arrows in the diagram below and stops as soon as it has a conclusive result.

[[Image:Algorithm_path_through_permission_table_A.png|Algorithm path through permissions data]]

# If there is an X anywhere in the table, STOP. The calculated permission is ''X''
# Go to the START node
# If there is no next node, STOP. The calculated permission is ''P''
# Otherwise, follow the arrow to the next node
#Add the permissions in the node using the numerical equivalents: N = 0, A = +1, P = -1
#* If the sum is positive, STOP. The calculated permission is ''A''
#* If the sum is negative, STOP. The calculated permission is ''P''
#* If the sum is zero, GO TO step 3

Notice that the algorithm stops when either (1) a conclusive result is obtained, or (2) the algorithm reaches the last node without a conclusive result.

===Applying the algorithm to our example===

If we execute the algorithm with the quiz data, we stop at step 1 with a calculated permission of X. That's not very interesting, so let's change the X to a P and see what happens:

[[Image:Calculation-8A.png|Change X to P in permission table]]

Run the algorithm:

*There is No X in the table
*Go to the START node
*Go to the next node
*N + N = 0
*the sum is zero; go to the next node
*A + P = 0
*the sum is zero; go to the next node
*P + A = 0
*the sum is zero; go to the next node
*A + P = 0
*the sum is zero; go to the next node
*N = 0
*the sum is zero; go to the next node
*A = +1
*the sum is positive; STOP. The calculated permission is ''A''

If the calculated permission is ''A'', ''has_capability()'' returns ''true'', and the user is allowed to perform the action.

Had the calculated permission been ''P'' or ''X'', ''has_capability()'' would not immediately return ''false''. Rather, it would test if the user has ''moodle/site:doanything = Allow'' (since this permission trumps all others). The function does this by calling itself:

final result = has_capability(moodle/site:doanything,CONTEXT, USER);

==A note about the algorithm==

Earlier, we said that the algorithm "calculates the result you would expect." But what do we expect? Intuition tells us that permissions closer to the user should carry more weight than more distant permissions. That's why we set up the table the way we did and why the algorithm walks the table in the order that it does. The last column of the table represents the role assignment(s) closest to the user. The second-to-last column represents the role assignent(s) that are next in terms of distance from the user, and so-on. That's why the algorithm considers the columns from right-to-left. Within a column, the algorithm searches upward in order to give higher weight to overrides that are closer to the user. Once again, this matches our intuition about overrides. If there are no overrides in a column (or the overrides are all Not set), the permission in the role definition is used.

==Getting the result you expect==

The calculation is more likely to give "the result you would expect" if you keep your permissions as simple as possible. Therefore, we recommend the following 'rules' for defining and overriding roles. If you understand the description of the calculation above, you should understand why they make sense.

===When defining roles===

... use Allow (A) for things you want the role to be able to do, and use Not set (N) for things you don't care about (which should include most things).

===When overriding permissions===

... leave the permission for every capability as Inherit (N) apart from the few you want to change. For those, use Allow (A) for things you want to allow, and Prevent (P) for things you want to prevent.

===Only use prohibit in special roles===

Prohibit exists to cover extreme scenarios such as the following: Suppose you have a naughty student who is posting inappropriate content in your Moodle site. You need to be able to remove their ability to contribute to public discussions until they have promised not to do it again, but during that time, you cannot completely block them from the resources, quizzes, etc. because they must keep up with their studying. Therefore, you need a way to block their access to specific capabilities e.g. mod/forum:replypost in a way that cannot be overridden. You can do this by creating a special 'Naughty student' role defined with the required permission(s) set to prohibit. Then when you are having problems with a user, you can temporarily assign them this role, either at site level or at course level.

==A practical example==

Suppose that a user, who is assigned the role of Course creator in category B, creates a course (becoming Teacher in the course) and then creates a Lesson within the course. The user is about to edit the lesson (editing lessons is controlled by capability ''mod/lesson:edit''). Here is the permission data:

0 System <---- define Auth user(N), Creator(N), Teacher(A)
| assign Auth user
|
1 Category A
|
|
2 Subcategory B <---- assign Creator
|
|
3 Course <---- assign Teacher
|
|
4 Lesson <---- user attempts to edit lesson

We set up the table and populate it with permission data.

[[Image:Calculation-10A.png|A practical example]]

Since there are no overrides, the table only has data in the first row. The algorithm quickly calculates a permission of ''A'' and returns true. The user is allowed to edit the Lesson!

Now suppose Teacher is overridden in the Lesson context with ''mod/lesson:edit = P''. Then the table changes

[[Image:Calculation-11A.png|A practical example with first override]]

and clearly the user is no longer allowed to edit the Lesson.

But suppose the administrator (or whoever is making the overrides) decided instead to override the ''Creator role'', setting ''mod/lesson:edit = Prevent'' in the Categoy B context:

[[Image:Calculation-12A.png|A practical example with second override]]

Much to everyone's surprise, the user is still allowed to edit the Lesson! If you understood this article, you shouldn't be surprised, and you should be able to explain what happened.

==See also==

*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=90140 Logged in: what role am I?] and [http://moodle.org/mod/forum/discuss.php?d=66782 What happens if a user has multiple roles in a course?] forum discussions.

There is a script that you can use to create tables like the ones in this article. It is very useful for debugging roles-related problems. See [[The rolesdebug.php roles debugging script]].

[[Category:Roles]]

[[fr:Comment les permissions sont calculées ?]]

Grade import

2008-05-26T13:57:37Z

Jisner: /* Importing grades */

{{Grades}}Grades may be imported as a CSV or XML file.

The import file format is the same as the corresponding export format.

Note: Grade import is equivalent to manual grading in the [[Grader report|grader report]]. Thus, if grades for a particular Moodle activity such as an assignment are imported, they can no longer be edited via the assignment submission page.

==Importing grades==
[[Image:Csv grade import.png|thumb|CSV grade import]]
To import grades into the gradebook:

# Decide on an import format - CSV or XML file (see below) - then [[Grade export|export some grades]] using the corresponding export format.
# Edit the export file as appropriate and save it.
# Select your chosen import format from the gradebook dropdown menu.
# Browse and upload your previously saved file.
# Set options as required.
# Click the "Upload grades" button.
# CSV import only: Preview the grade import and choose the column mapping then click the "Upload grades" button to complete the grade import.

You need two permissions to import grades: (1) general permission to import grades and (2) permission to import grades in a particular format. For example, to import CSV grades you need

moodle/grade:import ("Import grades") = Allow
gradeimport/csv:view ("Import grades from CSV") = Allow

==XML import==

XML import requires the numerical grade, activity idnumber and user idnumber.

===Remote file URL===

The remote file URL field is for fetching data from a remote server, such as a student information system.

==CSV import==

CSV import is more flexible than XML import, as you may choose the column mapping.

===Encoding===

If you are unsure of the encoding of your CSV file, try selecting the second option in the encoding dropdown menu. If you've used Excel to produce the CSV file the second option WINDOWS-xxx encoding is probably the correct one. The grade import preview will tell you if you guessed the encoding correctly.

==See also==

Using Moodle forum discussions:
*[http://moodle.org/mod/forum/discuss.php?d=85944 Gradebook confusion]
*[http://moodle.org/mod/forum/discuss.php?d=92081 Can external software insert data into the gradebook?]

The rolesdebug.php roles debugging script

2008-05-13T15:19:50Z

Jisner: /* Essential roles and capabilities concepts */

{{Roles}}{{Moodle 1.9}}
Rolesdebug.php is a stand-alone script that is extremely useful for debugging problems related to roles and permissions. The output can be interpreted by anyone with a good understanding of Moodle's [[Roles and capabilities]] system. If you're a "roles novice" and you need help with a roles-related problem, ask a roles expert to help you with running the script and interpreting the output. If you don't have access to an expert, post a request for help to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]. After using the script a few times, you'll be an expert too!

You can download rolesdebug.php from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and Plugins database]. To install the script, simply drop it into the Moodle root directory or any directory under the root directory.

Rolesdebug.php requires a login, so only someone with a Moodle user account who is currently logged in can use it. Since it is a php script, you will see the output in your browser. No one else will see it unless they're looking over your shoulder. Furthermore, rolesdebug.php will only give you information about YOUR permissions. You cannot use it to get information about another user's permissions (unless you can login as them).

Rolesdebug.php outputs a table giving a spatial view of the role assignments and overrides that affect you in a specified context. From the table, you will be able to see how Moodle calculates a specified permission. The table format is explained (and several examples are given) in the article [[How permissions are calculated]].

Rolesdebug.php reads permission data from the Moodle database but does not modify the database in any way. In this respect, it is similar to other debug scripts in the standard distribution, like the [[TeX_notation_filter#Debugging_TeX_filter | TeX notation debugger]].

==The use case for rolesdebug.php==

The main use case for rolesdebug.php is a ''roles expert helping a roles novice troubleshoot a roles-related problem''. A ''roles expert'' is anyone with a solid understanding of the [[#Essential roles and capabilities concepts | essential roles concepts]] listed in the next section. A ''roles novice'' is any Moodle user with the ability to follow simple instructions from the expert. While the expert and novice may occasionally share the same physical location and have accounts on the same Moodle site, it is not required that they do so. The expert must be able to help the novice without logging in to the novice's site, and by communicating with the novice only by e-mail, messaging, forum posts, etc.. For example, the novice may be a user posting to a moodle.org forum and the expert may be a moodler wanting to be helpful. Even when expert and novice share a physical location and have accounts on the same Moodle site, the expert may not be in a position to give direct help, e.g., by "logging in as" the novice or meeting with the novice. For example, the expert may be a Moodle administrator with an extremely busy schedule.

Here's a typical scenario. Supposed the novice is a teacher who has created a quiz, but is being prevented from previewing the quiz for some unknown reason. The novice reports the problem to moodle.org in a forum post. The expert (a helpful moodler) suspects a roles problem and replies by asking the novice to (1) log in to Moodle, reproduce the problem (2) browse to rolesdebug.php (3) enter two or three parameters as specified by the expert (4) paste the output from rolesdebug.php into a reply to this forum post. The expert views the output and immediately diagnoses the problem.

Secondary use cases for rolesdebug.php include
* a user troubleshooting his own problems
* a user troubleshooting another user's problem while logged in as that user

Note that both of these secondary use cases are equivalent, since there is only one actor (the expert), not two. To keep things simple in the remainder of the article, I'll describe the secondary use case, and I'll refer only to YOU. Keeping the primary use case in mind, it should be clear when "you" means roles expert and when it means the roles novice.

==Essential roles and capabilities concepts==

Interpreting the output from rolesdebug.php requires a solid understanding of the concepts listed below. If any of these concepts are unfamiliar to you, stop and follow the documentation link.

* [[Assign_roles#Contexts | Context]]
* [[Capabilities | Capability]]
* [[Capabilities | Permission]]
* [[Capabilities | Role]]
* [[Assign_roles | Role assignment]]
* [[Override_permissions | Role override]]
* [[How permissions are calculated]]

==Overview of a script session==

First, you will log in to Moodle and navigate to the context where you're having the problem. Perhaps this is a quiz which Moodle, for some unknown reason, is preventing you from attempting. Then, without logging out of Moodle, point your browser at rolesdebug.php (I find it convenient to open a new browser tab for this). Input the ''context'' you're interested in and (optionally) the name of a ''capability'' to investigate, then press the Go button. The script will return a page with a table presenting a spatial view of the role assignments and overrides that affect you in the specified context. From the table, you will be able to see why Moodle is preventing you from attempting the quiz.

==Using the script==

===STEP1===
This step is done in Moodle (you won't use the script until STEP 2). Login to Moodle and navigate into the context where the problem is occurring. Once you're there, you'll make note of the context id, which is needed in STEP 2. I'll tell you [[#How to determine the context id|how to determine the context id]] later.

Incidentally, even if you know the context id, it is essential that you actually navigate to the context. This is because Moodle loads certain permission data "lazily" -- i.e., only when actually needed. Navigating to the context guarantees that Moodle will have loaded the data. For example, suppose the target context is a certain quiz in some course. You must enter the course and click on the Quiz icon.

However if you are debugging a problem related to a change to a user policy such as Site administration -> Front page -> Front page settings -> Default front page role, you must logout and log back in after making the change.

Do not log out!

===STEP 2===
Open a second browser window. In the window, point your browser at
rolesdebug.php. The script URL will be something like

http://yoursite/moodle/rolesdebug.php

Rolesdebug.php will NOT ask you to login because you are already logged in. The script will ask you for three inputs:

* CAPABILITY. If you're only interested in seeing your role assignments and overrides, you can leave this field empty. If you're interested in analyzing a particular permission, you'll need to enter the capability name. For example, if you're interested in the capability that controls your ability to attempt quizzes, enter [[Capabilities/mod/quiz:attempt | mod/quiz:attempt]].

* CONTEXT TYPE. Choose one of the following from the dropdown menu:
**COURSE
**MODULE
**BLOCK
**COURSECAT
**USER
**SYSTEM

* CONTEXT ID. The context id is a number at the end of the URL of the page you found in STEP 1. See [[#How to determine the context id|How to determine the context id]] below.

Incidentally, MODULE means activity or resource. There is no FRONT PAGE context. If you're interested in the Front page context, choose COURSE and specify a context id of 1.

Here's an example of input:

[[Image:sample_input_quiz_attempt.png|sample input when investigating a quiz attempt]]

===STEP 3===
Press the Go button. Rolesdebug.php will return a page of information. The main item on the page is a table giving a spatial view of all the role assignments and overrides that affect you in the specified context.

==How to read the output==
Let's look at a typical output for the input parameters from the last section.
[[Image:sample_output_quiz_attempt.png|sample output when investigating a quiz attempt]]

The first three lines of output (1) simply echo your input values, and the next two lines (2) remind you of who YOU are, and tell you the actual name of the context you have selected. Check these carefully to make
sure you are who you think you are, and have specified the correct context.

For each of your roles, you will see a line of the form ''alias = role name'' where
* ''role name'' is the actual role name
* ''alias'' is the name used to represent the role in the table

In the example, ''R7 = user'' means the the role user (the shortname of Authorized user) will be represented in the table by the alias R7. Aliases are used because long role names could make the table very wide, forcing you to scroll horizontally. By using aliases, the table will hopefully fit in a window, allowing you to see the entire table in a single a glance.

Next comes the table (4). I'll have a lot more to say about the table below.

If you specified a capability, then you will see the three lines immediately after the table (5).
* The first line gives the calculated permission, which is based on the table. The value can be either A (Allow) or P (Prevent).
* The second line tells you if you are able to "do anything," that is, if you have moodle/site:doanything = Allow (this is typically only true for administrators)
* The third line tells you if you can "do this." If you can do anything, you can obviously do this regardless of the calculated permission.

====How to read the table====

If the target context is N levels deep, the table will have N rows and N columns, one for each context level. The example above has four levels:

System
|
|
Category "A"
|
|
Course "cooking"
|
|
Module "quiz-1"

The column headings give the names of the contexts. These are listed in order of increasing depth: System, A, cooking, quiz-1.

To save space, the table does not have row headings. If it did, they would be the same as the column headings. For example, row 1 would be labeled "System" and row 4 would be labeled "quiz-1".

The first row of the table contains the role assignments made in each context level. In the example, you can see that R7 (Authorized user) is assigned in the System context and R5 (Student) is assigned in the course context. If there are no overrides (as in this example) you will only see entries in row 1.

The letters N and A in parentheses are the values of the capabilities in the role definitions. The possible values are:

N - Not set
A - Allow
P - Prevent
X - Prohibit

"Not set" means that the role doesn't say anything about the capability. In the example, we see that the Student role allows
quiz attempts, while the Authorized user role doesn't have anything
to say about quiz attempts.

If there are role overrides, there will be entries in other rows of the table. Overrides have the same format as the assignments in row 1. An override is shown in the ROW of the context where it is made, and the COLUMN of the assignment that it overrides.

To illustrate, let's override the Student role in the Quiz context, setting mod/quiz:attempt to Prevent, and then rerun rolesdebug.php. Of course before running the script, the student must attempt the quiz. This time, the student should be prevented because of the override. Now we run the script and get the following output:
[[Image:sample_output_quiz_attempt_with_override.png|sample output when investigating a quiz attempt and there is an override]]

Notice the newly added R5(P). This is the override. It is in the fourth row because the override was made in the quiz context, and it is in the course column because the Student role was assigned in the Course context.

The calculated permission is now P, as expected.

====How Moodle calculates the permission====
For a full explanation of how permissions are calculated, see the article [[How permissions are calculated | How permissions are calculated]]. This section merely illustrates the calculation for the examples given in this article.

For the original example (where we only had role assignments in row 1),
Moodle scans the table from right to left.
[[Image:sample_output_quiz_attempt_showing_path.png|how to scan the table when investigating a quiz attempt]]
Since the first permission it hits is an 'A' the calculated permission is 'A'.

When we added the override, Moodle scans the table in a zig-zag fashion, as shown below.
[[Image:sample_output_quiz_attempt_with_override_showing_path.png|how to scan the table when investigating a quiz attempt and there is an override]]
Since the first permission it hits is a 'P' the calculated permission is 'P'.

==How to determine the context id==
Here are rules for determining the context id for each context type.
===COURSE===
For a COURSE context, the context id is the course id. You can get the course id from the URL that appears in the address bar when when you're on the course page. For example when I point my browser at the "Features" course on demo.moodle.org, I see this:

[[Image:URI_of_course_in_address_bar.png|URI of course is shown in the address bar]]

The course id, and therefore the context id for this course is 2.

If Moodle won't let you enter the course for some reason, but you can see a link to the course, let your mouse hover over the link as in the following screenshot. Your browser will show you the address at the bottom of the window.

[[Image:URI_of_course_at_bottom_of_browser_window.png|URI of course is shown at the bottom of the browser window]]

The front page of a Moodle site is also a course, but you can't use either of the above tricks to get the id. ''The front page course id is 1.''

===MODULE (activity or resource)===
For a MODULE context, the context id is the activity or resource id. You can get the id from the URL that appears in the address bar when you're viewing the activity or resource, or from the bottom of the browser window when you let your mouse hover over a link. Here are some examples:

http://demo.moodle.org/mod/choice/view.php?id=25
http://demo.moodle.org/mod/forum/view.php?id=28
http://demo.moodle.org/mod/lesson/view.php?id=38
http://demo.moodle.org/mod/quiz/view.php?id=61
http://demo.moodle.org/mod/resource/view.php?id=10
http://demo.moodle.org/mod/resource/view.php?id=48

The context id's for these modules are 25, 28, 38, 61, 10, and 48.

===BLOCK===
For a BLOCK context, the context id is the "instanceid" of the block. To get the instanceid, turn editing on and let the mouse hover over the "eye" icon in the block header. Then take the instanceid from URL that appears in the at the bottom of the window. For example:

http://demo.moodle.org/course/view.php?id=28&instanceid=19...

The context id for this block is 19. Note that for blocks, only a user who can turn editing on can get the instanceid.

===COURSECAT===
For a COURSECAT context, the context id is the category id. You can get the id from the URL that appears in the address bar when you're on the category page. If the site has only one category (usually called "Miscellaneous") the id is 1. If there is more than one category, the easiest way to get the category id for a specific category is to have a Category list or a Combo list on the front page of the site (or a Courses block) and let your mouse hover over one of the links. For example:

http://mysite/course/category.php?id=3

The context id for this category is 3

===USER===
For a USER context, the context id is the user id. You can get the id from the URL that appears in the address bar when you're on a profile page, or from the bottom of the browser window when you let your mouse hover over a user's name. For example:

http://demo.moodle.org/user/view.php?id=6&course=1

The context id for this user is 6

===SYSTEM===
There is only one SYSTEM context. Its id is 1.

==Rolesdebug says I should be able do this, but Moodle won't let me!==
When this happens it is because Moodle is calculating your permission differently from the way you think it is. Here are three possibilities:
* Moodle may be calculating the permission in a ''different context'' than the one you specified (Moodle calculates some permissions explicitly in System or User contexts).
* If you are assigned any legacy roles (particularly Guest), Moodle may be ignoring the calculated permission. For example, Guest has been edited, allowing it to post to Forums, Rolesdebug will report that you can post, but Moodle will simply ignore the permission. If you ask a developer why, they will tell you "because guests can never post."
* The action you are attempting requires two or more permissions.

When such a disagreement occurs, further research will be needed to debug the problem. Sometimes you can find the answer in documentation. For example, when a permission is calculated in a different context, the documentation usually says so. Other times you will just need to read the code.

[[Category:Contributed code]]

The rolesdebug.php roles debugging script

2008-05-13T15:19:02Z

Jisner: /* The use case for rolesdebug.php */

{{Roles}}{{Moodle 1.9}}
Rolesdebug.php is a stand-alone script that is extremely useful for debugging problems related to roles and permissions. The output can be interpreted by anyone with a good understanding of Moodle's [[Roles and capabilities]] system. If you're a "roles novice" and you need help with a roles-related problem, ask a roles expert to help you with running the script and interpreting the output. If you don't have access to an expert, post a request for help to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]. After using the script a few times, you'll be an expert too!

You can download rolesdebug.php from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and Plugins database]. To install the script, simply drop it into the Moodle root directory or any directory under the root directory.

Rolesdebug.php requires a login, so only someone with a Moodle user account who is currently logged in can use it. Since it is a php script, you will see the output in your browser. No one else will see it unless they're looking over your shoulder. Furthermore, rolesdebug.php will only give you information about YOUR permissions. You cannot use it to get information about another user's permissions (unless you can login as them).

Rolesdebug.php outputs a table giving a spatial view of the role assignments and overrides that affect you in a specified context. From the table, you will be able to see how Moodle calculates a specified permission. The table format is explained (and several examples are given) in the article [[How permissions are calculated]].

Rolesdebug.php reads permission data from the Moodle database but does not modify the database in any way. In this respect, it is similar to other debug scripts in the standard distribution, like the [[TeX_notation_filter#Debugging_TeX_filter | TeX notation debugger]].

==The use case for rolesdebug.php==

The main use case for rolesdebug.php is a ''roles expert helping a roles novice troubleshoot a roles-related problem''. A ''roles expert'' is anyone with a solid understanding of the [[#Essential roles and capabilities concepts | essential roles concepts]] listed in the next section. A ''roles novice'' is any Moodle user with the ability to follow simple instructions from the expert. While the expert and novice may occasionally share the same physical location and have accounts on the same Moodle site, it is not required that they do so. The expert must be able to help the novice without logging in to the novice's site, and by communicating with the novice only by e-mail, messaging, forum posts, etc.. For example, the novice may be a user posting to a moodle.org forum and the expert may be a moodler wanting to be helpful. Even when expert and novice share a physical location and have accounts on the same Moodle site, the expert may not be in a position to give direct help, e.g., by "logging in as" the novice or meeting with the novice. For example, the expert may be a Moodle administrator with an extremely busy schedule.

Here's a typical scenario. Supposed the novice is a teacher who has created a quiz, but is being prevented from previewing the quiz for some unknown reason. The novice reports the problem to moodle.org in a forum post. The expert (a helpful moodler) suspects a roles problem and replies by asking the novice to (1) log in to Moodle, reproduce the problem (2) browse to rolesdebug.php (3) enter two or three parameters as specified by the expert (4) paste the output from rolesdebug.php into a reply to this forum post. The expert views the output and immediately diagnoses the problem.

Secondary use cases for rolesdebug.php include
* a user troubleshooting his own problems
* a user troubleshooting another user's problem while logged in as that user

Note that both of these secondary use cases are equivalent, since there is only one actor (the expert), not two. To keep things simple in the remainder of the article, I'll describe the secondary use case, and I'll refer only to YOU. Keeping the primary use case in mind, it should be clear when "you" means roles expert and when it means the roles novice.

==Essential roles and capabilities concepts==

Interpreting the output from rolesdebug.php requires at least a basic understanding of the concepts listed below. If any of these concepts are unfamiliar to you, stop and follow the documentation link.

* [[Assign_roles#Contexts | Context]]
* [[Capabilities | Capability]]
* [[Capabilities | Permission]]
* [[Capabilities | Role]]
* [[Assign_roles | Role assignment]]
* [[Override_permissions | Role override]]
* [[How permissions are calculated]]

==Overview of a script session==

First, you will log in to Moodle and navigate to the context where you're having the problem. Perhaps this is a quiz which Moodle, for some unknown reason, is preventing you from attempting. Then, without logging out of Moodle, point your browser at rolesdebug.php (I find it convenient to open a new browser tab for this). Input the ''context'' you're interested in and (optionally) the name of a ''capability'' to investigate, then press the Go button. The script will return a page with a table presenting a spatial view of the role assignments and overrides that affect you in the specified context. From the table, you will be able to see why Moodle is preventing you from attempting the quiz.

==Using the script==

===STEP1===
This step is done in Moodle (you won't use the script until STEP 2). Login to Moodle and navigate into the context where the problem is occurring. Once you're there, you'll make note of the context id, which is needed in STEP 2. I'll tell you [[#How to determine the context id|how to determine the context id]] later.

Incidentally, even if you know the context id, it is essential that you actually navigate to the context. This is because Moodle loads certain permission data "lazily" -- i.e., only when actually needed. Navigating to the context guarantees that Moodle will have loaded the data. For example, suppose the target context is a certain quiz in some course. You must enter the course and click on the Quiz icon.

However if you are debugging a problem related to a change to a user policy such as Site administration -> Front page -> Front page settings -> Default front page role, you must logout and log back in after making the change.

Do not log out!

===STEP 2===
Open a second browser window. In the window, point your browser at
rolesdebug.php. The script URL will be something like

http://yoursite/moodle/rolesdebug.php

Rolesdebug.php will NOT ask you to login because you are already logged in. The script will ask you for three inputs:

* CAPABILITY. If you're only interested in seeing your role assignments and overrides, you can leave this field empty. If you're interested in analyzing a particular permission, you'll need to enter the capability name. For example, if you're interested in the capability that controls your ability to attempt quizzes, enter [[Capabilities/mod/quiz:attempt | mod/quiz:attempt]].

* CONTEXT TYPE. Choose one of the following from the dropdown menu:
**COURSE
**MODULE
**BLOCK
**COURSECAT
**USER
**SYSTEM

* CONTEXT ID. The context id is a number at the end of the URL of the page you found in STEP 1. See [[#How to determine the context id|How to determine the context id]] below.

Incidentally, MODULE means activity or resource. There is no FRONT PAGE context. If you're interested in the Front page context, choose COURSE and specify a context id of 1.

Here's an example of input:

[[Image:sample_input_quiz_attempt.png|sample input when investigating a quiz attempt]]

===STEP 3===
Press the Go button. Rolesdebug.php will return a page of information. The main item on the page is a table giving a spatial view of all the role assignments and overrides that affect you in the specified context.

==How to read the output==
Let's look at a typical output for the input parameters from the last section.
[[Image:sample_output_quiz_attempt.png|sample output when investigating a quiz attempt]]

The first three lines of output (1) simply echo your input values, and the next two lines (2) remind you of who YOU are, and tell you the actual name of the context you have selected. Check these carefully to make
sure you are who you think you are, and have specified the correct context.

For each of your roles, you will see a line of the form ''alias = role name'' where
* ''role name'' is the actual role name
* ''alias'' is the name used to represent the role in the table

In the example, ''R7 = user'' means the the role user (the shortname of Authorized user) will be represented in the table by the alias R7. Aliases are used because long role names could make the table very wide, forcing you to scroll horizontally. By using aliases, the table will hopefully fit in a window, allowing you to see the entire table in a single a glance.

Next comes the table (4). I'll have a lot more to say about the table below.

If you specified a capability, then you will see the three lines immediately after the table (5).
* The first line gives the calculated permission, which is based on the table. The value can be either A (Allow) or P (Prevent).
* The second line tells you if you are able to "do anything," that is, if you have moodle/site:doanything = Allow (this is typically only true for administrators)
* The third line tells you if you can "do this." If you can do anything, you can obviously do this regardless of the calculated permission.

====How to read the table====

If the target context is N levels deep, the table will have N rows and N columns, one for each context level. The example above has four levels:

System
|
|
Category "A"
|
|
Course "cooking"
|
|
Module "quiz-1"

The column headings give the names of the contexts. These are listed in order of increasing depth: System, A, cooking, quiz-1.

To save space, the table does not have row headings. If it did, they would be the same as the column headings. For example, row 1 would be labeled "System" and row 4 would be labeled "quiz-1".

The first row of the table contains the role assignments made in each context level. In the example, you can see that R7 (Authorized user) is assigned in the System context and R5 (Student) is assigned in the course context. If there are no overrides (as in this example) you will only see entries in row 1.

The letters N and A in parentheses are the values of the capabilities in the role definitions. The possible values are:

N - Not set
A - Allow
P - Prevent
X - Prohibit

"Not set" means that the role doesn't say anything about the capability. In the example, we see that the Student role allows
quiz attempts, while the Authorized user role doesn't have anything
to say about quiz attempts.

If there are role overrides, there will be entries in other rows of the table. Overrides have the same format as the assignments in row 1. An override is shown in the ROW of the context where it is made, and the COLUMN of the assignment that it overrides.

To illustrate, let's override the Student role in the Quiz context, setting mod/quiz:attempt to Prevent, and then rerun rolesdebug.php. Of course before running the script, the student must attempt the quiz. This time, the student should be prevented because of the override. Now we run the script and get the following output:
[[Image:sample_output_quiz_attempt_with_override.png|sample output when investigating a quiz attempt and there is an override]]

Notice the newly added R5(P). This is the override. It is in the fourth row because the override was made in the quiz context, and it is in the course column because the Student role was assigned in the Course context.

The calculated permission is now P, as expected.

====How Moodle calculates the permission====
For a full explanation of how permissions are calculated, see the article [[How permissions are calculated | How permissions are calculated]]. This section merely illustrates the calculation for the examples given in this article.

For the original example (where we only had role assignments in row 1),
Moodle scans the table from right to left.
[[Image:sample_output_quiz_attempt_showing_path.png|how to scan the table when investigating a quiz attempt]]
Since the first permission it hits is an 'A' the calculated permission is 'A'.

When we added the override, Moodle scans the table in a zig-zag fashion, as shown below.
[[Image:sample_output_quiz_attempt_with_override_showing_path.png|how to scan the table when investigating a quiz attempt and there is an override]]
Since the first permission it hits is a 'P' the calculated permission is 'P'.

==How to determine the context id==
Here are rules for determining the context id for each context type.
===COURSE===
For a COURSE context, the context id is the course id. You can get the course id from the URL that appears in the address bar when when you're on the course page. For example when I point my browser at the "Features" course on demo.moodle.org, I see this:

[[Image:URI_of_course_in_address_bar.png|URI of course is shown in the address bar]]

The course id, and therefore the context id for this course is 2.

If Moodle won't let you enter the course for some reason, but you can see a link to the course, let your mouse hover over the link as in the following screenshot. Your browser will show you the address at the bottom of the window.

[[Image:URI_of_course_at_bottom_of_browser_window.png|URI of course is shown at the bottom of the browser window]]

The front page of a Moodle site is also a course, but you can't use either of the above tricks to get the id. ''The front page course id is 1.''

===MODULE (activity or resource)===
For a MODULE context, the context id is the activity or resource id. You can get the id from the URL that appears in the address bar when you're viewing the activity or resource, or from the bottom of the browser window when you let your mouse hover over a link. Here are some examples:

http://demo.moodle.org/mod/choice/view.php?id=25
http://demo.moodle.org/mod/forum/view.php?id=28
http://demo.moodle.org/mod/lesson/view.php?id=38
http://demo.moodle.org/mod/quiz/view.php?id=61
http://demo.moodle.org/mod/resource/view.php?id=10
http://demo.moodle.org/mod/resource/view.php?id=48

The context id's for these modules are 25, 28, 38, 61, 10, and 48.

===BLOCK===
For a BLOCK context, the context id is the "instanceid" of the block. To get the instanceid, turn editing on and let the mouse hover over the "eye" icon in the block header. Then take the instanceid from URL that appears in the at the bottom of the window. For example:

http://demo.moodle.org/course/view.php?id=28&instanceid=19...

The context id for this block is 19. Note that for blocks, only a user who can turn editing on can get the instanceid.

===COURSECAT===
For a COURSECAT context, the context id is the category id. You can get the id from the URL that appears in the address bar when you're on the category page. If the site has only one category (usually called "Miscellaneous") the id is 1. If there is more than one category, the easiest way to get the category id for a specific category is to have a Category list or a Combo list on the front page of the site (or a Courses block) and let your mouse hover over one of the links. For example:

http://mysite/course/category.php?id=3

The context id for this category is 3

===USER===
For a USER context, the context id is the user id. You can get the id from the URL that appears in the address bar when you're on a profile page, or from the bottom of the browser window when you let your mouse hover over a user's name. For example:

http://demo.moodle.org/user/view.php?id=6&course=1

The context id for this user is 6

===SYSTEM===
There is only one SYSTEM context. Its id is 1.

==Rolesdebug says I should be able do this, but Moodle won't let me!==
When this happens it is because Moodle is calculating your permission differently from the way you think it is. Here are three possibilities:
* Moodle may be calculating the permission in a ''different context'' than the one you specified (Moodle calculates some permissions explicitly in System or User contexts).
* If you are assigned any legacy roles (particularly Guest), Moodle may be ignoring the calculated permission. For example, Guest has been edited, allowing it to post to Forums, Rolesdebug will report that you can post, but Moodle will simply ignore the permission. If you ask a developer why, they will tell you "because guests can never post."
* The action you are attempting requires two or more permissions.

When such a disagreement occurs, further research will be needed to debug the problem. Sometimes you can find the answer in documentation. For example, when a permission is calculated in a different context, the documentation usually says so. Other times you will just need to read the code.

[[Category:Contributed code]]

The rolesdebug.php roles debugging script

2008-05-13T15:17:55Z

Jisner: /* The use case for rolesdebug.php */

{{Roles}}{{Moodle 1.9}}
Rolesdebug.php is a stand-alone script that is extremely useful for debugging problems related to roles and permissions. The output can be interpreted by anyone with a good understanding of Moodle's [[Roles and capabilities]] system. If you're a "roles novice" and you need help with a roles-related problem, ask a roles expert to help you with running the script and interpreting the output. If you don't have access to an expert, post a request for help to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]. After using the script a few times, you'll be an expert too!

You can download rolesdebug.php from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and Plugins database]. To install the script, simply drop it into the Moodle root directory or any directory under the root directory.

Rolesdebug.php requires a login, so only someone with a Moodle user account who is currently logged in can use it. Since it is a php script, you will see the output in your browser. No one else will see it unless they're looking over your shoulder. Furthermore, rolesdebug.php will only give you information about YOUR permissions. You cannot use it to get information about another user's permissions (unless you can login as them).

Rolesdebug.php outputs a table giving a spatial view of the role assignments and overrides that affect you in a specified context. From the table, you will be able to see how Moodle calculates a specified permission. The table format is explained (and several examples are given) in the article [[How permissions are calculated]].

Rolesdebug.php reads permission data from the Moodle database but does not modify the database in any way. In this respect, it is similar to other debug scripts in the standard distribution, like the [[TeX_notation_filter#Debugging_TeX_filter | TeX notation debugger]].

==The use case for rolesdebug.php==

The main use case for rolesdebug.php is a ''roles expert helping a roles novice troubleshoot a roles-related problem''. A ''roles expert'' is anyone with a solid understanding of the [[#Essential roles and capabilities concepts | essential roles concepts]] listed in the next section. A ''roles novice'' is any Moodle user with the ability to follow simple instructions from the expert. While the expert and novice may occasionally share the same physical location and have accounts on the same Moodle site, it is not required that they do so. The expert must be able to help the novice without logging in to the novice's site, and by communicating with the novice only by e-mail, messaging, forum posts, etc.. For example, the novice may be a user posting to a moodle.org forum and the expert may be a moodler wanting to be helpful. Even when expert and novice share a physical location and have accounts on the same Moodle site, the expert may not be in a position to give direct help, e.g., by "logging in as" the novice or meeting with the novice. For example, the expert may be a Moodle administrator with an extremely busy schedule.

Here's a typical scenario. Supposed the novice is a teacher who has created a quiz, but is being prevented from previewing the quiz for some unknown reason. The novice reports the problem to moodle.org in a forum post. The expert (a helpful moodler) suspects a roles problem and replies by asking the novice to (1) log in to Moodle, reproduce the problem (2) browse to rolesdebug.php (3) enter two or three parameters as specified by the expert (4) paste the output from rolesdebug.php into a reply to this forum post. The expert reviews the output and (hopefully) diagnoses the problem.

Secondary use cases for rolesdebug.php include
* a user troubleshooting his own problems
* a user troubleshooting another user's problem while logged in as that user

Note that both of these secondary use cases are equivalent, since there is only one actor (the expert), not two. To keep things simple in the remainder of the article, I'll describe the secondary use case, and I'll refer only to YOU. Keeping the primary use case in mind, it should be clear when "you" means roles expert and when it means the roles novice.

==Essential roles and capabilities concepts==

Interpreting the output from rolesdebug.php requires at least a basic understanding of the concepts listed below. If any of these concepts are unfamiliar to you, stop and follow the documentation link.

* [[Assign_roles#Contexts | Context]]
* [[Capabilities | Capability]]
* [[Capabilities | Permission]]
* [[Capabilities | Role]]
* [[Assign_roles | Role assignment]]
* [[Override_permissions | Role override]]
* [[How permissions are calculated]]

==Overview of a script session==

First, you will log in to Moodle and navigate to the context where you're having the problem. Perhaps this is a quiz which Moodle, for some unknown reason, is preventing you from attempting. Then, without logging out of Moodle, point your browser at rolesdebug.php (I find it convenient to open a new browser tab for this). Input the ''context'' you're interested in and (optionally) the name of a ''capability'' to investigate, then press the Go button. The script will return a page with a table presenting a spatial view of the role assignments and overrides that affect you in the specified context. From the table, you will be able to see why Moodle is preventing you from attempting the quiz.

==Using the script==

===STEP1===
This step is done in Moodle (you won't use the script until STEP 2). Login to Moodle and navigate into the context where the problem is occurring. Once you're there, you'll make note of the context id, which is needed in STEP 2. I'll tell you [[#How to determine the context id|how to determine the context id]] later.

Incidentally, even if you know the context id, it is essential that you actually navigate to the context. This is because Moodle loads certain permission data "lazily" -- i.e., only when actually needed. Navigating to the context guarantees that Moodle will have loaded the data. For example, suppose the target context is a certain quiz in some course. You must enter the course and click on the Quiz icon.

However if you are debugging a problem related to a change to a user policy such as Site administration -> Front page -> Front page settings -> Default front page role, you must logout and log back in after making the change.

Do not log out!

===STEP 2===
Open a second browser window. In the window, point your browser at
rolesdebug.php. The script URL will be something like

http://yoursite/moodle/rolesdebug.php

Rolesdebug.php will NOT ask you to login because you are already logged in. The script will ask you for three inputs:

* CAPABILITY. If you're only interested in seeing your role assignments and overrides, you can leave this field empty. If you're interested in analyzing a particular permission, you'll need to enter the capability name. For example, if you're interested in the capability that controls your ability to attempt quizzes, enter [[Capabilities/mod/quiz:attempt | mod/quiz:attempt]].

* CONTEXT TYPE. Choose one of the following from the dropdown menu:
**COURSE
**MODULE
**BLOCK
**COURSECAT
**USER
**SYSTEM

* CONTEXT ID. The context id is a number at the end of the URL of the page you found in STEP 1. See [[#How to determine the context id|How to determine the context id]] below.

Incidentally, MODULE means activity or resource. There is no FRONT PAGE context. If you're interested in the Front page context, choose COURSE and specify a context id of 1.

Here's an example of input:

[[Image:sample_input_quiz_attempt.png|sample input when investigating a quiz attempt]]

===STEP 3===
Press the Go button. Rolesdebug.php will return a page of information. The main item on the page is a table giving a spatial view of all the role assignments and overrides that affect you in the specified context.

==How to read the output==
Let's look at a typical output for the input parameters from the last section.
[[Image:sample_output_quiz_attempt.png|sample output when investigating a quiz attempt]]

The first three lines of output (1) simply echo your input values, and the next two lines (2) remind you of who YOU are, and tell you the actual name of the context you have selected. Check these carefully to make
sure you are who you think you are, and have specified the correct context.

For each of your roles, you will see a line of the form ''alias = role name'' where
* ''role name'' is the actual role name
* ''alias'' is the name used to represent the role in the table

In the example, ''R7 = user'' means the the role user (the shortname of Authorized user) will be represented in the table by the alias R7. Aliases are used because long role names could make the table very wide, forcing you to scroll horizontally. By using aliases, the table will hopefully fit in a window, allowing you to see the entire table in a single a glance.

Next comes the table (4). I'll have a lot more to say about the table below.

If you specified a capability, then you will see the three lines immediately after the table (5).
* The first line gives the calculated permission, which is based on the table. The value can be either A (Allow) or P (Prevent).
* The second line tells you if you are able to "do anything," that is, if you have moodle/site:doanything = Allow (this is typically only true for administrators)
* The third line tells you if you can "do this." If you can do anything, you can obviously do this regardless of the calculated permission.

====How to read the table====

If the target context is N levels deep, the table will have N rows and N columns, one for each context level. The example above has four levels:

System
|
|
Category "A"
|
|
Course "cooking"
|
|
Module "quiz-1"

The column headings give the names of the contexts. These are listed in order of increasing depth: System, A, cooking, quiz-1.

To save space, the table does not have row headings. If it did, they would be the same as the column headings. For example, row 1 would be labeled "System" and row 4 would be labeled "quiz-1".

The first row of the table contains the role assignments made in each context level. In the example, you can see that R7 (Authorized user) is assigned in the System context and R5 (Student) is assigned in the course context. If there are no overrides (as in this example) you will only see entries in row 1.

The letters N and A in parentheses are the values of the capabilities in the role definitions. The possible values are:

N - Not set
A - Allow
P - Prevent
X - Prohibit

"Not set" means that the role doesn't say anything about the capability. In the example, we see that the Student role allows
quiz attempts, while the Authorized user role doesn't have anything
to say about quiz attempts.

If there are role overrides, there will be entries in other rows of the table. Overrides have the same format as the assignments in row 1. An override is shown in the ROW of the context where it is made, and the COLUMN of the assignment that it overrides.

To illustrate, let's override the Student role in the Quiz context, setting mod/quiz:attempt to Prevent, and then rerun rolesdebug.php. Of course before running the script, the student must attempt the quiz. This time, the student should be prevented because of the override. Now we run the script and get the following output:
[[Image:sample_output_quiz_attempt_with_override.png|sample output when investigating a quiz attempt and there is an override]]

Notice the newly added R5(P). This is the override. It is in the fourth row because the override was made in the quiz context, and it is in the course column because the Student role was assigned in the Course context.

The calculated permission is now P, as expected.

====How Moodle calculates the permission====
For a full explanation of how permissions are calculated, see the article [[How permissions are calculated | How permissions are calculated]]. This section merely illustrates the calculation for the examples given in this article.

For the original example (where we only had role assignments in row 1),
Moodle scans the table from right to left.
[[Image:sample_output_quiz_attempt_showing_path.png|how to scan the table when investigating a quiz attempt]]
Since the first permission it hits is an 'A' the calculated permission is 'A'.

When we added the override, Moodle scans the table in a zig-zag fashion, as shown below.
[[Image:sample_output_quiz_attempt_with_override_showing_path.png|how to scan the table when investigating a quiz attempt and there is an override]]
Since the first permission it hits is a 'P' the calculated permission is 'P'.

==How to determine the context id==
Here are rules for determining the context id for each context type.
===COURSE===
For a COURSE context, the context id is the course id. You can get the course id from the URL that appears in the address bar when when you're on the course page. For example when I point my browser at the "Features" course on demo.moodle.org, I see this:

[[Image:URI_of_course_in_address_bar.png|URI of course is shown in the address bar]]

The course id, and therefore the context id for this course is 2.

If Moodle won't let you enter the course for some reason, but you can see a link to the course, let your mouse hover over the link as in the following screenshot. Your browser will show you the address at the bottom of the window.

[[Image:URI_of_course_at_bottom_of_browser_window.png|URI of course is shown at the bottom of the browser window]]

The front page of a Moodle site is also a course, but you can't use either of the above tricks to get the id. ''The front page course id is 1.''

===MODULE (activity or resource)===
For a MODULE context, the context id is the activity or resource id. You can get the id from the URL that appears in the address bar when you're viewing the activity or resource, or from the bottom of the browser window when you let your mouse hover over a link. Here are some examples:

http://demo.moodle.org/mod/choice/view.php?id=25
http://demo.moodle.org/mod/forum/view.php?id=28
http://demo.moodle.org/mod/lesson/view.php?id=38
http://demo.moodle.org/mod/quiz/view.php?id=61
http://demo.moodle.org/mod/resource/view.php?id=10
http://demo.moodle.org/mod/resource/view.php?id=48

The context id's for these modules are 25, 28, 38, 61, 10, and 48.

===BLOCK===
For a BLOCK context, the context id is the "instanceid" of the block. To get the instanceid, turn editing on and let the mouse hover over the "eye" icon in the block header. Then take the instanceid from URL that appears in the at the bottom of the window. For example:

http://demo.moodle.org/course/view.php?id=28&instanceid=19...

The context id for this block is 19. Note that for blocks, only a user who can turn editing on can get the instanceid.

===COURSECAT===
For a COURSECAT context, the context id is the category id. You can get the id from the URL that appears in the address bar when you're on the category page. If the site has only one category (usually called "Miscellaneous") the id is 1. If there is more than one category, the easiest way to get the category id for a specific category is to have a Category list or a Combo list on the front page of the site (or a Courses block) and let your mouse hover over one of the links. For example:

http://mysite/course/category.php?id=3

The context id for this category is 3

===USER===
For a USER context, the context id is the user id. You can get the id from the URL that appears in the address bar when you're on a profile page, or from the bottom of the browser window when you let your mouse hover over a user's name. For example:

http://demo.moodle.org/user/view.php?id=6&course=1

The context id for this user is 6

===SYSTEM===
There is only one SYSTEM context. Its id is 1.

==Rolesdebug says I should be able do this, but Moodle won't let me!==
When this happens it is because Moodle is calculating your permission differently from the way you think it is. Here are three possibilities:
* Moodle may be calculating the permission in a ''different context'' than the one you specified (Moodle calculates some permissions explicitly in System or User contexts).
* If you are assigned any legacy roles (particularly Guest), Moodle may be ignoring the calculated permission. For example, Guest has been edited, allowing it to post to Forums, Rolesdebug will report that you can post, but Moodle will simply ignore the permission. If you ask a developer why, they will tell you "because guests can never post."
* The action you are attempting requires two or more permissions.

When such a disagreement occurs, further research will be needed to debug the problem. Sometimes you can find the answer in documentation. For example, when a permission is calculated in a different context, the documentation usually says so. Other times you will just need to read the code.

[[Category:Contributed code]]

The rolesdebug.php roles debugging script

2008-05-13T15:16:47Z

Jisner: /* The use case for rolesdebug.php */

{{Roles}}{{Moodle 1.9}}
Rolesdebug.php is a stand-alone script that is extremely useful for debugging problems related to roles and permissions. The output can be interpreted by anyone with a good understanding of Moodle's [[Roles and capabilities]] system. If you're a "roles novice" and you need help with a roles-related problem, ask a roles expert to help you with running the script and interpreting the output. If you don't have access to an expert, post a request for help to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]. After using the script a few times, you'll be an expert too!

You can download rolesdebug.php from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and Plugins database]. To install the script, simply drop it into the Moodle root directory or any directory under the root directory.

Rolesdebug.php requires a login, so only someone with a Moodle user account who is currently logged in can use it. Since it is a php script, you will see the output in your browser. No one else will see it unless they're looking over your shoulder. Furthermore, rolesdebug.php will only give you information about YOUR permissions. You cannot use it to get information about another user's permissions (unless you can login as them).

Rolesdebug.php outputs a table giving a spatial view of the role assignments and overrides that affect you in a specified context. From the table, you will be able to see how Moodle calculates a specified permission. The table format is explained (and several examples are given) in the article [[How permissions are calculated]].

Rolesdebug.php reads permission data from the Moodle database but does not modify the database in any way. In this respect, it is similar to other debug scripts in the standard distribution, like the [[TeX_notation_filter#Debugging_TeX_filter | TeX notation debugger]].

==The use case for rolesdebug.php==

The main use case for rolesdebug.php is a ''roles expert helping a roles novice troubleshoot a roles-related problem''. A ''roles expert'' is anyone with a solid understanding of the [[#Essential roles and capabilities concepts | essential roles concepts]] listed in the next section. A ''roles novice'' is any Moodle user with the ability to follow simple instructions from the expert. While the expert and novice may occasionally share the same physical location and have accounts on the same Moodle site, it is not required. The expert must be able to help the novice without logging in to the novice's site, and by communicating with the novice only by e-mail, messaging, forum posts, etc.. For example, the novice may be a user posting to a moodle.org forum and the expert may be a moodler wanting to be helpful. Even when expert and novice share a physical location and have accounts on the same Moodle site, the expert may not be in a position to give direct help, e.g., by "logging in as" the novice or meeting with the novice. For example, the expert may be a Moodle administrator with an extremely busy schedule.

Here's a typical scenario. Supposed the novice is a teacher who has created a quiz, but is being prevented from previewing the quiz for some unknown reason. The novice reports the problem to moodle.org in a forum post. The expert (a helpful moodler) suspects a roles problem and replies by asking the novice to (1) log in to Moodle, reproduce the problem (2) browse to rolesdebug.php (3) enter two or three parameters as specified by the expert (4) paste the output from rolesdebug.php into a reply to this forum post. The expert reviews the output and (hopefully) diagnoses the problem.

Secondary use cases for rolesdebug.php include
* a user troubleshooting his own problems
* a user troubleshooting another user's problem while logged in as that user

Note that both of these secondary use cases are equivalent, since there is only one actor (the expert), not two. To keep things simple in the remainder of the article, I'll describe the secondary use case, and I'll refer only to YOU. Keeping the primary use case in mind, it should be clear when "you" means roles expert and when it means the roles novice.

==Essential roles and capabilities concepts==

Interpreting the output from rolesdebug.php requires at least a basic understanding of the concepts listed below. If any of these concepts are unfamiliar to you, stop and follow the documentation link.

* [[Assign_roles#Contexts | Context]]
* [[Capabilities | Capability]]
* [[Capabilities | Permission]]
* [[Capabilities | Role]]
* [[Assign_roles | Role assignment]]
* [[Override_permissions | Role override]]
* [[How permissions are calculated]]

==Overview of a script session==

First, you will log in to Moodle and navigate to the context where you're having the problem. Perhaps this is a quiz which Moodle, for some unknown reason, is preventing you from attempting. Then, without logging out of Moodle, point your browser at rolesdebug.php (I find it convenient to open a new browser tab for this). Input the ''context'' you're interested in and (optionally) the name of a ''capability'' to investigate, then press the Go button. The script will return a page with a table presenting a spatial view of the role assignments and overrides that affect you in the specified context. From the table, you will be able to see why Moodle is preventing you from attempting the quiz.

==Using the script==

===STEP1===
This step is done in Moodle (you won't use the script until STEP 2). Login to Moodle and navigate into the context where the problem is occurring. Once you're there, you'll make note of the context id, which is needed in STEP 2. I'll tell you [[#How to determine the context id|how to determine the context id]] later.

Incidentally, even if you know the context id, it is essential that you actually navigate to the context. This is because Moodle loads certain permission data "lazily" -- i.e., only when actually needed. Navigating to the context guarantees that Moodle will have loaded the data. For example, suppose the target context is a certain quiz in some course. You must enter the course and click on the Quiz icon.

However if you are debugging a problem related to a change to a user policy such as Site administration -> Front page -> Front page settings -> Default front page role, you must logout and log back in after making the change.

Do not log out!

===STEP 2===
Open a second browser window. In the window, point your browser at
rolesdebug.php. The script URL will be something like

http://yoursite/moodle/rolesdebug.php

Rolesdebug.php will NOT ask you to login because you are already logged in. The script will ask you for three inputs:

* CAPABILITY. If you're only interested in seeing your role assignments and overrides, you can leave this field empty. If you're interested in analyzing a particular permission, you'll need to enter the capability name. For example, if you're interested in the capability that controls your ability to attempt quizzes, enter [[Capabilities/mod/quiz:attempt | mod/quiz:attempt]].

* CONTEXT TYPE. Choose one of the following from the dropdown menu:
**COURSE
**MODULE
**BLOCK
**COURSECAT
**USER
**SYSTEM

* CONTEXT ID. The context id is a number at the end of the URL of the page you found in STEP 1. See [[#How to determine the context id|How to determine the context id]] below.

Incidentally, MODULE means activity or resource. There is no FRONT PAGE context. If you're interested in the Front page context, choose COURSE and specify a context id of 1.

Here's an example of input:

[[Image:sample_input_quiz_attempt.png|sample input when investigating a quiz attempt]]

===STEP 3===
Press the Go button. Rolesdebug.php will return a page of information. The main item on the page is a table giving a spatial view of all the role assignments and overrides that affect you in the specified context.

==How to read the output==
Let's look at a typical output for the input parameters from the last section.
[[Image:sample_output_quiz_attempt.png|sample output when investigating a quiz attempt]]

The first three lines of output (1) simply echo your input values, and the next two lines (2) remind you of who YOU are, and tell you the actual name of the context you have selected. Check these carefully to make
sure you are who you think you are, and have specified the correct context.

For each of your roles, you will see a line of the form ''alias = role name'' where
* ''role name'' is the actual role name
* ''alias'' is the name used to represent the role in the table

In the example, ''R7 = user'' means the the role user (the shortname of Authorized user) will be represented in the table by the alias R7. Aliases are used because long role names could make the table very wide, forcing you to scroll horizontally. By using aliases, the table will hopefully fit in a window, allowing you to see the entire table in a single a glance.

Next comes the table (4). I'll have a lot more to say about the table below.

If you specified a capability, then you will see the three lines immediately after the table (5).
* The first line gives the calculated permission, which is based on the table. The value can be either A (Allow) or P (Prevent).
* The second line tells you if you are able to "do anything," that is, if you have moodle/site:doanything = Allow (this is typically only true for administrators)
* The third line tells you if you can "do this." If you can do anything, you can obviously do this regardless of the calculated permission.

====How to read the table====

If the target context is N levels deep, the table will have N rows and N columns, one for each context level. The example above has four levels:

System
|
|
Category "A"
|
|
Course "cooking"
|
|
Module "quiz-1"

The column headings give the names of the contexts. These are listed in order of increasing depth: System, A, cooking, quiz-1.

To save space, the table does not have row headings. If it did, they would be the same as the column headings. For example, row 1 would be labeled "System" and row 4 would be labeled "quiz-1".

The first row of the table contains the role assignments made in each context level. In the example, you can see that R7 (Authorized user) is assigned in the System context and R5 (Student) is assigned in the course context. If there are no overrides (as in this example) you will only see entries in row 1.

The letters N and A in parentheses are the values of the capabilities in the role definitions. The possible values are:

N - Not set
A - Allow
P - Prevent
X - Prohibit

"Not set" means that the role doesn't say anything about the capability. In the example, we see that the Student role allows
quiz attempts, while the Authorized user role doesn't have anything
to say about quiz attempts.

If there are role overrides, there will be entries in other rows of the table. Overrides have the same format as the assignments in row 1. An override is shown in the ROW of the context where it is made, and the COLUMN of the assignment that it overrides.

To illustrate, let's override the Student role in the Quiz context, setting mod/quiz:attempt to Prevent, and then rerun rolesdebug.php. Of course before running the script, the student must attempt the quiz. This time, the student should be prevented because of the override. Now we run the script and get the following output:
[[Image:sample_output_quiz_attempt_with_override.png|sample output when investigating a quiz attempt and there is an override]]

Notice the newly added R5(P). This is the override. It is in the fourth row because the override was made in the quiz context, and it is in the course column because the Student role was assigned in the Course context.

The calculated permission is now P, as expected.

====How Moodle calculates the permission====
For a full explanation of how permissions are calculated, see the article [[How permissions are calculated | How permissions are calculated]]. This section merely illustrates the calculation for the examples given in this article.

For the original example (where we only had role assignments in row 1),
Moodle scans the table from right to left.
[[Image:sample_output_quiz_attempt_showing_path.png|how to scan the table when investigating a quiz attempt]]
Since the first permission it hits is an 'A' the calculated permission is 'A'.

When we added the override, Moodle scans the table in a zig-zag fashion, as shown below.
[[Image:sample_output_quiz_attempt_with_override_showing_path.png|how to scan the table when investigating a quiz attempt and there is an override]]
Since the first permission it hits is a 'P' the calculated permission is 'P'.

==How to determine the context id==
Here are rules for determining the context id for each context type.
===COURSE===
For a COURSE context, the context id is the course id. You can get the course id from the URL that appears in the address bar when when you're on the course page. For example when I point my browser at the "Features" course on demo.moodle.org, I see this:

[[Image:URI_of_course_in_address_bar.png|URI of course is shown in the address bar]]

The course id, and therefore the context id for this course is 2.

If Moodle won't let you enter the course for some reason, but you can see a link to the course, let your mouse hover over the link as in the following screenshot. Your browser will show you the address at the bottom of the window.

[[Image:URI_of_course_at_bottom_of_browser_window.png|URI of course is shown at the bottom of the browser window]]

The front page of a Moodle site is also a course, but you can't use either of the above tricks to get the id. ''The front page course id is 1.''

===MODULE (activity or resource)===
For a MODULE context, the context id is the activity or resource id. You can get the id from the URL that appears in the address bar when you're viewing the activity or resource, or from the bottom of the browser window when you let your mouse hover over a link. Here are some examples:

http://demo.moodle.org/mod/choice/view.php?id=25
http://demo.moodle.org/mod/forum/view.php?id=28
http://demo.moodle.org/mod/lesson/view.php?id=38
http://demo.moodle.org/mod/quiz/view.php?id=61
http://demo.moodle.org/mod/resource/view.php?id=10
http://demo.moodle.org/mod/resource/view.php?id=48

The context id's for these modules are 25, 28, 38, 61, 10, and 48.

===BLOCK===
For a BLOCK context, the context id is the "instanceid" of the block. To get the instanceid, turn editing on and let the mouse hover over the "eye" icon in the block header. Then take the instanceid from URL that appears in the at the bottom of the window. For example:

http://demo.moodle.org/course/view.php?id=28&instanceid=19...

The context id for this block is 19. Note that for blocks, only a user who can turn editing on can get the instanceid.

===COURSECAT===
For a COURSECAT context, the context id is the category id. You can get the id from the URL that appears in the address bar when you're on the category page. If the site has only one category (usually called "Miscellaneous") the id is 1. If there is more than one category, the easiest way to get the category id for a specific category is to have a Category list or a Combo list on the front page of the site (or a Courses block) and let your mouse hover over one of the links. For example:

http://mysite/course/category.php?id=3

The context id for this category is 3

===USER===
For a USER context, the context id is the user id. You can get the id from the URL that appears in the address bar when you're on a profile page, or from the bottom of the browser window when you let your mouse hover over a user's name. For example:

http://demo.moodle.org/user/view.php?id=6&course=1

The context id for this user is 6

===SYSTEM===
There is only one SYSTEM context. Its id is 1.

==Rolesdebug says I should be able do this, but Moodle won't let me!==
When this happens it is because Moodle is calculating your permission differently from the way you think it is. Here are three possibilities:
* Moodle may be calculating the permission in a ''different context'' than the one you specified (Moodle calculates some permissions explicitly in System or User contexts).
* If you are assigned any legacy roles (particularly Guest), Moodle may be ignoring the calculated permission. For example, Guest has been edited, allowing it to post to Forums, Rolesdebug will report that you can post, but Moodle will simply ignore the permission. If you ask a developer why, they will tell you "because guests can never post."
* The action you are attempting requires two or more permissions.

When such a disagreement occurs, further research will be needed to debug the problem. Sometimes you can find the answer in documentation. For example, when a permission is calculated in a different context, the documentation usually says so. Other times you will just need to read the code.

[[Category:Contributed code]]

Roles FAQ

2008-05-12T13:09:20Z

Jisner: /* What is my role here? */

{{Roles}}

==What is the definition of a...==

;Role
:An identifier of the user's status in some context, for example Teacher, Student and Forum moderator
;Capability
:A description of a particular Moodle feature, for example [[Capabilities/moodle/blog:create|moodle/blog:create]]
;Permission
:A setting for a capability - inherit, allow, prevent or prohibit
;Context
:A "space" in Moodle, such as courses, activity modules or blocks

==Why isn't my role change taking effect?==

In Moodle 1.7.x and 1.8.x, role assignments and overrides do not take effect immediately. They are delayed until the next time the user logs in. Starting with Moodle 1.9, explicit role assignments and overrides take effect immediately. However role assignments resulting from changes to certain user policies (for example, changing the default front page role) may be delayed until the next login.

If you are testing a new role, [[Manage_roles#Testing_a_new_role | here are some suggestions]].

Also, please check the context in which the role is assigned. Certain capabilities e.g. [[Capabilities/moodle/user:update|moodle/user:update]] may only be applied in the system context, so assigning a role in the course context will result in the role change not taking effect.

==Why are participants being added automatically when a new course is created?==

If a user is assigned a system role or a role in the course category context then the user has this role in ALL courses in that context. Thus users who are students or teachers at the category level appear as course participants in all courses in that category.

Please check ''Administration > Users > Permissions > Assign system roles'' and also the Assign roles link in course categories page and unassign users as necessary.

==Why are all students enrolled in all courses?==

Either
*Users are assigned the role of student in the site/system context rather than the course context (see FAQ above)
Or
*The default role for all users in ''Administration > Users > Permissions > User policies'' is set to Student rather than Authenticated user (Moodle 1.8 onwards).

==Why are there differences in the users listed as course participants and users assigned roles in a course?==

Users assigned roles in a higher context, for example users assigned the role of teacher in a course category context, may appear as course participants. The discussion [http://moodle.org/mod/forum/discuss.php?d=59900 Discrepancies between Assign Roles lists and Participants list] contains a longer explanation.

==How can I prevent administrators being listed as course participants?==

Ensure that administrators are not assigned another role in addition to their admin role.

==Why are hidden assignments still visible?==

Hidden assignments are not hidden from admins or teachers i.e. users with the [[Capabilities/moodle/role:viewhiddenassigns|viewhiddenassigns capability]].

==Where are permissions inherited from?==

Permissions are inherited from a role assigned in a higher-level context which has permissions set to allow for particular capabilities. If permission is "Not set" in any context and not allowed in any higher context (in particular, if you are creating or editing a role at the site level), then a user will have no permission for that capability.

For example, the Student role has permission not set for the change site configuration capability. The permission is never allowed in any context so users assigned the role of Student cannot change the site configuration.

==What is my role here?==

This is a frequently asked question, but an improper one. The correct question is "What are my ''permissions'' here?" In any given context, you often have two or more roles. In addition, one or more role overrides may be in effect. Your permissions in a given context are a result of "adding" the individual permissions from these roles and overrides according to certain rules. As Tim Hunt writes in [http://moodle.org/mod/forum/discuss.php?d=90140 this discussion], the rules "normally do what you expect." However when permissions conflict, the results can be surprising, and it pays to understand [[How permissions are calculated]].

==How do I debug a roles-related problem?==

If you're having a problem that you suspect is related to roles, consider using [[The rolesdebug.php roles debugging script | the rolesdebug.php roles debugging script]]. You can download it from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and plugins database]. The script gives you a spatial view of your role assignments and overrides in a given context, and analyzes your permissions there. To interpret the output requires a basic understanding of roles and capabilities. If you are a complete roles novice, run the script and post the output to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities Forum].

==Are there any differences in Roles in Moodle 1.7 and 1.8?==

In addition to many Roles fixes and refinements (see the list of [http://tracker.moodle.org/secure/IssueNavigator.jspa?mode=hide&requestId=10221 Roles improvements] in the Tracker), in Moodle 1.8 the ''system'' context is separated from the ''front page'' context. Roles may be assigned in the front page context via ''Administration > Front Page > Front Page roles''.

A "Duplicate role" button has been added in Moodle 1.8, which makes creating new roles based on predefined roles much quicker.

==How do I change the name for "teacher" in the course description?==

Either
* Edit the role of Teacher via ''Administration > Users > Permissions > Define roles'' and rename it. The new name will apply site-wide.
Or
* Create a duplicate teacher role with an alternative name and assign users the duplicate teacher role as appropriate in the course context. In ''Administration > Appearance > Course manager'' select the alternative name for teacher that you wish to be displayed in the course description.
Or
* One more way to do it in 1.8 is to create new "dummy" roles (no capabilities) with those names and assign them to teachers along with the real roles. In the course manager settings you can choose which roles display on the front page under each course. (The feature request [http://tracker.moodle.org/browse/MDL-9182 Ability to assign or display custom title for role of person in course] contains this further method.)

{{Moodle 1.9}}From Moodle 1.9 onwards, names for different roles in a course may be changed in the [[Course settings|course settings]].

==How do I enable teachers to set role overrides?==

#Access ''Administration > Users > Permissions > Define roles''.
#Edit the teacher role and change the capability [[Capabilities/moodle/role:override|moodle/role:override]] to allow.
#Click the button "Save changes".
#Click the tab "Allow role overrides" (in ''Administration > Users > Permissions > Define roles'').
#Check the appropriate box to allow a teacher to override the student role.
#Click the button "Save changes".

==How do I enable teachers to assign other teachers in a course?==

This is disabled by default but it can be switched on by modifying the teacher's role. In ''Administration > Users > Permissions > Define roles'' select the "Allow role assignments" tab and tick the checkbox where Teacher and Teacher intersect.

==Why doesn't "Switch role to.." within a course seem to work properly for a course creator?==

This feature is intended for teachers so that they can see how their course appears for students. It doesn't work reliably outside the course.

Further information about this feature can be found in [[Switch roles]] and the paragraph on testing a new role in [[Manage roles]].

==Are there any example roles?==

Yes, as follows:

*[[Inspector role|Inspector]] - for providing external inspectors with permission to view all courses (without being required to enrol)
*[[Parent role|Parent]] - for providing parents/mentors/tutors with permission to view certain information about their children/mentees/tutees
*[[Demo teacher role|Demo teacher]] - for providing a demonstration teacher account with a password which can't be changed
*[[Forum moderator role]] - for providing a user with permission in a particular forum to edit or delete forum posts, split discussions and move discussions to other forums
*[[Keyholder role]] - for setting the person named as holding a course [[Enrolment key|enrolment key]]
*[[Calendar editor role|Calendar editor]] - for providing a user with permission to add site events to the calendar
*[[Blogger role]] - for limiting blogging to specific users only

==Logged-in users can't read the site news. What can I do?==

#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override roles" link
#Click on "Authenticated User"
#Scroll down to '''Forum'''
#Change the capability [[Capabilities/mod/forum:viewdiscussion|mod/forum:viewdiscussion]] to ''allow''
#Click the "Save changes" button at the bottom of the page

==How do I enable logged-in users to participate in front page activities?==

Either:
#Access ''Site Administration > Front Page > Front Page roles''
#Follow the "Override roles" link
#Click on "Authenticated User"
#Change capabilities to ''allow'' for all required activities e.g. record a choice, reply to posts
#Click the "Save changes" button at the bottom of the page

Note that for this to work, you need to make the default role for all users "authenticated user". This is the default for new versions of Moodle. In older versions, the default setting is guest, so if you have recently upgraded, you may have to change this setting. You can change the setting via ''Site Administration > Permissions > User Policies''.

Or:
#Access ''Site Administration > Front Page > Front Page roles''
#Click on Student
#Select all users in the potential users list, and use the left-facing arrow button to add them to the existing users list

{{Moodle 1.9}}Or, in Moodle 1.9 onwards:
#Access ''Site Administration > Front Page > Front Page settings''
#Set the default front page role to student.

[[Category:FAQ]]

[[es:FAQ_roles]]
[[fr:FAQ des rôles]]
[[ja:ロールFAQ]]
[[ru:FAQ по ролям]]
[[de:Rollen FAQ]]

The rolesdebug.php roles debugging script

2008-05-10T22:14:48Z

Jisner: /* Rolesdebug says I should be able do this, but Moodle won't let me! */

{{Roles}}{{Moodle 1.9}}
Rolesdebug.php is a stand-alone script that is extremely useful for debugging problems related to roles and permissions. The output can be interpreted by anyone with a good understanding of Moodle's [[Roles and capabilities]] system. If you're a "roles novice" and you need help with a roles-related problem, ask a roles expert to help you with running the script and interpreting the output. If you don't have access to an expert, post a request for help to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]. After using the script a few times, you'll be an expert too!

You can download rolesdebug.php from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and Plugins database]. To install the script, simply drop it into the Moodle root directory or any directory under the root directory.

Rolesdebug.php requires a login, so only someone with a Moodle user account who is currently logged in can use it. Since it is a php script, you will see the output in your browser. No one else will see it unless they're looking over your shoulder. Furthermore, rolesdebug.php will only give you information about YOUR permissions. You cannot use it to get information about another user's permissions (unless you can login as them).

Rolesdebug.php outputs a table giving a spatial view of the role assignments and overrides that affect you in a specified context. From the table, you will be able to see how Moodle calculates a specified permission. The table format is explained (and several examples are given) in the article [[How permissions are calculated]].

Rolesdebug.php reads permission data from the Moodle database but does not modify the database in any way. In this respect, it is similar to other debug scripts in the standard distribution, like the [[TeX_notation_filter#Debugging_TeX_filter | TeX notation debugger]].

==The use case for rolesdebug.php==

The main use case for rolesdebug.php is a ''roles expert helping a roles novice troubleshoot a roles-related problem''. A ''roles expert'' is anyone with a basic understanding of the [[#Essential roles and capabilities concepts | essential roles concepts]] listed in the next section. A ''roles novice'' is any Moodle user with the ability to follow simple instructions from the expert. While the expert and novice may occasionally share the same physical location and have accounts on the same Moodle site, it is not required. The expert must be able to help the novice without logging in to the novice's site, and by communicating with the novice only by e-mail, messaging, forum posts, etc.. For example, the novice may be a user posting to a moodle.org forum and the expert may be a moodler wanting to be helpful. Even when expert and novice share a physical location and have accounts on the same Moodle site, the expert may not be in a position to give direct help, e.g., by "logging in as" the novice or meeting with the novice. For example, the expert may be a Moodle administrator with an extremely busy schedule.

Here's a typical scenario. Supposed the novice is a teacher who has created a quiz, but is being prevented from previewing the quiz for some unknown reason. The novice reports the problem to moodle.org in a forum post. The expert (a helpful moodler) suspects a roles problem and replies by asking the novice to (1) log in to Moodle, reproduce the problem (2) browse to rolesdebug.php (3) enter two or three parameters as specified by the expert (4) paste the output from rolesdebug.php into a reply to this forum post. The expert reviews the output and (hopefully) diagnoses the problem.

Secondary use cases for rolesdebug.php include
* a user troubleshooting his own problems
* a user troubleshooting another user's problem while logged in as that user

Note that both of these secondary use cases are equivalent, since there is only one actor (the expert), not two. To keep things simple in the remainder of the article, I'll describe the secondary use case, and I'll refer only to YOU. Keeping the primary use case in mind, it should be clear when "you" means roles expert and when it means the roles novice.

==Essential roles and capabilities concepts==

Interpreting the output from rolesdebug.php requires at least a basic understanding of the concepts listed below. If any of these concepts are unfamiliar to you, stop and follow the documentation link.

* [[Assign_roles#Contexts | Context]]
* [[Capabilities | Capability]]
* [[Capabilities | Permission]]
* [[Capabilities | Role]]
* [[Assign_roles | Role assignment]]
* [[Override_permissions | Role override]]
* [[How permissions are calculated]]

==Overview of a script session==

First, you will log in to Moodle and navigate to the context where you're having the problem. Perhaps this is a quiz which Moodle, for some unknown reason, is preventing you from attempting. Then, without logging out of Moodle, point your browser at rolesdebug.php (I find it convenient to open a new browser tab for this). Input the ''context'' you're interested in and (optionally) the name of a ''capability'' to investigate, then press the Go button. The script will return a page with a table presenting a spatial view of the role assignments and overrides that affect you in the specified context. From the table, you will be able to see why Moodle is preventing you from attempting the quiz.

==Using the script==

===STEP1===
This step is done in Moodle (you won't use the script until STEP 2). Login to Moodle and navigate into the context where the problem is occurring. Once you're there, you'll make note of the context id, which is needed in STEP 2. I'll tell you [[#How to determine the context id|how to determine the context id]] later.

Incidentally, even if you know the context id, it is essential that you actually navigate to the context. This is because Moodle loads certain permission data "lazily" -- i.e., only when actually needed. Navigating to the context guarantees that Moodle will have loaded the data. For example, suppose the target context is a certain quiz in some course. You must enter the course and click on the Quiz icon.

However if you are debugging a problem related to a change to a user policy such as Site administration -> Front page -> Front page settings -> Default front page role, you must logout and log back in after making the change.

Do not log out!

===STEP 2===
Open a second browser window. In the window, point your browser at
rolesdebug.php. The script URL will be something like

http://yoursite/moodle/rolesdebug.php

Rolesdebug.php will NOT ask you to login because you are already logged in. The script will ask you for three inputs:

* CAPABILITY. If you're only interested in seeing your role assignments and overrides, you can leave this field empty. If you're interested in analyzing a particular permission, you'll need to enter the capability name. For example, if you're interested in the capability that controls your ability to attempt quizzes, enter [[Capabilities/mod/quiz:attempt | mod/quiz:attempt]].

* CONTEXT TYPE. Choose one of the following from the dropdown menu:
**COURSE
**MODULE
**BLOCK
**COURSECAT
**USER
**SYSTEM

* CONTEXT ID. The context id is a number at the end of the URL of the page you found in STEP 1. See [[#How to determine the context id|How to determine the context id]] below.

Incidentally, MODULE means activity or resource. There is no FRONT PAGE context. If you're interested in the Front page context, choose COURSE and specify a context id of 1.

Here's an example of input:

[[Image:sample_input_quiz_attempt.png|sample input when investigating a quiz attempt]]

===STEP 3===
Press the Go button. Rolesdebug.php will return a page of information. The main item on the page is a table giving a spatial view of all the role assignments and overrides that affect you in the specified context.

==How to read the output==
Let's look at a typical output for the input parameters from the last section.
[[Image:sample_output_quiz_attempt.png|sample output when investigating a quiz attempt]]

The first three lines of output (1) simply echo your input values, and the next two lines (2) remind you of who YOU are, and tell you the actual name of the context you have selected. Check these carefully to make
sure you are who you think you are, and have specified the correct context.

For each of your roles, you will see a line of the form ''alias = role name'' where
* ''role name'' is the actual role name
* ''alias'' is the name used to represent the role in the table

In the example, ''R7 = user'' means the the role user (the shortname of Authorized user) will be represented in the table by the alias R7. Aliases are used because long role names could make the table very wide, forcing you to scroll horizontally. By using aliases, the table will hopefully fit in a window, allowing you to see the entire table in a single a glance.

Next comes the table (4). I'll have a lot more to say about the table below.

If you specified a capability, then you will see the three lines immediately after the table (5).
* The first line gives the calculated permission, which is based on the table. The value can be either A (Allow) or P (Prevent).
* The second line tells you if you are able to "do anything," that is, if you have moodle/site:doanything = Allow (this is typically only true for administrators)
* The third line tells you if you can "do this." If you can do anything, you can obviously do this regardless of the calculated permission.

====How to read the table====

If the target context is N levels deep, the table will have N rows and N columns, one for each context level. The example above has four levels:

System
|
|
Category "A"
|
|
Course "cooking"
|
|
Module "quiz-1"

The column headings give the names of the contexts. These are listed in order of increasing depth: System, A, cooking, quiz-1.

To save space, the table does not have row headings. If it did, they would be the same as the column headings. For example, row 1 would be labeled "System" and row 4 would be labeled "quiz-1".

The first row of the table contains the role assignments made in each context level. In the example, you can see that R7 (Authorized user) is assigned in the System context and R5 (Student) is assigned in the course context. If there are no overrides (as in this example) you will only see entries in row 1.

The letters N and A in parentheses are the values of the capabilities in the role definitions. The possible values are:

N - Not set
A - Allow
P - Prevent
X - Prohibit

"Not set" means that the role doesn't say anything about the capability. In the example, we see that the Student role allows
quiz attempts, while the Authorized user role doesn't have anything
to say about quiz attempts.

If there are role overrides, there will be entries in other rows of the table. Overrides have the same format as the assignments in row 1. An override is shown in the ROW of the context where it is made, and the COLUMN of the assignment that it overrides.

To illustrate, let's override the Student role in the Quiz context, setting mod/quiz:attempt to Prevent, and then rerun rolesdebug.php. Of course before running the script, the student must attempt the quiz. This time, the student should be prevented because of the override. Now we run the script and get the following output:
[[Image:sample_output_quiz_attempt_with_override.png|sample output when investigating a quiz attempt and there is an override]]

Notice the newly added R5(P). This is the override. It is in the fourth row because the override was made in the quiz context, and it is in the course column because the Student role was assigned in the Course context.

The calculated permission is now P, as expected.

====How Moodle calculates the permission====
For a full explanation of how permissions are calculated, see the article [[How permissions are calculated | How permissions are calculated]]. This section merely illustrates the calculation for the examples given in this article.

For the original example (where we only had role assignments in row 1),
Moodle scans the table from right to left.
[[Image:sample_output_quiz_attempt_showing_path.png|how to scan the table when investigating a quiz attempt]]
Since the first permission it hits is an 'A' the calculated permission is 'A'.

When we added the override, Moodle scans the table in a zig-zag fashion, as shown below.
[[Image:sample_output_quiz_attempt_with_override_showing_path.png|how to scan the table when investigating a quiz attempt and there is an override]]
Since the first permission it hits is a 'P' the calculated permission is 'P'.

==How to determine the context id==
Here are rules for determining the context id for each context type.
===COURSE===
For a COURSE context, the context id is the course id. You can get the course id from the URL that appears in the address bar when when you're on the course page. For example when I point my browser at the "Features" course on demo.moodle.org, I see this:

[[Image:URI_of_course_in_address_bar.png|URI of course is shown in the address bar]]

The course id, and therefore the context id for this course is 2.

If Moodle won't let you enter the course for some reason, but you can see a link to the course, let your mouse hover over the link as in the following screenshot. Your browser will show you the address at the bottom of the window.

[[Image:URI_of_course_at_bottom_of_browser_window.png|URI of course is shown at the bottom of the browser window]]

The front page of a Moodle site is also a course, but you can't use either of the above tricks to get the id. ''The front page course id is 1.''

===MODULE (activity or resource)===
For a MODULE context, the context id is the activity or resource id. You can get the id from the URL that appears in the address bar when you're viewing the activity or resource, or from the bottom of the browser window when you let your mouse hover over a link. Here are some examples:

http://demo.moodle.org/mod/choice/view.php?id=25
http://demo.moodle.org/mod/forum/view.php?id=28
http://demo.moodle.org/mod/lesson/view.php?id=38
http://demo.moodle.org/mod/quiz/view.php?id=61
http://demo.moodle.org/mod/resource/view.php?id=10
http://demo.moodle.org/mod/resource/view.php?id=48

The context id's for these modules are 25, 28, 38, 61, 10, and 48.

===BLOCK===
For a BLOCK context, the context id is the "instanceid" of the block. To get the instanceid, turn editing on and let the mouse hover over the "eye" icon in the block header. Then take the instanceid from URL that appears in the at the bottom of the window. For example:

http://demo.moodle.org/course/view.php?id=28&instanceid=19...

The context id for this block is 19. Note that for blocks, only a user who can turn editing on can get the instanceid.

===COURSECAT===
For a COURSECAT context, the context id is the category id. You can get the id from the URL that appears in the address bar when you're on the category page. If the site has only one category (usually called "Miscellaneous") the id is 1. If there is more than one category, the easiest way to get the category id for a specific category is to have a Category list or a Combo list on the front page of the site (or a Courses block) and let your mouse hover over one of the links. For example:

http://mysite/course/category.php?id=3

The context id for this category is 3

===USER===
For a USER context, the context id is the user id. You can get the id from the URL that appears in the address bar when you're on a profile page, or from the bottom of the browser window when you let your mouse hover over a user's name. For example:

http://demo.moodle.org/user/view.php?id=6&course=1

The context id for this user is 6

===SYSTEM===
There is only one SYSTEM context. Its id is 1.

==Rolesdebug says I should be able do this, but Moodle won't let me!==
When this happens it is because Moodle is calculating your permission differently from the way you think it is. Here are three possibilities:
* Moodle may be calculating the permission in a ''different context'' than the one you specified (Moodle calculates some permissions explicitly in System or User contexts).
* If you are assigned any legacy roles (particularly Guest), Moodle may be ignoring the calculated permission. For example, Guest has been edited, allowing it to post to Forums, Rolesdebug will report that you can post, but Moodle will simply ignore the permission. If you ask a developer why, they will tell you "because guests can never post."
* The action you are attempting requires two or more permissions.

When such a disagreement occurs, further research will be needed to debug the problem. Sometimes you can find the answer in documentation. For example, when a permission is calculated in a different context, the documentation usually says so. Other times you will just need to read the code.

[[Category:Contributed code]]

The rolesdebug.php roles debugging script

2008-05-10T22:11:56Z

Jisner: /* Rolesdebug says I can do this, but Moodle says I can't! */

{{Roles}}{{Moodle 1.9}}
Rolesdebug.php is a stand-alone script that is extremely useful for debugging problems related to roles and permissions. The output can be interpreted by anyone with a good understanding of Moodle's [[Roles and capabilities]] system. If you're a "roles novice" and you need help with a roles-related problem, ask a roles expert to help you with running the script and interpreting the output. If you don't have access to an expert, post a request for help to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]. After using the script a few times, you'll be an expert too!

You can download rolesdebug.php from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and Plugins database]. To install the script, simply drop it into the Moodle root directory or any directory under the root directory.

Rolesdebug.php requires a login, so only someone with a Moodle user account who is currently logged in can use it. Since it is a php script, you will see the output in your browser. No one else will see it unless they're looking over your shoulder. Furthermore, rolesdebug.php will only give you information about YOUR permissions. You cannot use it to get information about another user's permissions (unless you can login as them).

Rolesdebug.php outputs a table giving a spatial view of the role assignments and overrides that affect you in a specified context. From the table, you will be able to see how Moodle calculates a specified permission. The table format is explained (and several examples are given) in the article [[How permissions are calculated]].

Rolesdebug.php reads permission data from the Moodle database but does not modify the database in any way. In this respect, it is similar to other debug scripts in the standard distribution, like the [[TeX_notation_filter#Debugging_TeX_filter | TeX notation debugger]].

==The use case for rolesdebug.php==

The main use case for rolesdebug.php is a ''roles expert helping a roles novice troubleshoot a roles-related problem''. A ''roles expert'' is anyone with a basic understanding of the [[#Essential roles and capabilities concepts | essential roles concepts]] listed in the next section. A ''roles novice'' is any Moodle user with the ability to follow simple instructions from the expert. While the expert and novice may occasionally share the same physical location and have accounts on the same Moodle site, it is not required. The expert must be able to help the novice without logging in to the novice's site, and by communicating with the novice only by e-mail, messaging, forum posts, etc.. For example, the novice may be a user posting to a moodle.org forum and the expert may be a moodler wanting to be helpful. Even when expert and novice share a physical location and have accounts on the same Moodle site, the expert may not be in a position to give direct help, e.g., by "logging in as" the novice or meeting with the novice. For example, the expert may be a Moodle administrator with an extremely busy schedule.

Here's a typical scenario. Supposed the novice is a teacher who has created a quiz, but is being prevented from previewing the quiz for some unknown reason. The novice reports the problem to moodle.org in a forum post. The expert (a helpful moodler) suspects a roles problem and replies by asking the novice to (1) log in to Moodle, reproduce the problem (2) browse to rolesdebug.php (3) enter two or three parameters as specified by the expert (4) paste the output from rolesdebug.php into a reply to this forum post. The expert reviews the output and (hopefully) diagnoses the problem.

Secondary use cases for rolesdebug.php include
* a user troubleshooting his own problems
* a user troubleshooting another user's problem while logged in as that user

Note that both of these secondary use cases are equivalent, since there is only one actor (the expert), not two. To keep things simple in the remainder of the article, I'll describe the secondary use case, and I'll refer only to YOU. Keeping the primary use case in mind, it should be clear when "you" means roles expert and when it means the roles novice.

==Essential roles and capabilities concepts==

Interpreting the output from rolesdebug.php requires at least a basic understanding of the concepts listed below. If any of these concepts are unfamiliar to you, stop and follow the documentation link.

* [[Assign_roles#Contexts | Context]]
* [[Capabilities | Capability]]
* [[Capabilities | Permission]]
* [[Capabilities | Role]]
* [[Assign_roles | Role assignment]]
* [[Override_permissions | Role override]]
* [[How permissions are calculated]]

==Overview of a script session==

First, you will log in to Moodle and navigate to the context where you're having the problem. Perhaps this is a quiz which Moodle, for some unknown reason, is preventing you from attempting. Then, without logging out of Moodle, point your browser at rolesdebug.php (I find it convenient to open a new browser tab for this). Input the ''context'' you're interested in and (optionally) the name of a ''capability'' to investigate, then press the Go button. The script will return a page with a table presenting a spatial view of the role assignments and overrides that affect you in the specified context. From the table, you will be able to see why Moodle is preventing you from attempting the quiz.

==Using the script==

===STEP1===
This step is done in Moodle (you won't use the script until STEP 2). Login to Moodle and navigate into the context where the problem is occurring. Once you're there, you'll make note of the context id, which is needed in STEP 2. I'll tell you [[#How to determine the context id|how to determine the context id]] later.

Incidentally, even if you know the context id, it is essential that you actually navigate to the context. This is because Moodle loads certain permission data "lazily" -- i.e., only when actually needed. Navigating to the context guarantees that Moodle will have loaded the data. For example, suppose the target context is a certain quiz in some course. You must enter the course and click on the Quiz icon.

However if you are debugging a problem related to a change to a user policy such as Site administration -> Front page -> Front page settings -> Default front page role, you must logout and log back in after making the change.

Do not log out!

===STEP 2===
Open a second browser window. In the window, point your browser at
rolesdebug.php. The script URL will be something like

http://yoursite/moodle/rolesdebug.php

Rolesdebug.php will NOT ask you to login because you are already logged in. The script will ask you for three inputs:

* CAPABILITY. If you're only interested in seeing your role assignments and overrides, you can leave this field empty. If you're interested in analyzing a particular permission, you'll need to enter the capability name. For example, if you're interested in the capability that controls your ability to attempt quizzes, enter [[Capabilities/mod/quiz:attempt | mod/quiz:attempt]].

* CONTEXT TYPE. Choose one of the following from the dropdown menu:
**COURSE
**MODULE
**BLOCK
**COURSECAT
**USER
**SYSTEM

* CONTEXT ID. The context id is a number at the end of the URL of the page you found in STEP 1. See [[#How to determine the context id|How to determine the context id]] below.

Incidentally, MODULE means activity or resource. There is no FRONT PAGE context. If you're interested in the Front page context, choose COURSE and specify a context id of 1.

Here's an example of input:

[[Image:sample_input_quiz_attempt.png|sample input when investigating a quiz attempt]]

===STEP 3===
Press the Go button. Rolesdebug.php will return a page of information. The main item on the page is a table giving a spatial view of all the role assignments and overrides that affect you in the specified context.

==How to read the output==
Let's look at a typical output for the input parameters from the last section.
[[Image:sample_output_quiz_attempt.png|sample output when investigating a quiz attempt]]

The first three lines of output (1) simply echo your input values, and the next two lines (2) remind you of who YOU are, and tell you the actual name of the context you have selected. Check these carefully to make
sure you are who you think you are, and have specified the correct context.

For each of your roles, you will see a line of the form ''alias = role name'' where
* ''role name'' is the actual role name
* ''alias'' is the name used to represent the role in the table

In the example, ''R7 = user'' means the the role user (the shortname of Authorized user) will be represented in the table by the alias R7. Aliases are used because long role names could make the table very wide, forcing you to scroll horizontally. By using aliases, the table will hopefully fit in a window, allowing you to see the entire table in a single a glance.

Next comes the table (4). I'll have a lot more to say about the table below.

If you specified a capability, then you will see the three lines immediately after the table (5).
* The first line gives the calculated permission, which is based on the table. The value can be either A (Allow) or P (Prevent).
* The second line tells you if you are able to "do anything," that is, if you have moodle/site:doanything = Allow (this is typically only true for administrators)
* The third line tells you if you can "do this." If you can do anything, you can obviously do this regardless of the calculated permission.

====How to read the table====

If the target context is N levels deep, the table will have N rows and N columns, one for each context level. The example above has four levels:

System
|
|
Category "A"
|
|
Course "cooking"
|
|
Module "quiz-1"

The column headings give the names of the contexts. These are listed in order of increasing depth: System, A, cooking, quiz-1.

To save space, the table does not have row headings. If it did, they would be the same as the column headings. For example, row 1 would be labeled "System" and row 4 would be labeled "quiz-1".

The first row of the table contains the role assignments made in each context level. In the example, you can see that R7 (Authorized user) is assigned in the System context and R5 (Student) is assigned in the course context. If there are no overrides (as in this example) you will only see entries in row 1.

The letters N and A in parentheses are the values of the capabilities in the role definitions. The possible values are:

N - Not set
A - Allow
P - Prevent
X - Prohibit

"Not set" means that the role doesn't say anything about the capability. In the example, we see that the Student role allows
quiz attempts, while the Authorized user role doesn't have anything
to say about quiz attempts.

If there are role overrides, there will be entries in other rows of the table. Overrides have the same format as the assignments in row 1. An override is shown in the ROW of the context where it is made, and the COLUMN of the assignment that it overrides.

To illustrate, let's override the Student role in the Quiz context, setting mod/quiz:attempt to Prevent, and then rerun rolesdebug.php. Of course before running the script, the student must attempt the quiz. This time, the student should be prevented because of the override. Now we run the script and get the following output:
[[Image:sample_output_quiz_attempt_with_override.png|sample output when investigating a quiz attempt and there is an override]]

Notice the newly added R5(P). This is the override. It is in the fourth row because the override was made in the quiz context, and it is in the course column because the Student role was assigned in the Course context.

The calculated permission is now P, as expected.

====How Moodle calculates the permission====
For a full explanation of how permissions are calculated, see the article [[How permissions are calculated | How permissions are calculated]]. This section merely illustrates the calculation for the examples given in this article.

For the original example (where we only had role assignments in row 1),
Moodle scans the table from right to left.
[[Image:sample_output_quiz_attempt_showing_path.png|how to scan the table when investigating a quiz attempt]]
Since the first permission it hits is an 'A' the calculated permission is 'A'.

When we added the override, Moodle scans the table in a zig-zag fashion, as shown below.
[[Image:sample_output_quiz_attempt_with_override_showing_path.png|how to scan the table when investigating a quiz attempt and there is an override]]
Since the first permission it hits is a 'P' the calculated permission is 'P'.

==How to determine the context id==
Here are rules for determining the context id for each context type.
===COURSE===
For a COURSE context, the context id is the course id. You can get the course id from the URL that appears in the address bar when when you're on the course page. For example when I point my browser at the "Features" course on demo.moodle.org, I see this:

[[Image:URI_of_course_in_address_bar.png|URI of course is shown in the address bar]]

The course id, and therefore the context id for this course is 2.

If Moodle won't let you enter the course for some reason, but you can see a link to the course, let your mouse hover over the link as in the following screenshot. Your browser will show you the address at the bottom of the window.

[[Image:URI_of_course_at_bottom_of_browser_window.png|URI of course is shown at the bottom of the browser window]]

The front page of a Moodle site is also a course, but you can't use either of the above tricks to get the id. ''The front page course id is 1.''

===MODULE (activity or resource)===
For a MODULE context, the context id is the activity or resource id. You can get the id from the URL that appears in the address bar when you're viewing the activity or resource, or from the bottom of the browser window when you let your mouse hover over a link. Here are some examples:

http://demo.moodle.org/mod/choice/view.php?id=25
http://demo.moodle.org/mod/forum/view.php?id=28
http://demo.moodle.org/mod/lesson/view.php?id=38
http://demo.moodle.org/mod/quiz/view.php?id=61
http://demo.moodle.org/mod/resource/view.php?id=10
http://demo.moodle.org/mod/resource/view.php?id=48

The context id's for these modules are 25, 28, 38, 61, 10, and 48.

===BLOCK===
For a BLOCK context, the context id is the "instanceid" of the block. To get the instanceid, turn editing on and let the mouse hover over the "eye" icon in the block header. Then take the instanceid from URL that appears in the at the bottom of the window. For example:

http://demo.moodle.org/course/view.php?id=28&instanceid=19...

The context id for this block is 19. Note that for blocks, only a user who can turn editing on can get the instanceid.

===COURSECAT===
For a COURSECAT context, the context id is the category id. You can get the id from the URL that appears in the address bar when you're on the category page. If the site has only one category (usually called "Miscellaneous") the id is 1. If there is more than one category, the easiest way to get the category id for a specific category is to have a Category list or a Combo list on the front page of the site (or a Courses block) and let your mouse hover over one of the links. For example:

http://mysite/course/category.php?id=3

The context id for this category is 3

===USER===
For a USER context, the context id is the user id. You can get the id from the URL that appears in the address bar when you're on a profile page, or from the bottom of the browser window when you let your mouse hover over a user's name. For example:

http://demo.moodle.org/user/view.php?id=6&course=1

The context id for this user is 6

===SYSTEM===
There is only one SYSTEM context. Its id is 1.

==Rolesdebug says I should be able do this, but Moodle won't let me!==
When this happens it is because Moodle is calculating your permission differently from the way you think it is. Here are several possibilities to consider.
* Moodle may be calculating the permission in a ''different context'' than the one you specified (Moodle calculates some permissions explicitly in System or User contexts).
* If you are assigned any legacy roles (particularly Guest), Moodle may be ignoring the calculated permission. For example, if you allow Guest it to post to a Forum, Rolesdebug will report that you can post, but Moodle will simply ignore the permission. If you ask a developer why, they will tell you "because guests can never post."
* The action you are attempting requires two or more permissions.

When such a disagreement occurs, further research will be needed to debug the problem. Sometimes you can find the answer in documentation (e.g., when a permission is calculated in a different context, the documentation usually says so), and other times you will need to read the code.

[[Category:Contributed code]]

The rolesdebug.php roles debugging script

2008-05-10T22:11:29Z

Jisner: /* Rolesdebug says I can do this, but Moodle says I can't! */

{{Roles}}{{Moodle 1.9}}
Rolesdebug.php is a stand-alone script that is extremely useful for debugging problems related to roles and permissions. The output can be interpreted by anyone with a good understanding of Moodle's [[Roles and capabilities]] system. If you're a "roles novice" and you need help with a roles-related problem, ask a roles expert to help you with running the script and interpreting the output. If you don't have access to an expert, post a request for help to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]. After using the script a few times, you'll be an expert too!

You can download rolesdebug.php from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and Plugins database]. To install the script, simply drop it into the Moodle root directory or any directory under the root directory.

Rolesdebug.php requires a login, so only someone with a Moodle user account who is currently logged in can use it. Since it is a php script, you will see the output in your browser. No one else will see it unless they're looking over your shoulder. Furthermore, rolesdebug.php will only give you information about YOUR permissions. You cannot use it to get information about another user's permissions (unless you can login as them).

Rolesdebug.php outputs a table giving a spatial view of the role assignments and overrides that affect you in a specified context. From the table, you will be able to see how Moodle calculates a specified permission. The table format is explained (and several examples are given) in the article [[How permissions are calculated]].

Rolesdebug.php reads permission data from the Moodle database but does not modify the database in any way. In this respect, it is similar to other debug scripts in the standard distribution, like the [[TeX_notation_filter#Debugging_TeX_filter | TeX notation debugger]].

==The use case for rolesdebug.php==

The main use case for rolesdebug.php is a ''roles expert helping a roles novice troubleshoot a roles-related problem''. A ''roles expert'' is anyone with a basic understanding of the [[#Essential roles and capabilities concepts | essential roles concepts]] listed in the next section. A ''roles novice'' is any Moodle user with the ability to follow simple instructions from the expert. While the expert and novice may occasionally share the same physical location and have accounts on the same Moodle site, it is not required. The expert must be able to help the novice without logging in to the novice's site, and by communicating with the novice only by e-mail, messaging, forum posts, etc.. For example, the novice may be a user posting to a moodle.org forum and the expert may be a moodler wanting to be helpful. Even when expert and novice share a physical location and have accounts on the same Moodle site, the expert may not be in a position to give direct help, e.g., by "logging in as" the novice or meeting with the novice. For example, the expert may be a Moodle administrator with an extremely busy schedule.

Here's a typical scenario. Supposed the novice is a teacher who has created a quiz, but is being prevented from previewing the quiz for some unknown reason. The novice reports the problem to moodle.org in a forum post. The expert (a helpful moodler) suspects a roles problem and replies by asking the novice to (1) log in to Moodle, reproduce the problem (2) browse to rolesdebug.php (3) enter two or three parameters as specified by the expert (4) paste the output from rolesdebug.php into a reply to this forum post. The expert reviews the output and (hopefully) diagnoses the problem.

Secondary use cases for rolesdebug.php include
* a user troubleshooting his own problems
* a user troubleshooting another user's problem while logged in as that user

Note that both of these secondary use cases are equivalent, since there is only one actor (the expert), not two. To keep things simple in the remainder of the article, I'll describe the secondary use case, and I'll refer only to YOU. Keeping the primary use case in mind, it should be clear when "you" means roles expert and when it means the roles novice.

==Essential roles and capabilities concepts==

Interpreting the output from rolesdebug.php requires at least a basic understanding of the concepts listed below. If any of these concepts are unfamiliar to you, stop and follow the documentation link.

* [[Assign_roles#Contexts | Context]]
* [[Capabilities | Capability]]
* [[Capabilities | Permission]]
* [[Capabilities | Role]]
* [[Assign_roles | Role assignment]]
* [[Override_permissions | Role override]]
* [[How permissions are calculated]]

==Overview of a script session==

First, you will log in to Moodle and navigate to the context where you're having the problem. Perhaps this is a quiz which Moodle, for some unknown reason, is preventing you from attempting. Then, without logging out of Moodle, point your browser at rolesdebug.php (I find it convenient to open a new browser tab for this). Input the ''context'' you're interested in and (optionally) the name of a ''capability'' to investigate, then press the Go button. The script will return a page with a table presenting a spatial view of the role assignments and overrides that affect you in the specified context. From the table, you will be able to see why Moodle is preventing you from attempting the quiz.

==Using the script==

===STEP1===
This step is done in Moodle (you won't use the script until STEP 2). Login to Moodle and navigate into the context where the problem is occurring. Once you're there, you'll make note of the context id, which is needed in STEP 2. I'll tell you [[#How to determine the context id|how to determine the context id]] later.

Incidentally, even if you know the context id, it is essential that you actually navigate to the context. This is because Moodle loads certain permission data "lazily" -- i.e., only when actually needed. Navigating to the context guarantees that Moodle will have loaded the data. For example, suppose the target context is a certain quiz in some course. You must enter the course and click on the Quiz icon.

However if you are debugging a problem related to a change to a user policy such as Site administration -> Front page -> Front page settings -> Default front page role, you must logout and log back in after making the change.

Do not log out!

===STEP 2===
Open a second browser window. In the window, point your browser at
rolesdebug.php. The script URL will be something like

http://yoursite/moodle/rolesdebug.php

Rolesdebug.php will NOT ask you to login because you are already logged in. The script will ask you for three inputs:

* CAPABILITY. If you're only interested in seeing your role assignments and overrides, you can leave this field empty. If you're interested in analyzing a particular permission, you'll need to enter the capability name. For example, if you're interested in the capability that controls your ability to attempt quizzes, enter [[Capabilities/mod/quiz:attempt | mod/quiz:attempt]].

* CONTEXT TYPE. Choose one of the following from the dropdown menu:
**COURSE
**MODULE
**BLOCK
**COURSECAT
**USER
**SYSTEM

* CONTEXT ID. The context id is a number at the end of the URL of the page you found in STEP 1. See [[#How to determine the context id|How to determine the context id]] below.

Incidentally, MODULE means activity or resource. There is no FRONT PAGE context. If you're interested in the Front page context, choose COURSE and specify a context id of 1.

Here's an example of input:

[[Image:sample_input_quiz_attempt.png|sample input when investigating a quiz attempt]]

===STEP 3===
Press the Go button. Rolesdebug.php will return a page of information. The main item on the page is a table giving a spatial view of all the role assignments and overrides that affect you in the specified context.

==How to read the output==
Let's look at a typical output for the input parameters from the last section.
[[Image:sample_output_quiz_attempt.png|sample output when investigating a quiz attempt]]

The first three lines of output (1) simply echo your input values, and the next two lines (2) remind you of who YOU are, and tell you the actual name of the context you have selected. Check these carefully to make
sure you are who you think you are, and have specified the correct context.

For each of your roles, you will see a line of the form ''alias = role name'' where
* ''role name'' is the actual role name
* ''alias'' is the name used to represent the role in the table

In the example, ''R7 = user'' means the the role user (the shortname of Authorized user) will be represented in the table by the alias R7. Aliases are used because long role names could make the table very wide, forcing you to scroll horizontally. By using aliases, the table will hopefully fit in a window, allowing you to see the entire table in a single a glance.

Next comes the table (4). I'll have a lot more to say about the table below.

If you specified a capability, then you will see the three lines immediately after the table (5).
* The first line gives the calculated permission, which is based on the table. The value can be either A (Allow) or P (Prevent).
* The second line tells you if you are able to "do anything," that is, if you have moodle/site:doanything = Allow (this is typically only true for administrators)
* The third line tells you if you can "do this." If you can do anything, you can obviously do this regardless of the calculated permission.

====How to read the table====

If the target context is N levels deep, the table will have N rows and N columns, one for each context level. The example above has four levels:

System
|
|
Category "A"
|
|
Course "cooking"
|
|
Module "quiz-1"

The column headings give the names of the contexts. These are listed in order of increasing depth: System, A, cooking, quiz-1.

To save space, the table does not have row headings. If it did, they would be the same as the column headings. For example, row 1 would be labeled "System" and row 4 would be labeled "quiz-1".

The first row of the table contains the role assignments made in each context level. In the example, you can see that R7 (Authorized user) is assigned in the System context and R5 (Student) is assigned in the course context. If there are no overrides (as in this example) you will only see entries in row 1.

The letters N and A in parentheses are the values of the capabilities in the role definitions. The possible values are:

N - Not set
A - Allow
P - Prevent
X - Prohibit

"Not set" means that the role doesn't say anything about the capability. In the example, we see that the Student role allows
quiz attempts, while the Authorized user role doesn't have anything
to say about quiz attempts.

If there are role overrides, there will be entries in other rows of the table. Overrides have the same format as the assignments in row 1. An override is shown in the ROW of the context where it is made, and the COLUMN of the assignment that it overrides.

To illustrate, let's override the Student role in the Quiz context, setting mod/quiz:attempt to Prevent, and then rerun rolesdebug.php. Of course before running the script, the student must attempt the quiz. This time, the student should be prevented because of the override. Now we run the script and get the following output:
[[Image:sample_output_quiz_attempt_with_override.png|sample output when investigating a quiz attempt and there is an override]]

Notice the newly added R5(P). This is the override. It is in the fourth row because the override was made in the quiz context, and it is in the course column because the Student role was assigned in the Course context.

The calculated permission is now P, as expected.

====How Moodle calculates the permission====
For a full explanation of how permissions are calculated, see the article [[How permissions are calculated | How permissions are calculated]]. This section merely illustrates the calculation for the examples given in this article.

For the original example (where we only had role assignments in row 1),
Moodle scans the table from right to left.
[[Image:sample_output_quiz_attempt_showing_path.png|how to scan the table when investigating a quiz attempt]]
Since the first permission it hits is an 'A' the calculated permission is 'A'.

When we added the override, Moodle scans the table in a zig-zag fashion, as shown below.
[[Image:sample_output_quiz_attempt_with_override_showing_path.png|how to scan the table when investigating a quiz attempt and there is an override]]
Since the first permission it hits is a 'P' the calculated permission is 'P'.

==How to determine the context id==
Here are rules for determining the context id for each context type.
===COURSE===
For a COURSE context, the context id is the course id. You can get the course id from the URL that appears in the address bar when when you're on the course page. For example when I point my browser at the "Features" course on demo.moodle.org, I see this:

[[Image:URI_of_course_in_address_bar.png|URI of course is shown in the address bar]]

The course id, and therefore the context id for this course is 2.

If Moodle won't let you enter the course for some reason, but you can see a link to the course, let your mouse hover over the link as in the following screenshot. Your browser will show you the address at the bottom of the window.

[[Image:URI_of_course_at_bottom_of_browser_window.png|URI of course is shown at the bottom of the browser window]]

The front page of a Moodle site is also a course, but you can't use either of the above tricks to get the id. ''The front page course id is 1.''

===MODULE (activity or resource)===
For a MODULE context, the context id is the activity or resource id. You can get the id from the URL that appears in the address bar when you're viewing the activity or resource, or from the bottom of the browser window when you let your mouse hover over a link. Here are some examples:

http://demo.moodle.org/mod/choice/view.php?id=25
http://demo.moodle.org/mod/forum/view.php?id=28
http://demo.moodle.org/mod/lesson/view.php?id=38
http://demo.moodle.org/mod/quiz/view.php?id=61
http://demo.moodle.org/mod/resource/view.php?id=10
http://demo.moodle.org/mod/resource/view.php?id=48

The context id's for these modules are 25, 28, 38, 61, 10, and 48.

===BLOCK===
For a BLOCK context, the context id is the "instanceid" of the block. To get the instanceid, turn editing on and let the mouse hover over the "eye" icon in the block header. Then take the instanceid from URL that appears in the at the bottom of the window. For example:

http://demo.moodle.org/course/view.php?id=28&instanceid=19...

The context id for this block is 19. Note that for blocks, only a user who can turn editing on can get the instanceid.

===COURSECAT===
For a COURSECAT context, the context id is the category id. You can get the id from the URL that appears in the address bar when you're on the category page. If the site has only one category (usually called "Miscellaneous") the id is 1. If there is more than one category, the easiest way to get the category id for a specific category is to have a Category list or a Combo list on the front page of the site (or a Courses block) and let your mouse hover over one of the links. For example:

http://mysite/course/category.php?id=3

The context id for this category is 3

===USER===
For a USER context, the context id is the user id. You can get the id from the URL that appears in the address bar when you're on a profile page, or from the bottom of the browser window when you let your mouse hover over a user's name. For example:

http://demo.moodle.org/user/view.php?id=6&course=1

The context id for this user is 6

===SYSTEM===
There is only one SYSTEM context. Its id is 1.

==Rolesdebug says I can do this, but Moodle says I can't!==
When this happens it is because Moodle is calculating your permission differently from the way you think it is. Here are several possibilities to consider.
* Moodle may be calculating the permission in a ''different context'' than the one you specified (Moodle calculates some permissions explicitly in System or User contexts).
* If you are assigned any legacy roles (particularly Guest), Moodle may be ignoring the calculated permission. For example, if you allow Guest it to post to a Forum, Rolesdebug will report that you can post, but Moodle will simply ignore the permission. If you ask a developer why, they will tell you "because guests can never post."
* The action you are attempting requires two or more permissions.

When such a disagreement occurs, further research will be needed to debug the problem. Sometimes you can find the answer in documentation (e.g., when a permission is calculated in a different context, the documentation usually says so), and other times you will need to read the code.

[[Category:Contributed code]]

The rolesdebug.php roles debugging script

2008-05-10T22:07:55Z

Jisner:

{{Roles}}{{Moodle 1.9}}
Rolesdebug.php is a stand-alone script that is extremely useful for debugging problems related to roles and permissions. The output can be interpreted by anyone with a good understanding of Moodle's [[Roles and capabilities]] system. If you're a "roles novice" and you need help with a roles-related problem, ask a roles expert to help you with running the script and interpreting the output. If you don't have access to an expert, post a request for help to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]. After using the script a few times, you'll be an expert too!

You can download rolesdebug.php from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and Plugins database]. To install the script, simply drop it into the Moodle root directory or any directory under the root directory.

Rolesdebug.php requires a login, so only someone with a Moodle user account who is currently logged in can use it. Since it is a php script, you will see the output in your browser. No one else will see it unless they're looking over your shoulder. Furthermore, rolesdebug.php will only give you information about YOUR permissions. You cannot use it to get information about another user's permissions (unless you can login as them).

Rolesdebug.php outputs a table giving a spatial view of the role assignments and overrides that affect you in a specified context. From the table, you will be able to see how Moodle calculates a specified permission. The table format is explained (and several examples are given) in the article [[How permissions are calculated]].

Rolesdebug.php reads permission data from the Moodle database but does not modify the database in any way. In this respect, it is similar to other debug scripts in the standard distribution, like the [[TeX_notation_filter#Debugging_TeX_filter | TeX notation debugger]].

==The use case for rolesdebug.php==

The main use case for rolesdebug.php is a ''roles expert helping a roles novice troubleshoot a roles-related problem''. A ''roles expert'' is anyone with a basic understanding of the [[#Essential roles and capabilities concepts | essential roles concepts]] listed in the next section. A ''roles novice'' is any Moodle user with the ability to follow simple instructions from the expert. While the expert and novice may occasionally share the same physical location and have accounts on the same Moodle site, it is not required. The expert must be able to help the novice without logging in to the novice's site, and by communicating with the novice only by e-mail, messaging, forum posts, etc.. For example, the novice may be a user posting to a moodle.org forum and the expert may be a moodler wanting to be helpful. Even when expert and novice share a physical location and have accounts on the same Moodle site, the expert may not be in a position to give direct help, e.g., by "logging in as" the novice or meeting with the novice. For example, the expert may be a Moodle administrator with an extremely busy schedule.

Here's a typical scenario. Supposed the novice is a teacher who has created a quiz, but is being prevented from previewing the quiz for some unknown reason. The novice reports the problem to moodle.org in a forum post. The expert (a helpful moodler) suspects a roles problem and replies by asking the novice to (1) log in to Moodle, reproduce the problem (2) browse to rolesdebug.php (3) enter two or three parameters as specified by the expert (4) paste the output from rolesdebug.php into a reply to this forum post. The expert reviews the output and (hopefully) diagnoses the problem.

Secondary use cases for rolesdebug.php include
* a user troubleshooting his own problems
* a user troubleshooting another user's problem while logged in as that user

Note that both of these secondary use cases are equivalent, since there is only one actor (the expert), not two. To keep things simple in the remainder of the article, I'll describe the secondary use case, and I'll refer only to YOU. Keeping the primary use case in mind, it should be clear when "you" means roles expert and when it means the roles novice.

==Essential roles and capabilities concepts==

Interpreting the output from rolesdebug.php requires at least a basic understanding of the concepts listed below. If any of these concepts are unfamiliar to you, stop and follow the documentation link.

* [[Assign_roles#Contexts | Context]]
* [[Capabilities | Capability]]
* [[Capabilities | Permission]]
* [[Capabilities | Role]]
* [[Assign_roles | Role assignment]]
* [[Override_permissions | Role override]]
* [[How permissions are calculated]]

==Overview of a script session==

First, you will log in to Moodle and navigate to the context where you're having the problem. Perhaps this is a quiz which Moodle, for some unknown reason, is preventing you from attempting. Then, without logging out of Moodle, point your browser at rolesdebug.php (I find it convenient to open a new browser tab for this). Input the ''context'' you're interested in and (optionally) the name of a ''capability'' to investigate, then press the Go button. The script will return a page with a table presenting a spatial view of the role assignments and overrides that affect you in the specified context. From the table, you will be able to see why Moodle is preventing you from attempting the quiz.

==Using the script==

===STEP1===
This step is done in Moodle (you won't use the script until STEP 2). Login to Moodle and navigate into the context where the problem is occurring. Once you're there, you'll make note of the context id, which is needed in STEP 2. I'll tell you [[#How to determine the context id|how to determine the context id]] later.

Incidentally, even if you know the context id, it is essential that you actually navigate to the context. This is because Moodle loads certain permission data "lazily" -- i.e., only when actually needed. Navigating to the context guarantees that Moodle will have loaded the data. For example, suppose the target context is a certain quiz in some course. You must enter the course and click on the Quiz icon.

However if you are debugging a problem related to a change to a user policy such as Site administration -> Front page -> Front page settings -> Default front page role, you must logout and log back in after making the change.

Do not log out!

===STEP 2===
Open a second browser window. In the window, point your browser at
rolesdebug.php. The script URL will be something like

http://yoursite/moodle/rolesdebug.php

Rolesdebug.php will NOT ask you to login because you are already logged in. The script will ask you for three inputs:

* CAPABILITY. If you're only interested in seeing your role assignments and overrides, you can leave this field empty. If you're interested in analyzing a particular permission, you'll need to enter the capability name. For example, if you're interested in the capability that controls your ability to attempt quizzes, enter [[Capabilities/mod/quiz:attempt | mod/quiz:attempt]].

* CONTEXT TYPE. Choose one of the following from the dropdown menu:
**COURSE
**MODULE
**BLOCK
**COURSECAT
**USER
**SYSTEM

* CONTEXT ID. The context id is a number at the end of the URL of the page you found in STEP 1. See [[#How to determine the context id|How to determine the context id]] below.

Incidentally, MODULE means activity or resource. There is no FRONT PAGE context. If you're interested in the Front page context, choose COURSE and specify a context id of 1.

Here's an example of input:

[[Image:sample_input_quiz_attempt.png|sample input when investigating a quiz attempt]]

===STEP 3===
Press the Go button. Rolesdebug.php will return a page of information. The main item on the page is a table giving a spatial view of all the role assignments and overrides that affect you in the specified context.

==How to read the output==
Let's look at a typical output for the input parameters from the last section.
[[Image:sample_output_quiz_attempt.png|sample output when investigating a quiz attempt]]

The first three lines of output (1) simply echo your input values, and the next two lines (2) remind you of who YOU are, and tell you the actual name of the context you have selected. Check these carefully to make
sure you are who you think you are, and have specified the correct context.

For each of your roles, you will see a line of the form ''alias = role name'' where
* ''role name'' is the actual role name
* ''alias'' is the name used to represent the role in the table

In the example, ''R7 = user'' means the the role user (the shortname of Authorized user) will be represented in the table by the alias R7. Aliases are used because long role names could make the table very wide, forcing you to scroll horizontally. By using aliases, the table will hopefully fit in a window, allowing you to see the entire table in a single a glance.

Next comes the table (4). I'll have a lot more to say about the table below.

If you specified a capability, then you will see the three lines immediately after the table (5).
* The first line gives the calculated permission, which is based on the table. The value can be either A (Allow) or P (Prevent).
* The second line tells you if you are able to "do anything," that is, if you have moodle/site:doanything = Allow (this is typically only true for administrators)
* The third line tells you if you can "do this." If you can do anything, you can obviously do this regardless of the calculated permission.

====How to read the table====

If the target context is N levels deep, the table will have N rows and N columns, one for each context level. The example above has four levels:

System
|
|
Category "A"
|
|
Course "cooking"
|
|
Module "quiz-1"

The column headings give the names of the contexts. These are listed in order of increasing depth: System, A, cooking, quiz-1.

To save space, the table does not have row headings. If it did, they would be the same as the column headings. For example, row 1 would be labeled "System" and row 4 would be labeled "quiz-1".

The first row of the table contains the role assignments made in each context level. In the example, you can see that R7 (Authorized user) is assigned in the System context and R5 (Student) is assigned in the course context. If there are no overrides (as in this example) you will only see entries in row 1.

The letters N and A in parentheses are the values of the capabilities in the role definitions. The possible values are:

N - Not set
A - Allow
P - Prevent
X - Prohibit

"Not set" means that the role doesn't say anything about the capability. In the example, we see that the Student role allows
quiz attempts, while the Authorized user role doesn't have anything
to say about quiz attempts.

If there are role overrides, there will be entries in other rows of the table. Overrides have the same format as the assignments in row 1. An override is shown in the ROW of the context where it is made, and the COLUMN of the assignment that it overrides.

To illustrate, let's override the Student role in the Quiz context, setting mod/quiz:attempt to Prevent, and then rerun rolesdebug.php. Of course before running the script, the student must attempt the quiz. This time, the student should be prevented because of the override. Now we run the script and get the following output:
[[Image:sample_output_quiz_attempt_with_override.png|sample output when investigating a quiz attempt and there is an override]]

Notice the newly added R5(P). This is the override. It is in the fourth row because the override was made in the quiz context, and it is in the course column because the Student role was assigned in the Course context.

The calculated permission is now P, as expected.

====How Moodle calculates the permission====
For a full explanation of how permissions are calculated, see the article [[How permissions are calculated | How permissions are calculated]]. This section merely illustrates the calculation for the examples given in this article.

For the original example (where we only had role assignments in row 1),
Moodle scans the table from right to left.
[[Image:sample_output_quiz_attempt_showing_path.png|how to scan the table when investigating a quiz attempt]]
Since the first permission it hits is an 'A' the calculated permission is 'A'.

When we added the override, Moodle scans the table in a zig-zag fashion, as shown below.
[[Image:sample_output_quiz_attempt_with_override_showing_path.png|how to scan the table when investigating a quiz attempt and there is an override]]
Since the first permission it hits is a 'P' the calculated permission is 'P'.

==How to determine the context id==
Here are rules for determining the context id for each context type.
===COURSE===
For a COURSE context, the context id is the course id. You can get the course id from the URL that appears in the address bar when when you're on the course page. For example when I point my browser at the "Features" course on demo.moodle.org, I see this:

[[Image:URI_of_course_in_address_bar.png|URI of course is shown in the address bar]]

The course id, and therefore the context id for this course is 2.

If Moodle won't let you enter the course for some reason, but you can see a link to the course, let your mouse hover over the link as in the following screenshot. Your browser will show you the address at the bottom of the window.

[[Image:URI_of_course_at_bottom_of_browser_window.png|URI of course is shown at the bottom of the browser window]]

The front page of a Moodle site is also a course, but you can't use either of the above tricks to get the id. ''The front page course id is 1.''

===MODULE (activity or resource)===
For a MODULE context, the context id is the activity or resource id. You can get the id from the URL that appears in the address bar when you're viewing the activity or resource, or from the bottom of the browser window when you let your mouse hover over a link. Here are some examples:

http://demo.moodle.org/mod/choice/view.php?id=25
http://demo.moodle.org/mod/forum/view.php?id=28
http://demo.moodle.org/mod/lesson/view.php?id=38
http://demo.moodle.org/mod/quiz/view.php?id=61
http://demo.moodle.org/mod/resource/view.php?id=10
http://demo.moodle.org/mod/resource/view.php?id=48

The context id's for these modules are 25, 28, 38, 61, 10, and 48.

===BLOCK===
For a BLOCK context, the context id is the "instanceid" of the block. To get the instanceid, turn editing on and let the mouse hover over the "eye" icon in the block header. Then take the instanceid from URL that appears in the at the bottom of the window. For example:

http://demo.moodle.org/course/view.php?id=28&instanceid=19...

The context id for this block is 19. Note that for blocks, only a user who can turn editing on can get the instanceid.

===COURSECAT===
For a COURSECAT context, the context id is the category id. You can get the id from the URL that appears in the address bar when you're on the category page. If the site has only one category (usually called "Miscellaneous") the id is 1. If there is more than one category, the easiest way to get the category id for a specific category is to have a Category list or a Combo list on the front page of the site (or a Courses block) and let your mouse hover over one of the links. For example:

http://mysite/course/category.php?id=3

The context id for this category is 3

===USER===
For a USER context, the context id is the user id. You can get the id from the URL that appears in the address bar when you're on a profile page, or from the bottom of the browser window when you let your mouse hover over a user's name. For example:

http://demo.moodle.org/user/view.php?id=6&course=1

The context id for this user is 6

===SYSTEM===
There is only one SYSTEM context. Its id is 1.

==Rolesdebug says I can do this, but Moodle says I can't!==
When this happens it is because Moodle is calculating your permission differently from the way you think it is. Here are several possibilities to consider.
* Moodle may be calculating the permission in a ''different context'' than the one you specified. Moodle tests some Systems explicitly in System or User contexts.
* If you are assigned any legacy roles (particularly Guest), Moodle may be ignoring the calculated permission in favor of preserving legacy behavior. For example, if you allow Guest it to post to a Forum, Rolesdebug will report that you can post, but Moodle will simply ignore the permission.
* The action you are attempting requires two or more permissions.

When there is a disagreement, further research will be needed to debug the problem. Sometimes you can find the answer in documentation (e.g., when a permission is calculated in a different context, the documentation usually says so), and other times you will need to read the code.

[[Category:Contributed code]]

How permissions are calculated

2008-05-10T21:48:10Z

Jisner: /* The calculation */

{{Roles}}
One of the most frequently asked question is: ''What are my permissions in this context?'' This article will document the function that Moodle uses to answer this question. The article is written for non-programmers as well as programmers, since it describes ''what'' the function does, not ''how''. The ''how'' is complicated. The ''what'' turns out to be relatively simple! If you are a programmer and you insist on reading the code, look for ''has_capability()'' in ''lib/accesslib.php''.

Given a user, a capability, and a context, ''has_capability()'' returns ''true'' if the user is allowed to perform the action controlled by the capability in the given context, and ''false'' otherwise. In calculating the permission, the function considers all of the relevant permission data, which include role definitions, assignments, and overrides.

Moodle never calculates a user's complete set of permissions. To do so would be very costly and also wasteful, since most permissions are never tested. Instead, Moodle calculates permissions only as needed. It does not store the permissions that it calculates, but recalculates them every time it needs to test them. This is why role assignments and overrides no longer have delayed effects, as they did in Moodle 1.7 and 1.8.

Incidentally, you can generate permission tables like the ones in this article using [[The rolesdebug.php roles debugging script]].

==The calculation==

When a user attempts an action that is controlled by a capability, Moodle calls has_capability to see if the action should be permitted. The function is called as follows:

has_capability(CAP,CONTEXT,USER);

where
*CAP is the capability that controls the action (e.g., mod/quiz:attempt)
*CONTEXT is the context in which the capability is being tested
*USER is the user attempting the action

The function returns a true/false result

* ''true'' means the user should be allowed to perform the action
* ''false'' means the user should be prevented from perfoming the action

===Data used by the function===

Suppose USER is about to attempt a quiz (''CAP = mod/quiz:attempt'') in a Module context nested four levels deep within System.

System
|
Category A
|
Subcategory B
|
Course
|
Quiz <--- the user is here

The quiz module will call ''has_capability()'' to see if the user should be allowed to perform this action.

''has_capability()'' considers the following permission data:

* ''Role definitions'' (these are in the System context)
* ''Role assignments'' which may occur in any of the five contexts
* ''Role overrides'' which may occur in any of the contexts except System (there is no concept of override in System).

''has_capability()'' ignores capabilities other than CAP. This simplification lets us view each role or override as if it contains a ''single permission'' having one of the following values

N - Not set
A - Allow
P - Prevent
X - Prohibit

We use the following notation: for a role ''R1'' with permission ''P'', we write ''R1(P)''.

===An example===

In the quiz example, suppose that the user has four roles (''R1'', ''R2'', ''R3'', and ''R4'') and each of the roles has been assigned and overridden as follows:

0 System <---- define R1(A), R2(N), R3(N), R4(P)
| assign R1
|
1 Category A <-------------- overide R1(N) and R4(N)
|
|
2 Subcategory B <---- assign R2 and R3
|
|
3 Course <-------------- override R2(X) and R3(A)
|
|
4 Quiz <---- assign R4 and R1

Note that ''R1'' has been assigned in two different contexts. This is an unusual practice (it is probably someone's error), but since it is legal, we have to consider the possibility that it can happen. In fact this entire example has been contrived to explore the edge cases of the algorithm. In practice, the calculation of permissions is trivial and the function calculates the result you would expect based on common sense and simple mental analysis (for further discussion of this, see [[#A note about the algorithm|A note about the algorithm]] near the end of this article.

===Representing the data in tabular form===

We will set up a table to hold the permission data. The table has
*a column for each context, ordered from highest level (System) to lowest (the context where we want to compute the permission).
*a row for each context, also listed from highest to lowest.

[[Image:Calculation-3A.png|Empty table]]

The role definitions go in the first row. Put each definition in the column(s) coresponding to the context(s) in which the role is assigned:

[[Image:Calculation-5A.png|Table with assignments added]]

The overrides go in the remaining rows. Each override goes
*in the same column as the role being overridden
*in the row corresponding the context in which the override is made.

To illustrate, let's add just one of the overrides:

[[Image:Calculation-6A.png|Table with just one override]]

R2(X) represents the override to role R2 made in the course context. Let's add the rest of the overrides:

[[Image:Calculation-7A.png|Table with remaining overrides shown]]

The table is now fully populated, and we are ready to calculate the permission.

===The algorithm===

The algorithm follows a path through the table indicated by nodes and arrows in the diagram below and stops as soon as it has a conclusive result.

[[Image:Algorithm_path_through_permission_table_A.png|Algorithm path through permissions data]]

# If there is an X anywhere in the table, STOP. The calculated permission is ''X''
# Go to the START node
# If there is no next node, STOP. The calculated permission is ''P''
# Otherwise, follow the arrow to the next node
#Add the permissions in the node using the numerical equivalents: N = 0, A = +1, P = -1
#* If the sum is positive, STOP. The calculated permission is ''A''
#* If the sum is negative, STOP. The calculated permission is ''P''
#* If the sum is zero, GO TO step 3

Notice that the algorithm stops when either (1) a conclusive result is obtained, or (2) the algorithm reaches the last node without a conclusive result.

===Applying the algorithm to our example===

If we execute the algorithm with the quiz data, we stop at step 1 with a calculated permission of X. That's not very interesting, so let's change the X to a P and see what happens:

[[Image:Calculation-8A.png|Change X to P in permission table]]

Run the algorithm:

*There is No X in the table
*Go to the START node
*Go to the next node
*N + N = 0
*the sum is zero; go to the next node
*A + P = 0
*the sum is zero; go to the next node
*P + A = 0
*the sum is zero; go to the next node
*A + P = 0
*the sum is zero; go to the next node
*N = 0
*the sum is zero; go to the next node
*A = +1
*the sum is positive; STOP. The calculated permission is ''A''

If the calculated permission is ''A'', ''has_capability()'' returns ''true'', and the user is allowed to perform the action.

Had the calculated permission been ''P'' or ''X'', ''has_capability()'' would not immediately return ''false''. Rather, it would test if the user has ''moodle/site:doanything = Allow'' (since this permission trumps all others). The function does this by calling itself:

final result = has_capability(moodle/site:doanything,CONTEXT, USER);

==A note about the algorithm==

Earlier, we said that the algorithm "calculates the result you would expect." But what do we expect? Intuition tells us that permissions closer to the user should carry more weight than more distant permissions. That's why we set up the table the way we did and why the algorithm walks the table in the order that it does. The last column of the table represents the role assignment(s) closest to the user. The second-to-last column represents the role assignent(s) that are next in terms of distance from the user, and so-on. That's why the algorithm considers the columns from right-to-left. Within a column, the algorithm searches upward in order to give higher weight to overrides that are closer to the user. Once again, this matches our intuition about overrides. If there are no overrides in a column (or the overrides are all Not set), the permission in the role definition is used.

==Getting the result you expect==

The calculation is more likely to give "the result you would expect" if you keep your permissions as simple as possible. Therefore, we recommend the following 'rules' for defining and overriding roles. If you understand the description of the calculation above, you should understand why they make sense.

===When defining roles===

... use Allow (A) for things you want the role to be able to do, and use Not set (N) for things you don't care about (which should include most things).

===When overriding permissions===

... leave the permission for every capability as Inherit (N) apart from the few you want to change. For those, use Allow (A) for things you want to allow, and Prevent (P) for things you want to prevent.

===Only use prohibit in special roles===

Prohibit exists to cover extreme scenarios such as the following: Suppose you have a naughty student who is posting inappropriate content in your Moodle site. You need to be able to remove their ability to contribute to public discussions until they have promised not to do it again, but during that time, you cannot completely block them from the resources, quizzes, etc. because they must keep up with their studying. Therefore, you need a way to block their access to specific capabilities e.g. mod/forum:replypost in a way that cannot be overridden. You can do this by creating a special 'Naughty student' role defined with the required permission(s) set to prohibit. Then when you are having problems with a user, you can temporarily assign them this role, either at site level or at course level.

==A practical example==

Suppose that a user, who is assigned the role of Course creator in category B, creates a course (becoming Teacher in the course) and then creates a Lesson within the course. The user is about to edit the lesson (editing lessons is controlled by capability ''mod/lesson:edit''). Here is the permission data:

0 System <---- define Auth user(N), Creator(N), Teacher(A)
| assign Auth user
|
1 Category A
|
|
2 Subcategory B <---- assign Creator
|
|
3 Course <---- assign Teacher
|
|
4 Lesson <---- user attempts to edit lesson

We set up the table and populate it with permission data.

[[Image:Calculation-10A.png|A practical example]]

Since there are no overrides, the table only has data in the first row. The algorithm quickly calculates a permission of ''A'' and returns true. The user is allowed to edit the Lesson!

Now suppose Teacher is overridden in the Lesson context with ''mod/lesson:edit = P''. Then the table changes

[[Image:Calculation-11A.png|A practical example with first override]]

and clearly the user is no longer allowed to edit the Lesson.

But suppose the administrator (or whoever is making the overrides) decided instead to override the ''Creator role'', setting ''mod/lesson:edit = Prevent'' in the Categoy B context:

[[Image:Calculation-12A.png|A practical example with second override]]

Much to everyone's surprise, the user is still allowed to edit the Lesson! If you understood this article, you shouldn't be surprised, and you should be able to explain what happened.

==See also==

*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=90140 Logged in: what role am I?] and [http://moodle.org/mod/forum/discuss.php?d=66782 What happens if a user has multiple roles in a course?] forum discussions.

There is a script that you can use to create tables like the ones in this article. It is very useful for debugging roles-related problems. See [[The rolesdebug.php roles debugging script]].

[[Category:Roles]]

[[fr:Comment les permissions sont calculées ?]]

How permissions are calculated

2008-05-10T21:46:45Z

Jisner: /* The calculation */

{{Roles}}
One of the most frequently asked question is: ''What are my permissions in this context?'' This article will document the function that Moodle uses to answer this question. The article is written for non-programmers as well as programmers, since it describes ''what'' the function does, not ''how''. The ''how'' is complicated. The ''what'' turns out to be relatively simple! If you are a programmer and you insist on reading the code, look for ''has_capability()'' in ''lib/accesslib.php''.

Given a user, a capability, and a context, ''has_capability()'' returns ''true'' if the user is allowed to perform the action controlled by the capability in the given context, and ''false'' otherwise. In calculating the permission, the function considers all of the relevant permission data, which include role definitions, assignments, and overrides.

Moodle never calculates a user's complete set of permissions. To do so would be very costly and also wasteful, since most permissions are never tested. Instead, Moodle calculates permissions only as needed. It does not store the permissions that it calculates, but recalculates them every time it needs to test them. This is why role assignments and overrides no longer have delayed effects, as they did in Moodle 1.7 and 1.8.

Incidentally, you can generate permission tables like the ones in this article using [[The rolesdebug.php roles debugging script]].

==The calculation==

When a user attempts an action that is controlled by a capability, Moodle calls has_capability to see if you have permission. The function is called as follows:

has_capability(CAP,CONTEXT,USER);

where
*CAP is the capability that controls the action (e.g., mod/quiz:attempt)
*CONTEXT is the context in which the capability is being tested
*USER is the user attempting the action

The function returns a true/false result

* ''true'' means the user should be allowed to perform the action
* ''false'' means the user should be prevented from perfoming the action

===Data used by the function===

Suppose USER is about to attempt a quiz (''CAP = mod/quiz:attempt'') in a Module context nested four levels deep within System.

System
|
Category A
|
Subcategory B
|
Course
|
Quiz <--- the user is here

The quiz module will call ''has_capability()'' to see if the user should be allowed to perform this action.

''has_capability()'' considers the following permission data:

* ''Role definitions'' (these are in the System context)
* ''Role assignments'' which may occur in any of the five contexts
* ''Role overrides'' which may occur in any of the contexts except System (there is no concept of override in System).

''has_capability()'' ignores capabilities other than CAP. This simplification lets us view each role or override as if it contains a ''single permission'' having one of the following values

N - Not set
A - Allow
P - Prevent
X - Prohibit

We use the following notation: for a role ''R1'' with permission ''P'', we write ''R1(P)''.

===An example===

In the quiz example, suppose that the user has four roles (''R1'', ''R2'', ''R3'', and ''R4'') and each of the roles has been assigned and overridden as follows:

0 System <---- define R1(A), R2(N), R3(N), R4(P)
| assign R1
|
1 Category A <-------------- overide R1(N) and R4(N)
|
|
2 Subcategory B <---- assign R2 and R3
|
|
3 Course <-------------- override R2(X) and R3(A)
|
|
4 Quiz <---- assign R4 and R1

Note that ''R1'' has been assigned in two different contexts. This is an unusual practice (it is probably someone's error), but since it is legal, we have to consider the possibility that it can happen. In fact this entire example has been contrived to explore the edge cases of the algorithm. In practice, the calculation of permissions is trivial and the function calculates the result you would expect based on common sense and simple mental analysis (for further discussion of this, see [[#A note about the algorithm|A note about the algorithm]] near the end of this article.

===Representing the data in tabular form===

We will set up a table to hold the permission data. The table has
*a column for each context, ordered from highest level (System) to lowest (the context where we want to compute the permission).
*a row for each context, also listed from highest to lowest.

[[Image:Calculation-3A.png|Empty table]]

The role definitions go in the first row. Put each definition in the column(s) coresponding to the context(s) in which the role is assigned:

[[Image:Calculation-5A.png|Table with assignments added]]

The overrides go in the remaining rows. Each override goes
*in the same column as the role being overridden
*in the row corresponding the context in which the override is made.

To illustrate, let's add just one of the overrides:

[[Image:Calculation-6A.png|Table with just one override]]

R2(X) represents the override to role R2 made in the course context. Let's add the rest of the overrides:

[[Image:Calculation-7A.png|Table with remaining overrides shown]]

The table is now fully populated, and we are ready to calculate the permission.

===The algorithm===

The algorithm follows a path through the table indicated by nodes and arrows in the diagram below and stops as soon as it has a conclusive result.

[[Image:Algorithm_path_through_permission_table_A.png|Algorithm path through permissions data]]

# If there is an X anywhere in the table, STOP. The calculated permission is ''X''
# Go to the START node
# If there is no next node, STOP. The calculated permission is ''P''
# Otherwise, follow the arrow to the next node
#Add the permissions in the node using the numerical equivalents: N = 0, A = +1, P = -1
#* If the sum is positive, STOP. The calculated permission is ''A''
#* If the sum is negative, STOP. The calculated permission is ''P''
#* If the sum is zero, GO TO step 3

Notice that the algorithm stops when either (1) a conclusive result is obtained, or (2) the algorithm reaches the last node without a conclusive result.

===Applying the algorithm to our example===

If we execute the algorithm with the quiz data, we stop at step 1 with a calculated permission of X. That's not very interesting, so let's change the X to a P and see what happens:

[[Image:Calculation-8A.png|Change X to P in permission table]]

Run the algorithm:

*There is No X in the table
*Go to the START node
*Go to the next node
*N + N = 0
*the sum is zero; go to the next node
*A + P = 0
*the sum is zero; go to the next node
*P + A = 0
*the sum is zero; go to the next node
*A + P = 0
*the sum is zero; go to the next node
*N = 0
*the sum is zero; go to the next node
*A = +1
*the sum is positive; STOP. The calculated permission is ''A''

If the calculated permission is ''A'', ''has_capability()'' returns ''true'', and the user is allowed to perform the action.

Had the calculated permission been ''P'' or ''X'', ''has_capability()'' would not immediately return ''false''. Rather, it would test if the user has ''moodle/site:doanything = Allow'' (since this permission trumps all others). The function does this by calling itself:

final result = has_capability(moodle/site:doanything,CONTEXT, USER);

==A note about the algorithm==

Earlier, we said that the algorithm "calculates the result you would expect." But what do we expect? Intuition tells us that permissions closer to the user should carry more weight than more distant permissions. That's why we set up the table the way we did and why the algorithm walks the table in the order that it does. The last column of the table represents the role assignment(s) closest to the user. The second-to-last column represents the role assignent(s) that are next in terms of distance from the user, and so-on. That's why the algorithm considers the columns from right-to-left. Within a column, the algorithm searches upward in order to give higher weight to overrides that are closer to the user. Once again, this matches our intuition about overrides. If there are no overrides in a column (or the overrides are all Not set), the permission in the role definition is used.

==Getting the result you expect==

The calculation is more likely to give "the result you would expect" if you keep your permissions as simple as possible. Therefore, we recommend the following 'rules' for defining and overriding roles. If you understand the description of the calculation above, you should understand why they make sense.

===When defining roles===

... use Allow (A) for things you want the role to be able to do, and use Not set (N) for things you don't care about (which should include most things).

===When overriding permissions===

... leave the permission for every capability as Inherit (N) apart from the few you want to change. For those, use Allow (A) for things you want to allow, and Prevent (P) for things you want to prevent.

===Only use prohibit in special roles===

Prohibit exists to cover extreme scenarios such as the following: Suppose you have a naughty student who is posting inappropriate content in your Moodle site. You need to be able to remove their ability to contribute to public discussions until they have promised not to do it again, but during that time, you cannot completely block them from the resources, quizzes, etc. because they must keep up with their studying. Therefore, you need a way to block their access to specific capabilities e.g. mod/forum:replypost in a way that cannot be overridden. You can do this by creating a special 'Naughty student' role defined with the required permission(s) set to prohibit. Then when you are having problems with a user, you can temporarily assign them this role, either at site level or at course level.

==A practical example==

Suppose that a user, who is assigned the role of Course creator in category B, creates a course (becoming Teacher in the course) and then creates a Lesson within the course. The user is about to edit the lesson (editing lessons is controlled by capability ''mod/lesson:edit''). Here is the permission data:

0 System <---- define Auth user(N), Creator(N), Teacher(A)
| assign Auth user
|
1 Category A
|
|
2 Subcategory B <---- assign Creator
|
|
3 Course <---- assign Teacher
|
|
4 Lesson <---- user attempts to edit lesson

We set up the table and populate it with permission data.

[[Image:Calculation-10A.png|A practical example]]

Since there are no overrides, the table only has data in the first row. The algorithm quickly calculates a permission of ''A'' and returns true. The user is allowed to edit the Lesson!

Now suppose Teacher is overridden in the Lesson context with ''mod/lesson:edit = P''. Then the table changes

[[Image:Calculation-11A.png|A practical example with first override]]

and clearly the user is no longer allowed to edit the Lesson.

But suppose the administrator (or whoever is making the overrides) decided instead to override the ''Creator role'', setting ''mod/lesson:edit = Prevent'' in the Categoy B context:

[[Image:Calculation-12A.png|A practical example with second override]]

Much to everyone's surprise, the user is still allowed to edit the Lesson! If you understood this article, you shouldn't be surprised, and you should be able to explain what happened.

==See also==

*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=90140 Logged in: what role am I?] and [http://moodle.org/mod/forum/discuss.php?d=66782 What happens if a user has multiple roles in a course?] forum discussions.

There is a script that you can use to create tables like the ones in this article. It is very useful for debugging roles-related problems. See [[The rolesdebug.php roles debugging script]].

[[Category:Roles]]

[[fr:Comment les permissions sont calculées ?]]

How permissions are calculated

2008-05-10T21:35:19Z

Jisner:

{{Roles}}
One of the most frequently asked question is: ''What are my permissions in this context?'' This article will document the function that Moodle uses to answer this question. The article is written for non-programmers as well as programmers, since it describes ''what'' the function does, not ''how''. The ''how'' is complicated. The ''what'' turns out to be relatively simple! If you are a programmer and you insist on reading the code, look for ''has_capability()'' in ''lib/accesslib.php''.

Given a user, a capability, and a context, ''has_capability()'' returns ''true'' if the user is allowed to perform the action controlled by the capability in the given context, and ''false'' otherwise. In calculating the permission, the function considers all of the relevant permission data, which include role definitions, assignments, and overrides.

Moodle never calculates a user's complete set of permissions. To do so would be very costly and also wasteful, since most permissions are never tested. Instead, Moodle calculates permissions only as needed. It does not store the permissions that it calculates, but recalculates them every time it needs to test them. This is why role assignments and overrides no longer have delayed effects, as they did in Moodle 1.7 and 1.8.

Incidentally, you can generate permission tables like the ones in this article using [[The rolesdebug.php roles debugging script]].

==The calculation==

The function is called as follows:

has_capability(CAP,CONTEXT,USER);

where
*CAP is the capability being tested (e.g., mod/quiz:attempt)
*CONTEXT can be System context or some context nested arbitrarily deeply within System. Internally, the function uses Unix-style paths to represent contexts (e.g., /1/3/4/150), but such details do not concern us here
*USER is the user.

The function returns a true/false result

* ''true'' means the user should be allowed to perform the action
* ''false'' means the user should be prevented from perfoming the action

===Data used by the function===

Suppose USER is about to attempt a quiz (''CAP = mod/quiz:attempt'') in a Module context nested four levels deep within System.

System
|
Category A
|
Subcategory B
|
Course
|
Quiz <--- the user is here

The quiz module will call ''has_capability()'' to see if the user should be allowed to perform this action.

The function considers the following permissions data:

* ''Role definitions'' (these are in the System context)
* ''Role assignments'' which have been made in any of the five contexts
* ''Role overrides'' which may occur in any of the contexts except System (there is no concept of override in System).

Note that there may be multiple assignments and/or overrides in any single context.

Whether or not the user can attempt the quiz is a function of the permissions data, as well as the location of the data in the context chain.

''has_capability()'' considers all roles and overrides that impact USER in CONTEXT, but it ignores capabilities other than CAP. This simplification lets us view each role or override as a ''single permission'' having one of the following values

N - Not set
A - Allow
P - Prevent
X - Prohibit

We use the following notation: for a role ''R1'' with permission ''P'', we write ''R1(P)''.

===An example===

In the quiz example, suppose that the user has four roles (''R1'', ''R2'', ''R3'', and ''R4'') and each of the roles has been assigned and overridden as follows:

0 System <---- define R1(A), R2(N), R3(N), R4(P)
| assign R1
|
1 Category A <-------------- overide R1(N) and R4(N)
|
|
2 Subcategory B <---- assign R2 and R3
|
|
3 Course <-------------- override R2(X) and R3(A)
|
|
4 Quiz <---- assign R4 and R1

Note that ''R1'' has been assigned in two different contexts. This is an unusual practice (it is probably someone's error), but since it is legal, we have to consider the possibility that it can happen. In fact this entire example has been contrived to explore the edge cases of the algorithm. In practice, the calculation of permissions is trivial and the function calculates the result you would expect based on common sense and simple mental analysis (for further discussion of this, see [[#A note about the algorithm|A note about the algorithm]] near the end of this article.

===Representing the data in tabular form===

We will set up a table to hold the permission data. The table has
*a column for each context, ordered from highest level (System) to lowest (the context where we want to compute the permission).
*a row for each context, also listed from highest to lowest.

[[Image:Calculation-3A.png|Empty table]]

The role definitions go in the first row. Put each definition in the column(s) coresponding to the context(s) in which the role is assigned:

[[Image:Calculation-5A.png|Table with assignments added]]

The overrides go in the remaining rows. Each override goes
*in the same column as the role being overridden
*in the row corresponding the context in which the override is made.

To illustrate, let's add just one of the overrides:

[[Image:Calculation-6A.png|Table with just one override]]

R2(X) represents the override to role R2 made in the course context. Let's add the rest of the overrides:

[[Image:Calculation-7A.png|Table with remaining overrides shown]]

The table is now fully populated, and we are ready to calculate the permission.

===The algorithm===

The algorithm follows a path through the table indicated by nodes and arrows in the diagram below and stops as soon as it has a conclusive result.

[[Image:Algorithm_path_through_permission_table_A.png|Algorithm path through permissions data]]

# If there is an X anywhere in the table, STOP. The calculated permission is ''X''
# Go to the START node
# If there is no next node, STOP. The calculated permission is ''P''
# Otherwise, follow the arrow to the next node
#Add the permissions in the node using the numerical equivalents: N = 0, A = +1, P = -1
#* If the sum is positive, STOP. The calculated permission is ''A''
#* If the sum is negative, STOP. The calculated permission is ''P''
#* If the sum is zero, GO TO step 3

Notice that the algorithm stops when either (1) a conclusive result is obtained, or (2) the algorithm reaches the last node without a conclusive result.

===Applying the algorithm to our example===

If we execute the algorithm with the quiz data, we stop at step 1 with a calculated permission of X. That's not very interesting, so let's change the X to a P and see what happens:

[[Image:Calculation-8A.png|Change X to P in permission table]]

Run the algorithm:

*There is No X in the table
*Go to the START node
*Go to the next node
*N + N = 0
*the sum is zero; go to the next node
*A + P = 0
*the sum is zero; go to the next node
*P + A = 0
*the sum is zero; go to the next node
*A + P = 0
*the sum is zero; go to the next node
*N = 0
*the sum is zero; go to the next node
*A = +1
*the sum is positive; STOP. The calculated permission is ''A''

If the calculated permission is ''A'', ''has_capability()'' returns ''true'', and the user is allowed to perform the action.

Had the calculated permission been ''P'' or ''X'', ''has_capability()'' would not immediately return ''false''. Rather, it would test if the user has ''moodle/site:doanything = Allow'' (since this permission trumps all others). The function does this by calling itself:

final result = has_capability(moodle/site:doanything,CONTEXT, USER);

==A note about the algorithm==

Earlier, we said that the algorithm "calculates the result you would expect." But what do we expect? Intuition tells us that permissions closer to the user should carry more weight than more distant permissions. That's why we set up the table the way we did and why the algorithm walks the table in the order that it does. The last column of the table represents the role assignment(s) closest to the user. The second-to-last column represents the role assignent(s) that are next in terms of distance from the user, and so-on. That's why the algorithm considers the columns from right-to-left. Within a column, the algorithm searches upward in order to give higher weight to overrides that are closer to the user. Once again, this matches our intuition about overrides. If there are no overrides in a column (or the overrides are all Not set), the permission in the role definition is used.

==Getting the result you expect==

The calculation is more likely to give "the result you would expect" if you keep your permissions as simple as possible. Therefore, we recommend the following 'rules' for defining and overriding roles. If you understand the description of the calculation above, you should understand why they make sense.

===When defining roles===

... use Allow (A) for things you want the role to be able to do, and use Not set (N) for things you don't care about (which should include most things).

===When overriding permissions===

... leave the permission for every capability as Inherit (N) apart from the few you want to change. For those, use Allow (A) for things you want to allow, and Prevent (P) for things you want to prevent.

===Only use prohibit in special roles===

Prohibit exists to cover extreme scenarios such as the following: Suppose you have a naughty student who is posting inappropriate content in your Moodle site. You need to be able to remove their ability to contribute to public discussions until they have promised not to do it again, but during that time, you cannot completely block them from the resources, quizzes, etc. because they must keep up with their studying. Therefore, you need a way to block their access to specific capabilities e.g. mod/forum:replypost in a way that cannot be overridden. You can do this by creating a special 'Naughty student' role defined with the required permission(s) set to prohibit. Then when you are having problems with a user, you can temporarily assign them this role, either at site level or at course level.

==A practical example==

Suppose that a user, who is assigned the role of Course creator in category B, creates a course (becoming Teacher in the course) and then creates a Lesson within the course. The user is about to edit the lesson (editing lessons is controlled by capability ''mod/lesson:edit''). Here is the permission data:

0 System <---- define Auth user(N), Creator(N), Teacher(A)
| assign Auth user
|
1 Category A
|
|
2 Subcategory B <---- assign Creator
|
|
3 Course <---- assign Teacher
|
|
4 Lesson <---- user attempts to edit lesson

We set up the table and populate it with permission data.

[[Image:Calculation-10A.png|A practical example]]

Since there are no overrides, the table only has data in the first row. The algorithm quickly calculates a permission of ''A'' and returns true. The user is allowed to edit the Lesson!

Now suppose Teacher is overridden in the Lesson context with ''mod/lesson:edit = P''. Then the table changes

[[Image:Calculation-11A.png|A practical example with first override]]

and clearly the user is no longer allowed to edit the Lesson.

But suppose the administrator (or whoever is making the overrides) decided instead to override the ''Creator role'', setting ''mod/lesson:edit = Prevent'' in the Categoy B context:

[[Image:Calculation-12A.png|A practical example with second override]]

Much to everyone's surprise, the user is still allowed to edit the Lesson! If you understood this article, you shouldn't be surprised, and you should be able to explain what happened.

==See also==

*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=90140 Logged in: what role am I?] and [http://moodle.org/mod/forum/discuss.php?d=66782 What happens if a user has multiple roles in a course?] forum discussions.

There is a script that you can use to create tables like the ones in this article. It is very useful for debugging roles-related problems. See [[The rolesdebug.php roles debugging script]].

[[Category:Roles]]

[[fr:Comment les permissions sont calculées ?]]

The rolesdebug.php roles debugging script

2008-05-01T12:50:06Z

Jisner:

{{Roles}}{{Moodle 1.9}}
Rolesdebug.php is a stand-alone script that is extremely useful for debugging problems related to roles and permissions. The output can be interpreted by anyone with a good understanding of Moodle's [[Roles and capabilities]] system. If you're a "roles novice" and you need help with a roles-related problem, you can ask a roles expert to help you with running the script and interpreting the output. If you don't have access to an expert, post a request for help to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]. After using the script a few times, you'll be an expert too!

You can download rolesdebug.php from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and Plugins database]. To install the script, simply drop it into the Moodle root directory or any directory under the root directory.

Rolesdebug.php requires a login, so only someone with a Moodle user account who is currently logged in can use it. Since it is a php script, you will see the output in your browser. No one else will see it unless they're looking over your shoulder. Furthermore, rolesdebug.php gives you information about YOUR permissions. You cannot use it to get information about another user's permissions, unless you can login as them.

Rolesdebug.php returns a table that gives a spatial view of the role assignments and overrides that affect you in a specified context. From the table, you will be able to see how Moodle calculates a specified permission. The table format is explained (and several examples are given) in the article [[How permissions are calculated]].

Rolesdebug.php reads permission data from the Moodle database but does not modify the database in any way. In this respect, it is similar to other debug scripts in the standard distribution, like the [[TeX_notation_filter#Debugging_TeX_filter | TeX notation debugger]].

==The use case for rolesdebug.php==

The main use case for rolesdebug.php is a ''roles expert helping a roles novice troubleshoot a roles-related problem''. A ''roles expert'' is anyone with a basic understanding of the [[#Essential roles and capabilities concepts | essential roles concepts]] listed in the next section. A ''roles novice'' is any Moodle user with the ability to follow simple instructions from the expert. While the expert and novice may occasionally share the same physical location and have accounts on the same Moodle site, it is not required. The expert must be able to help the novice without logging in to the novice's site, and by communicating with the novice only by e-mail, messaging, forum posts, etc.. For example, the novice may be a user posting to a moodle.org forum and the expert may be a moodler wanting to be helpful. Even when expert and novice share a physical location and have accounts on the same Moodle site, the expert may not be in a position to give direct help, e.g., by "logging in as" the novice or meeting with the novice. For example, the expert may be a Moodle administrator with an extremely busy schedule.

Here's a typical scenario. Supposed the novice is a teacher who has created a quiz, but is being prevented from previewing the quiz for some unknown reason. The novice reports the problem to moodle.org in a forum post. The expert (a helpful moodler) suspects a roles problem and replies by asking the novice to (1) log in to Moodle, reproduce the problem (2) browse to rolesdebug.php (3) enter two or three parameters as specified by the expert (4) paste the output from rolesdebug.php into a reply to this forum post. The expert reviews the output and (hopefully) diagnoses the problem.

Secondary use cases for rolesdebug.php include
* a user troubleshooting his own problems
* a user troubleshooting another user's problem while logged in as that user

Note that both of these secondary use cases are equivalent, since there is only one actor (the expert), not two. To keep things simple in the remainder of the article, I'll describe the secondary use case, and I'll refer only to YOU. Keeping the primary use case in mind, it should be clear when "you" means roles expert and when it means the roles novice.

==Essential roles and capabilities concepts==

Interpreting the output from rolesdebug.php requires at least a basic understanding of the concepts listed below. If any of these concepts are unfamiliar to you, stop and follow the documentation link.

* [[Assign_roles#Contexts | Context]]
* [[Capabilities | Capability]]
* [[Capabilities | Permission]]
* [[Capabilities | Role]]
* [[Assign_roles | Role assignment]]
* [[Override_permissions | Role override]]
* [[How permissions are calculated]]

==Overview of a script session==

First, you will log in to Moodle and navigate to the context where you're having the problem. Perhaps this is a quiz which Moodle, for some unknown reason, is preventing you from attempting. Then, without logging out of Moodle, point your browser at rolesdebug.php (I find it convenient to open a new browser tab for this). Input the ''context'' you're interested in and (optionally) the name of a ''capability'' to investigate, then press the Go button. The script will return a page with a table presenting a spatial view of the role assignments and overrides that affect you in the specified context. From the table, you will be able to see why Moodle is preventing you from attempting the quiz.

==Using the script==

===STEP1===
This step is done in Moodle (you won't use the script until STEP 2). Login to Moodle and navigate into the context where the problem is occurring. Once you're there, you'll make note of the context id, which is needed in STEP 2. I'll tell you [[#How to determine the context id|how to determine the context id]] later.

Incidentally, even if you know the context id, it is essential that you actually navigate to the context. This is because Moodle loads certain permission data "lazily" -- i.e., only when actually needed. Navigating to the context guarantees that Moodle will have loaded the data. For example, suppose the target context is a certain quiz in some course. You must enter the course and click on the Quiz icon.

However if you are debugging a problem related to a change to a user policy such as Site administration -> Front page -> Front page settings -> Default front page role, you must logout and log back in after making the change.

Do not log out!

===STEP 2===
Open a second browser window. In the window, point your browser at
rolesdebug.php. The script URL will be something like

http://yoursite/moodle/rolesdebug.php

Rolesdebug.php will NOT ask you to login because you are already logged in. The script will ask you for three inputs:

* CAPABILITY. If you're only interested in seeing your role assignments and overrides, you can leave this field empty. If you're interested in analyzing a particular permission, you'll need to enter the capability name. For example, if you're interested in the capability that controls your ability to attempt quizzes, enter [[Capabilities/mod/quiz:attempt | mod/quiz:attempt]].

* CONTEXT TYPE. Choose one of the following from the dropdown menu:
**COURSE
**MODULE
**BLOCK
**COURSECAT
**USER
**SYSTEM

* CONTEXT ID. The context id is a number at the end of the URL of the page you found in STEP 1. See [[#How to determine the context id|How to determine the context id]] below.

Incidentally, MODULE means activity or resource. There is no FRONT PAGE context. If you're interested in the Front page context, choose COURSE and specify a context id of 1.

Here's an example of input:

[[Image:sample_input_quiz_attempt.png|sample input when investigating a quiz attempt]]

===STEP 3===
Press the Go button. Rolesdebug.php will return a page of information. The main item on the page is a table giving a spatial view of all the role assignments and overrides that affect you in the specified context.

==How to read the output==
Let's look at a typical output for the input parameters from the last section.
[[Image:sample_output_quiz_attempt.png|sample output when investigating a quiz attempt]]

The first three lines of output (1) simply echo your input values, and the next two lines (2) remind you of who YOU are, and tell you the actual name of the context you have selected. Check these carefully to make
sure you are who you think you are, and have specified the correct context.

For each of your roles, you will see a line of the form ''alias = role name'' where
* ''role name'' is the actual role name
* ''alias'' is the name used to represent the role in the table

In the example, ''R7 = user'' means the the role user (the shortname of Authorized user) will be represented in the table by the alias R7. Aliases are used because long role names could make the table very wide, forcing you to scroll horizontally. By using aliases, the table will hopefully fit in a window, allowing you to see the entire table in a single a glance.

Next comes the table (4). I'll have a lot more to say about the table below.

If you specified a capability, then you will see the three lines immediately after the table (5).
* The first line gives the calculated permission, which is based on the table. The value can be either A (Allow) or P (Prevent).
* The second line tells you if you are able to "do anything," that is, if you have moodle/site:doanything = Allow (this is typically only true for administrators)
* The third line tells you if you can "do this." If you can do anything, you can obviously do this regardless of the calculated permission.

====How to read the table====

If the target context is N levels deep, the table will have N rows and N columns, one for each context level. The example above has four levels:

System
|
|
Category "A"
|
|
Course "cooking"
|
|
Module "quiz-1"

The column headings give the names of the contexts. These are listed in order of increasing depth: System, A, cooking, quiz-1.

To save space, the table does not have row headings. If it did, they would be the same as the column headings. For example, row 1 would be labeled "System" and row 4 would be labeled "quiz-1".

The first row of the table contains the role assignments made in each context level. In the example, you can see that R7 (Authorized user) is assigned in the System context and R5 (Student) is assigned in the course context. If there are no overrides (as in this example) you will only see entries in row 1.

The letters N and A in parentheses are the values of the capabilities in the role definitions. The possible values are:

N - Not set
A - Allow
P - Prevent
X - Prohibit

"Not set" means that the role doesn't say anything about the capability. In the example, we see that the Student role allows
quiz attempts, while the Authorized user role doesn't have anything
to say about quiz attempts.

If there are role overrides, there will be entries in other rows of the table. Overrides have the same format as the assignments in row 1. An override is shown in the ROW of the context where it is made, and the COLUMN of the assignment that it overrides.

To illustrate, let's override the Student role in the Quiz context, setting mod/quiz:attempt to Prevent, and then rerun rolesdebug.php. Of course before running the script, the student must attempt the quiz. This time, the student should be prevented because of the override. Now we run the script and get the following output:
[[Image:sample_output_quiz_attempt_with_override.png|sample output when investigating a quiz attempt and there is an override]]

Notice the newly added R5(P). This is the override. It is in the fourth row because the override was made in the quiz context, and it is in the course column because the Student role was assigned in the Course context.

The calculated permission is now P, as expected.

====How Moodle calculates the permission====
For a full explanation of how permissions are calculated, see the article [[How permissions are calculated | How permissions are calculated]]. This section merely illustrates the calculation for the examples given in this article.

For the original example (where we only had role assignments in row 1),
Moodle scans the table from right to left.
[[Image:sample_output_quiz_attempt_showing_path.png|how to scan the table when investigating a quiz attempt]]
Since the first permission it hits is an 'A' the calculated permission is 'A'.

When we added the override, Moodle scans the table in a zig-zag fashion, as shown below.
[[Image:sample_output_quiz_attempt_with_override_showing_path.png|how to scan the table when investigating a quiz attempt and there is an override]]
Since the first permission it hits is a 'P' the calculated permission is 'P'.

==How to determine the context id==
Here are rules for determining the context id for each context type.
===COURSE===
For a COURSE context, the context id is the course id. You can get the course id from the URL that appears in the address bar when when you're on the course page. For example when I point my browser at the "Features" course on demo.moodle.org, I see this:

[[Image:URI_of_course_in_address_bar.png|URI of course is shown in the address bar]]

The course id, and therefore the context id for this course is 2.

If Moodle won't let you enter the course for some reason, but you can see a link to the course, let your mouse hover over the link as in the following screenshot. Your browser will show you the address at the bottom of the window.

[[Image:URI_of_course_at_bottom_of_browser_window.png|URI of course is shown at the bottom of the browser window]]

The front page of a Moodle site is also a course, but you can't use either of the above tricks to get the id. ''The front page course id is 1.''

===MODULE (activity or resource)===
For a MODULE context, the context id is the activity or resource id. You can get the id from the URL that appears in the address bar when you're viewing the activity or resource, or from the bottom of the browser window when you let your mouse hover over a link. Here are some examples:

http://demo.moodle.org/mod/choice/view.php?id=25
http://demo.moodle.org/mod/forum/view.php?id=28
http://demo.moodle.org/mod/lesson/view.php?id=38
http://demo.moodle.org/mod/quiz/view.php?id=61
http://demo.moodle.org/mod/resource/view.php?id=10
http://demo.moodle.org/mod/resource/view.php?id=48

The context id's for these modules are 25, 28, 38, 61, 10, and 48.

===BLOCK===
For a BLOCK context, the context id is the "instanceid" of the block. To get the instanceid, turn editing on and let the mouse hover over the "eye" icon in the block header. Then take the instanceid from URL that appears in the at the bottom of the window. For example:

http://demo.moodle.org/course/view.php?id=28&instanceid=19...

The context id for this block is 19. Note that for blocks, only a user who can turn editing on can get the instanceid.

===COURSECAT===
For a COURSECAT context, the context id is the category id. You can get the id from the URL that appears in the address bar when you're on the category page. If the site has only one category (usually called "Miscellaneous") the id is 1. If there is more than one category, the easiest way to get the category id for a specific category is to have a Category list or a Combo list on the front page of the site (or a Courses block) and let your mouse hover over one of the links. For example:

http://mysite/course/category.php?id=3

The context id for this category is 3

===USER===
For a USER context, the context id is the user id. You can get the id from the URL that appears in the address bar when you're on a profile page, or from the bottom of the browser window when you let your mouse hover over a user's name. For example:

http://demo.moodle.org/user/view.php?id=6&course=1

The context id for this user is 6

===SYSTEM===
There is only one SYSTEM context. Its id is 1.

[[Category:Contributed code]]

The rolesdebug.php roles debugging script

2008-05-01T12:49:49Z

Jisner:

{{Roles}}{{Moodle 1.9}}
Rolesdebug.php is a stand-alone script that is extremely useful for debugging problems related to roles and permissions. The output can be interpreted by anyone with a good understanding of Moodle's [[Roles and capabilities]] system. If you're a "roles novice" and you need help with a roles-related problem, you can ask a roles expert to help you with running the script and interpreting the output. If you don't have access to an expert, post a request for help to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum]. After using the script a few times, you'll be an expert too.

You can download rolesdebug.php from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and Plugins database]. To install the script, simply drop it into the Moodle root directory or any directory under the root directory.

Rolesdebug.php requires a login, so only someone with a Moodle user account who is currently logged in can use it. Since it is a php script, you will see the output in your browser. No one else will see it unless they're looking over your shoulder. Furthermore, rolesdebug.php gives you information about YOUR permissions. You cannot use it to get information about another user's permissions, unless you can login as them.

Rolesdebug.php returns a table that gives a spatial view of the role assignments and overrides that affect you in a specified context. From the table, you will be able to see how Moodle calculates a specified permission. The table format is explained (and several examples are given) in the article [[How permissions are calculated]].

Rolesdebug.php reads permission data from the Moodle database but does not modify the database in any way. In this respect, it is similar to other debug scripts in the standard distribution, like the [[TeX_notation_filter#Debugging_TeX_filter | TeX notation debugger]].

==The use case for rolesdebug.php==

The main use case for rolesdebug.php is a ''roles expert helping a roles novice troubleshoot a roles-related problem''. A ''roles expert'' is anyone with a basic understanding of the [[#Essential roles and capabilities concepts | essential roles concepts]] listed in the next section. A ''roles novice'' is any Moodle user with the ability to follow simple instructions from the expert. While the expert and novice may occasionally share the same physical location and have accounts on the same Moodle site, it is not required. The expert must be able to help the novice without logging in to the novice's site, and by communicating with the novice only by e-mail, messaging, forum posts, etc.. For example, the novice may be a user posting to a moodle.org forum and the expert may be a moodler wanting to be helpful. Even when expert and novice share a physical location and have accounts on the same Moodle site, the expert may not be in a position to give direct help, e.g., by "logging in as" the novice or meeting with the novice. For example, the expert may be a Moodle administrator with an extremely busy schedule.

Here's a typical scenario. Supposed the novice is a teacher who has created a quiz, but is being prevented from previewing the quiz for some unknown reason. The novice reports the problem to moodle.org in a forum post. The expert (a helpful moodler) suspects a roles problem and replies by asking the novice to (1) log in to Moodle, reproduce the problem (2) browse to rolesdebug.php (3) enter two or three parameters as specified by the expert (4) paste the output from rolesdebug.php into a reply to this forum post. The expert reviews the output and (hopefully) diagnoses the problem.

Secondary use cases for rolesdebug.php include
* a user troubleshooting his own problems
* a user troubleshooting another user's problem while logged in as that user

Note that both of these secondary use cases are equivalent, since there is only one actor (the expert), not two. To keep things simple in the remainder of the article, I'll describe the secondary use case, and I'll refer only to YOU. Keeping the primary use case in mind, it should be clear when "you" means roles expert and when it means the roles novice.

==Essential roles and capabilities concepts==

Interpreting the output from rolesdebug.php requires at least a basic understanding of the concepts listed below. If any of these concepts are unfamiliar to you, stop and follow the documentation link.

* [[Assign_roles#Contexts | Context]]
* [[Capabilities | Capability]]
* [[Capabilities | Permission]]
* [[Capabilities | Role]]
* [[Assign_roles | Role assignment]]
* [[Override_permissions | Role override]]
* [[How permissions are calculated]]

==Overview of a script session==

First, you will log in to Moodle and navigate to the context where you're having the problem. Perhaps this is a quiz which Moodle, for some unknown reason, is preventing you from attempting. Then, without logging out of Moodle, point your browser at rolesdebug.php (I find it convenient to open a new browser tab for this). Input the ''context'' you're interested in and (optionally) the name of a ''capability'' to investigate, then press the Go button. The script will return a page with a table presenting a spatial view of the role assignments and overrides that affect you in the specified context. From the table, you will be able to see why Moodle is preventing you from attempting the quiz.

==Using the script==

===STEP1===
This step is done in Moodle (you won't use the script until STEP 2). Login to Moodle and navigate into the context where the problem is occurring. Once you're there, you'll make note of the context id, which is needed in STEP 2. I'll tell you [[#How to determine the context id|how to determine the context id]] later.

Incidentally, even if you know the context id, it is essential that you actually navigate to the context. This is because Moodle loads certain permission data "lazily" -- i.e., only when actually needed. Navigating to the context guarantees that Moodle will have loaded the data. For example, suppose the target context is a certain quiz in some course. You must enter the course and click on the Quiz icon.

However if you are debugging a problem related to a change to a user policy such as Site administration -> Front page -> Front page settings -> Default front page role, you must logout and log back in after making the change.

Do not log out!

===STEP 2===
Open a second browser window. In the window, point your browser at
rolesdebug.php. The script URL will be something like

http://yoursite/moodle/rolesdebug.php

Rolesdebug.php will NOT ask you to login because you are already logged in. The script will ask you for three inputs:

* CAPABILITY. If you're only interested in seeing your role assignments and overrides, you can leave this field empty. If you're interested in analyzing a particular permission, you'll need to enter the capability name. For example, if you're interested in the capability that controls your ability to attempt quizzes, enter [[Capabilities/mod/quiz:attempt | mod/quiz:attempt]].

* CONTEXT TYPE. Choose one of the following from the dropdown menu:
**COURSE
**MODULE
**BLOCK
**COURSECAT
**USER
**SYSTEM

* CONTEXT ID. The context id is a number at the end of the URL of the page you found in STEP 1. See [[#How to determine the context id|How to determine the context id]] below.

Incidentally, MODULE means activity or resource. There is no FRONT PAGE context. If you're interested in the Front page context, choose COURSE and specify a context id of 1.

Here's an example of input:

[[Image:sample_input_quiz_attempt.png|sample input when investigating a quiz attempt]]

===STEP 3===
Press the Go button. Rolesdebug.php will return a page of information. The main item on the page is a table giving a spatial view of all the role assignments and overrides that affect you in the specified context.

==How to read the output==
Let's look at a typical output for the input parameters from the last section.
[[Image:sample_output_quiz_attempt.png|sample output when investigating a quiz attempt]]

The first three lines of output (1) simply echo your input values, and the next two lines (2) remind you of who YOU are, and tell you the actual name of the context you have selected. Check these carefully to make
sure you are who you think you are, and have specified the correct context.

For each of your roles, you will see a line of the form ''alias = role name'' where
* ''role name'' is the actual role name
* ''alias'' is the name used to represent the role in the table

In the example, ''R7 = user'' means the the role user (the shortname of Authorized user) will be represented in the table by the alias R7. Aliases are used because long role names could make the table very wide, forcing you to scroll horizontally. By using aliases, the table will hopefully fit in a window, allowing you to see the entire table in a single a glance.

Next comes the table (4). I'll have a lot more to say about the table below.

If you specified a capability, then you will see the three lines immediately after the table (5).
* The first line gives the calculated permission, which is based on the table. The value can be either A (Allow) or P (Prevent).
* The second line tells you if you are able to "do anything," that is, if you have moodle/site:doanything = Allow (this is typically only true for administrators)
* The third line tells you if you can "do this." If you can do anything, you can obviously do this regardless of the calculated permission.

====How to read the table====

If the target context is N levels deep, the table will have N rows and N columns, one for each context level. The example above has four levels:

System
|
|
Category "A"
|
|
Course "cooking"
|
|
Module "quiz-1"

The column headings give the names of the contexts. These are listed in order of increasing depth: System, A, cooking, quiz-1.

To save space, the table does not have row headings. If it did, they would be the same as the column headings. For example, row 1 would be labeled "System" and row 4 would be labeled "quiz-1".

The first row of the table contains the role assignments made in each context level. In the example, you can see that R7 (Authorized user) is assigned in the System context and R5 (Student) is assigned in the course context. If there are no overrides (as in this example) you will only see entries in row 1.

The letters N and A in parentheses are the values of the capabilities in the role definitions. The possible values are:

N - Not set
A - Allow
P - Prevent
X - Prohibit

"Not set" means that the role doesn't say anything about the capability. In the example, we see that the Student role allows
quiz attempts, while the Authorized user role doesn't have anything
to say about quiz attempts.

If there are role overrides, there will be entries in other rows of the table. Overrides have the same format as the assignments in row 1. An override is shown in the ROW of the context where it is made, and the COLUMN of the assignment that it overrides.

To illustrate, let's override the Student role in the Quiz context, setting mod/quiz:attempt to Prevent, and then rerun rolesdebug.php. Of course before running the script, the student must attempt the quiz. This time, the student should be prevented because of the override. Now we run the script and get the following output:
[[Image:sample_output_quiz_attempt_with_override.png|sample output when investigating a quiz attempt and there is an override]]

Notice the newly added R5(P). This is the override. It is in the fourth row because the override was made in the quiz context, and it is in the course column because the Student role was assigned in the Course context.

The calculated permission is now P, as expected.

====How Moodle calculates the permission====
For a full explanation of how permissions are calculated, see the article [[How permissions are calculated | How permissions are calculated]]. This section merely illustrates the calculation for the examples given in this article.

For the original example (where we only had role assignments in row 1),
Moodle scans the table from right to left.
[[Image:sample_output_quiz_attempt_showing_path.png|how to scan the table when investigating a quiz attempt]]
Since the first permission it hits is an 'A' the calculated permission is 'A'.

When we added the override, Moodle scans the table in a zig-zag fashion, as shown below.
[[Image:sample_output_quiz_attempt_with_override_showing_path.png|how to scan the table when investigating a quiz attempt and there is an override]]
Since the first permission it hits is a 'P' the calculated permission is 'P'.

==How to determine the context id==
Here are rules for determining the context id for each context type.
===COURSE===
For a COURSE context, the context id is the course id. You can get the course id from the URL that appears in the address bar when when you're on the course page. For example when I point my browser at the "Features" course on demo.moodle.org, I see this:

[[Image:URI_of_course_in_address_bar.png|URI of course is shown in the address bar]]

The course id, and therefore the context id for this course is 2.

If Moodle won't let you enter the course for some reason, but you can see a link to the course, let your mouse hover over the link as in the following screenshot. Your browser will show you the address at the bottom of the window.

[[Image:URI_of_course_at_bottom_of_browser_window.png|URI of course is shown at the bottom of the browser window]]

The front page of a Moodle site is also a course, but you can't use either of the above tricks to get the id. ''The front page course id is 1.''

===MODULE (activity or resource)===
For a MODULE context, the context id is the activity or resource id. You can get the id from the URL that appears in the address bar when you're viewing the activity or resource, or from the bottom of the browser window when you let your mouse hover over a link. Here are some examples:

http://demo.moodle.org/mod/choice/view.php?id=25
http://demo.moodle.org/mod/forum/view.php?id=28
http://demo.moodle.org/mod/lesson/view.php?id=38
http://demo.moodle.org/mod/quiz/view.php?id=61
http://demo.moodle.org/mod/resource/view.php?id=10
http://demo.moodle.org/mod/resource/view.php?id=48

The context id's for these modules are 25, 28, 38, 61, 10, and 48.

===BLOCK===
For a BLOCK context, the context id is the "instanceid" of the block. To get the instanceid, turn editing on and let the mouse hover over the "eye" icon in the block header. Then take the instanceid from URL that appears in the at the bottom of the window. For example:

http://demo.moodle.org/course/view.php?id=28&instanceid=19...

The context id for this block is 19. Note that for blocks, only a user who can turn editing on can get the instanceid.

===COURSECAT===
For a COURSECAT context, the context id is the category id. You can get the id from the URL that appears in the address bar when you're on the category page. If the site has only one category (usually called "Miscellaneous") the id is 1. If there is more than one category, the easiest way to get the category id for a specific category is to have a Category list or a Combo list on the front page of the site (or a Courses block) and let your mouse hover over one of the links. For example:

http://mysite/course/category.php?id=3

The context id for this category is 3

===USER===
For a USER context, the context id is the user id. You can get the id from the URL that appears in the address bar when you're on a profile page, or from the bottom of the browser window when you let your mouse hover over a user's name. For example:

http://demo.moodle.org/user/view.php?id=6&course=1

The context id for this user is 6

===SYSTEM===
There is only one SYSTEM context. Its id is 1.

[[Category:Contributed code]]

The rolesdebug.php roles debugging script

2008-05-01T12:47:35Z

Jisner: /* How Moodle calculates the final permission */

{{Roles}}{{Moodle 1.9}}
Rolesdebug.php is a stand-alone script that is extremely useful for debugging problems related to roles and permissions. The output can be interpreted by anyone with a good understanding of Moodle's [[Roles and capabilities]] system. If you're a "roles novice" and you need help with a roles-related problem, you can ask a roles expert to help you with running the script and interpreting the output. Simply post a request for help to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum].

You can download rolesdebug.php from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and Plugins database]. To install the script, simply drop it into the Moodle root directory or any directory under the root directory.

Rolesdebug.php requires a login, so only someone with a Moodle user account who is currently logged in can use it. Since it is a php script, you will see the output in your browser. No one else will see it unless they're looking over your shoulder. Furthermore, rolesdebug.php gives you information about YOUR permissions. You cannot use it to get information about another user's permissions, unless you can login as them.

Rolesdebug.php returns a table that gives a spatial view of the role assignments and overrides that affect you in a specified context. From the table, you will be able to see how Moodle calculates a specified permission. The table format is explained (and several examples are given) in the article [[How permissions are calculated]].

Rolesdebug.php reads permission data from the Moodle database but does not modify the database in any way. In this respect, it is similar to other debug scripts in the standard distribution, like the [[TeX_notation_filter#Debugging_TeX_filter | TeX notation debugger]].

==The use case for rolesdebug.php==

The main use case for rolesdebug.php is a ''roles expert helping a roles novice troubleshoot a roles-related problem''. A ''roles expert'' is anyone with a basic understanding of the [[#Essential roles and capabilities concepts | essential roles concepts]] listed in the next section. A ''roles novice'' is any Moodle user with the ability to follow simple instructions from the expert. While the expert and novice may occasionally share the same physical location and have accounts on the same Moodle site, it is not required. The expert must be able to help the novice without logging in to the novice's site, and by communicating with the novice only by e-mail, messaging, forum posts, etc.. For example, the novice may be a user posting to a moodle.org forum and the expert may be a moodler wanting to be helpful. Even when expert and novice share a physical location and have accounts on the same Moodle site, the expert may not be in a position to give direct help, e.g., by "logging in as" the novice or meeting with the novice. For example, the expert may be a Moodle administrator with an extremely busy schedule.

Here's a typical scenario. Supposed the novice is a teacher who has created a quiz, but is being prevented from previewing the quiz for some unknown reason. The novice reports the problem to moodle.org in a forum post. The expert (a helpful moodler) suspects a roles problem and replies by asking the novice to (1) log in to Moodle, reproduce the problem (2) browse to rolesdebug.php (3) enter two or three parameters as specified by the expert (4) paste the output from rolesdebug.php into a reply to this forum post. The expert reviews the output and (hopefully) diagnoses the problem.

Secondary use cases for rolesdebug.php include
* a user troubleshooting his own problems
* a user troubleshooting another user's problem while logged in as that user

Note that both of these secondary use cases are equivalent, since there is only one actor (the expert), not two. To keep things simple in the remainder of the article, I'll describe the secondary use case, and I'll refer only to YOU. Keeping the primary use case in mind, it should be clear when "you" means roles expert and when it means the roles novice.

==Essential roles and capabilities concepts==

Interpreting the output from rolesdebug.php requires at least a basic understanding of the concepts listed below. If any of these concepts are unfamiliar to you, stop and follow the documentation link.

* [[Assign_roles#Contexts | Context]]
* [[Capabilities | Capability]]
* [[Capabilities | Permission]]
* [[Capabilities | Role]]
* [[Assign_roles | Role assignment]]
* [[Override_permissions | Role override]]
* [[How permissions are calculated]]

==Overview of a script session==

First, you will log in to Moodle and navigate to the context where you're having the problem. Perhaps this is a quiz which Moodle, for some unknown reason, is preventing you from attempting. Then, without logging out of Moodle, point your browser at rolesdebug.php (I find it convenient to open a new browser tab for this). Input the ''context'' you're interested in and (optionally) the name of a ''capability'' to investigate, then press the Go button. The script will return a page with a table presenting a spatial view of the role assignments and overrides that affect you in the specified context. From the table, you will be able to see why Moodle is preventing you from attempting the quiz.

==Using the script==

===STEP1===
This step is done in Moodle (you won't use the script until STEP 2). Login to Moodle and navigate into the context where the problem is occurring. Once you're there, you'll make note of the context id, which is needed in STEP 2. I'll tell you [[#How to determine the context id|how to determine the context id]] later.

Incidentally, even if you know the context id, it is essential that you actually navigate to the context. This is because Moodle loads certain permission data "lazily" -- i.e., only when actually needed. Navigating to the context guarantees that Moodle will have loaded the data. For example, suppose the target context is a certain quiz in some course. You must enter the course and click on the Quiz icon.

However if you are debugging a problem related to a change to a user policy such as Site administration -> Front page -> Front page settings -> Default front page role, you must logout and log back in after making the change.

Do not log out!

===STEP 2===
Open a second browser window. In the window, point your browser at
rolesdebug.php. The script URL will be something like

http://yoursite/moodle/rolesdebug.php

Rolesdebug.php will NOT ask you to login because you are already logged in. The script will ask you for three inputs:

* CAPABILITY. If you're only interested in seeing your role assignments and overrides, you can leave this field empty. If you're interested in analyzing a particular permission, you'll need to enter the capability name. For example, if you're interested in the capability that controls your ability to attempt quizzes, enter [[Capabilities/mod/quiz:attempt | mod/quiz:attempt]].

* CONTEXT TYPE. Choose one of the following from the dropdown menu:
**COURSE
**MODULE
**BLOCK
**COURSECAT
**USER
**SYSTEM

* CONTEXT ID. The context id is a number at the end of the URL of the page you found in STEP 1. See [[#How to determine the context id|How to determine the context id]] below.

Incidentally, MODULE means activity or resource. There is no FRONT PAGE context. If you're interested in the Front page context, choose COURSE and specify a context id of 1.

Here's an example of input:

[[Image:sample_input_quiz_attempt.png|sample input when investigating a quiz attempt]]

===STEP 3===
Press the Go button. Rolesdebug.php will return a page of information. The main item on the page is a table giving a spatial view of all the role assignments and overrides that affect you in the specified context.

==How to read the output==
Let's look at a typical output for the input parameters from the last section.
[[Image:sample_output_quiz_attempt.png|sample output when investigating a quiz attempt]]

The first three lines of output (1) simply echo your input values, and the next two lines (2) remind you of who YOU are, and tell you the actual name of the context you have selected. Check these carefully to make
sure you are who you think you are, and have specified the correct context.

For each of your roles, you will see a line of the form ''alias = role name'' where
* ''role name'' is the actual role name
* ''alias'' is the name used to represent the role in the table

In the example, ''R7 = user'' means the the role user (the shortname of Authorized user) will be represented in the table by the alias R7. Aliases are used because long role names could make the table very wide, forcing you to scroll horizontally. By using aliases, the table will hopefully fit in a window, allowing you to see the entire table in a single a glance.

Next comes the table (4). I'll have a lot more to say about the table below.

If you specified a capability, then you will see the three lines immediately after the table (5).
* The first line gives the calculated permission, which is based on the table. The value can be either A (Allow) or P (Prevent).
* The second line tells you if you are able to "do anything," that is, if you have moodle/site:doanything = Allow (this is typically only true for administrators)
* The third line tells you if you can "do this." If you can do anything, you can obviously do this regardless of the calculated permission.

====How to read the table====

If the target context is N levels deep, the table will have N rows and N columns, one for each context level. The example above has four levels:

System
|
|
Category "A"
|
|
Course "cooking"
|
|
Module "quiz-1"

The column headings give the names of the contexts. These are listed in order of increasing depth: System, A, cooking, quiz-1.

To save space, the table does not have row headings. If it did, they would be the same as the column headings. For example, row 1 would be labeled "System" and row 4 would be labeled "quiz-1".

The first row of the table contains the role assignments made in each context level. In the example, you can see that R7 (Authorized user) is assigned in the System context and R5 (Student) is assigned in the course context. If there are no overrides (as in this example) you will only see entries in row 1.

The letters N and A in parentheses are the values of the capabilities in the role definitions. The possible values are:

N - Not set
A - Allow
P - Prevent
X - Prohibit

"Not set" means that the role doesn't say anything about the capability. In the example, we see that the Student role allows
quiz attempts, while the Authorized user role doesn't have anything
to say about quiz attempts.

If there are role overrides, there will be entries in other rows of the table. Overrides have the same format as the assignments in row 1. An override is shown in the ROW of the context where it is made, and the COLUMN of the assignment that it overrides.

To illustrate, let's override the Student role in the Quiz context, setting mod/quiz:attempt to Prevent, and then rerun rolesdebug.php. Of course before running the script, the student must attempt the quiz. This time, the student should be prevented because of the override. Now we run the script and get the following output:
[[Image:sample_output_quiz_attempt_with_override.png|sample output when investigating a quiz attempt and there is an override]]

Notice the newly added R5(P). This is the override. It is in the fourth row because the override was made in the quiz context, and it is in the course column because the Student role was assigned in the Course context.

The calculated permission is now P, as expected.

====How Moodle calculates the permission====
For a full explanation of how permissions are calculated, see the article [[How permissions are calculated | How permissions are calculated]]. This section merely illustrates the calculation for the examples given in this article.

For the original example (where we only had role assignments in row 1),
Moodle scans the table from right to left.
[[Image:sample_output_quiz_attempt_showing_path.png|how to scan the table when investigating a quiz attempt]]
Since the first permission it hits is an 'A' the calculated permission is 'A'.

When we added the override, Moodle scans the table in a zig-zag fashion, as shown below.
[[Image:sample_output_quiz_attempt_with_override_showing_path.png|how to scan the table when investigating a quiz attempt and there is an override]]
Since the first permission it hits is a 'P' the calculated permission is 'P'.

==How to determine the context id==
Here are rules for determining the context id for each context type.
===COURSE===
For a COURSE context, the context id is the course id. You can get the course id from the URL that appears in the address bar when when you're on the course page. For example when I point my browser at the "Features" course on demo.moodle.org, I see this:

[[Image:URI_of_course_in_address_bar.png|URI of course is shown in the address bar]]

The course id, and therefore the context id for this course is 2.

If Moodle won't let you enter the course for some reason, but you can see a link to the course, let your mouse hover over the link as in the following screenshot. Your browser will show you the address at the bottom of the window.

[[Image:URI_of_course_at_bottom_of_browser_window.png|URI of course is shown at the bottom of the browser window]]

The front page of a Moodle site is also a course, but you can't use either of the above tricks to get the id. ''The front page course id is 1.''

===MODULE (activity or resource)===
For a MODULE context, the context id is the activity or resource id. You can get the id from the URL that appears in the address bar when you're viewing the activity or resource, or from the bottom of the browser window when you let your mouse hover over a link. Here are some examples:

http://demo.moodle.org/mod/choice/view.php?id=25
http://demo.moodle.org/mod/forum/view.php?id=28
http://demo.moodle.org/mod/lesson/view.php?id=38
http://demo.moodle.org/mod/quiz/view.php?id=61
http://demo.moodle.org/mod/resource/view.php?id=10
http://demo.moodle.org/mod/resource/view.php?id=48

The context id's for these modules are 25, 28, 38, 61, 10, and 48.

===BLOCK===
For a BLOCK context, the context id is the "instanceid" of the block. To get the instanceid, turn editing on and let the mouse hover over the "eye" icon in the block header. Then take the instanceid from URL that appears in the at the bottom of the window. For example:

http://demo.moodle.org/course/view.php?id=28&instanceid=19...

The context id for this block is 19. Note that for blocks, only a user who can turn editing on can get the instanceid.

===COURSECAT===
For a COURSECAT context, the context id is the category id. You can get the id from the URL that appears in the address bar when you're on the category page. If the site has only one category (usually called "Miscellaneous") the id is 1. If there is more than one category, the easiest way to get the category id for a specific category is to have a Category list or a Combo list on the front page of the site (or a Courses block) and let your mouse hover over one of the links. For example:

http://mysite/course/category.php?id=3

The context id for this category is 3

===USER===
For a USER context, the context id is the user id. You can get the id from the URL that appears in the address bar when you're on a profile page, or from the bottom of the browser window when you let your mouse hover over a user's name. For example:

http://demo.moodle.org/user/view.php?id=6&course=1

The context id for this user is 6

===SYSTEM===
There is only one SYSTEM context. Its id is 1.

[[Category:Contributed code]]

The rolesdebug.php roles debugging script

2008-05-01T12:26:08Z

Jisner: /* How to read the table */

{{Roles}}{{Moodle 1.9}}
Rolesdebug.php is a stand-alone script that is extremely useful for debugging problems related to roles and permissions. The output can be interpreted by anyone with a good understanding of Moodle's [[Roles and capabilities]] system. If you're a "roles novice" and you need help with a roles-related problem, you can ask a roles expert to help you with running the script and interpreting the output. Simply post a request for help to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum].

You can download rolesdebug.php from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and Plugins database]. To install the script, simply drop it into the Moodle root directory or any directory under the root directory.

Rolesdebug.php requires a login, so only someone with a Moodle user account who is currently logged in can use it. Since it is a php script, you will see the output in your browser. No one else will see it unless they're looking over your shoulder. Furthermore, rolesdebug.php gives you information about YOUR permissions. You cannot use it to get information about another user's permissions, unless you can login as them.

Rolesdebug.php returns a table that gives a spatial view of the role assignments and overrides that affect you in a specified context. From the table, you will be able to see how Moodle calculates a specified permission. The table format is explained (and several examples are given) in the article [[How permissions are calculated]].

Rolesdebug.php reads permission data from the Moodle database but does not modify the database in any way. In this respect, it is similar to other debug scripts in the standard distribution, like the [[TeX_notation_filter#Debugging_TeX_filter | TeX notation debugger]].

==The use case for rolesdebug.php==

The main use case for rolesdebug.php is a ''roles expert helping a roles novice troubleshoot a roles-related problem''. A ''roles expert'' is anyone with a basic understanding of the [[#Essential roles and capabilities concepts | essential roles concepts]] listed in the next section. A ''roles novice'' is any Moodle user with the ability to follow simple instructions from the expert. While the expert and novice may occasionally share the same physical location and have accounts on the same Moodle site, it is not required. The expert must be able to help the novice without logging in to the novice's site, and by communicating with the novice only by e-mail, messaging, forum posts, etc.. For example, the novice may be a user posting to a moodle.org forum and the expert may be a moodler wanting to be helpful. Even when expert and novice share a physical location and have accounts on the same Moodle site, the expert may not be in a position to give direct help, e.g., by "logging in as" the novice or meeting with the novice. For example, the expert may be a Moodle administrator with an extremely busy schedule.

Here's a typical scenario. Supposed the novice is a teacher who has created a quiz, but is being prevented from previewing the quiz for some unknown reason. The novice reports the problem to moodle.org in a forum post. The expert (a helpful moodler) suspects a roles problem and replies by asking the novice to (1) log in to Moodle, reproduce the problem (2) browse to rolesdebug.php (3) enter two or three parameters as specified by the expert (4) paste the output from rolesdebug.php into a reply to this forum post. The expert reviews the output and (hopefully) diagnoses the problem.

Secondary use cases for rolesdebug.php include
* a user troubleshooting his own problems
* a user troubleshooting another user's problem while logged in as that user

Note that both of these secondary use cases are equivalent, since there is only one actor (the expert), not two. To keep things simple in the remainder of the article, I'll describe the secondary use case, and I'll refer only to YOU. Keeping the primary use case in mind, it should be clear when "you" means roles expert and when it means the roles novice.

==Essential roles and capabilities concepts==

Interpreting the output from rolesdebug.php requires at least a basic understanding of the concepts listed below. If any of these concepts are unfamiliar to you, stop and follow the documentation link.

* [[Assign_roles#Contexts | Context]]
* [[Capabilities | Capability]]
* [[Capabilities | Permission]]
* [[Capabilities | Role]]
* [[Assign_roles | Role assignment]]
* [[Override_permissions | Role override]]
* [[How permissions are calculated]]

==Overview of a script session==

First, you will log in to Moodle and navigate to the context where you're having the problem. Perhaps this is a quiz which Moodle, for some unknown reason, is preventing you from attempting. Then, without logging out of Moodle, point your browser at rolesdebug.php (I find it convenient to open a new browser tab for this). Input the ''context'' you're interested in and (optionally) the name of a ''capability'' to investigate, then press the Go button. The script will return a page with a table presenting a spatial view of the role assignments and overrides that affect you in the specified context. From the table, you will be able to see why Moodle is preventing you from attempting the quiz.

==Using the script==

===STEP1===
This step is done in Moodle (you won't use the script until STEP 2). Login to Moodle and navigate into the context where the problem is occurring. Once you're there, you'll make note of the context id, which is needed in STEP 2. I'll tell you [[#How to determine the context id|how to determine the context id]] later.

Incidentally, even if you know the context id, it is essential that you actually navigate to the context. This is because Moodle loads certain permission data "lazily" -- i.e., only when actually needed. Navigating to the context guarantees that Moodle will have loaded the data. For example, suppose the target context is a certain quiz in some course. You must enter the course and click on the Quiz icon.

However if you are debugging a problem related to a change to a user policy such as Site administration -> Front page -> Front page settings -> Default front page role, you must logout and log back in after making the change.

Do not log out!

===STEP 2===
Open a second browser window. In the window, point your browser at
rolesdebug.php. The script URL will be something like

http://yoursite/moodle/rolesdebug.php

Rolesdebug.php will NOT ask you to login because you are already logged in. The script will ask you for three inputs:

* CAPABILITY. If you're only interested in seeing your role assignments and overrides, you can leave this field empty. If you're interested in analyzing a particular permission, you'll need to enter the capability name. For example, if you're interested in the capability that controls your ability to attempt quizzes, enter [[Capabilities/mod/quiz:attempt | mod/quiz:attempt]].

* CONTEXT TYPE. Choose one of the following from the dropdown menu:
**COURSE
**MODULE
**BLOCK
**COURSECAT
**USER
**SYSTEM

* CONTEXT ID. The context id is a number at the end of the URL of the page you found in STEP 1. See [[#How to determine the context id|How to determine the context id]] below.

Incidentally, MODULE means activity or resource. There is no FRONT PAGE context. If you're interested in the Front page context, choose COURSE and specify a context id of 1.

Here's an example of input:

[[Image:sample_input_quiz_attempt.png|sample input when investigating a quiz attempt]]

===STEP 3===
Press the Go button. Rolesdebug.php will return a page of information. The main item on the page is a table giving a spatial view of all the role assignments and overrides that affect you in the specified context.

==How to read the output==
Let's look at a typical output for the input parameters from the last section.
[[Image:sample_output_quiz_attempt.png|sample output when investigating a quiz attempt]]

The first three lines of output (1) simply echo your input values, and the next two lines (2) remind you of who YOU are, and tell you the actual name of the context you have selected. Check these carefully to make
sure you are who you think you are, and have specified the correct context.

For each of your roles, you will see a line of the form ''alias = role name'' where
* ''role name'' is the actual role name
* ''alias'' is the name used to represent the role in the table

In the example, ''R7 = user'' means the the role user (the shortname of Authorized user) will be represented in the table by the alias R7. Aliases are used because long role names could make the table very wide, forcing you to scroll horizontally. By using aliases, the table will hopefully fit in a window, allowing you to see the entire table in a single a glance.

Next comes the table (4). I'll have a lot more to say about the table below.

If you specified a capability, then you will see the three lines immediately after the table (5).
* The first line gives the calculated permission, which is based on the table. The value can be either A (Allow) or P (Prevent).
* The second line tells you if you are able to "do anything," that is, if you have moodle/site:doanything = Allow (this is typically only true for administrators)
* The third line tells you if you can "do this." If you can do anything, you can obviously do this regardless of the calculated permission.

====How to read the table====

If the target context is N levels deep, the table will have N rows and N columns, one for each context level. The example above has four levels:

System
|
|
Category "A"
|
|
Course "cooking"
|
|
Module "quiz-1"

The column headings give the names of the contexts. These are listed in order of increasing depth: System, A, cooking, quiz-1.

To save space, the table does not have row headings. If it did, they would be the same as the column headings. For example, row 1 would be labeled "System" and row 4 would be labeled "quiz-1".

The first row of the table contains the role assignments made in each context level. In the example, you can see that R7 (Authorized user) is assigned in the System context and R5 (Student) is assigned in the course context. If there are no overrides (as in this example) you will only see entries in row 1.

The letters N and A in parentheses are the values of the capabilities in the role definitions. The possible values are:

N - Not set
A - Allow
P - Prevent
X - Prohibit

"Not set" means that the role doesn't say anything about the capability. In the example, we see that the Student role allows
quiz attempts, while the Authorized user role doesn't have anything
to say about quiz attempts.

If there are role overrides, there will be entries in other rows of the table. Overrides have the same format as the assignments in row 1. An override is shown in the ROW of the context where it is made, and the COLUMN of the assignment that it overrides.

To illustrate, let's override the Student role in the Quiz context, setting mod/quiz:attempt to Prevent, and then rerun rolesdebug.php. Of course before running the script, the student must attempt the quiz. This time, the student should be prevented because of the override. Now we run the script and get the following output:
[[Image:sample_output_quiz_attempt_with_override.png|sample output when investigating a quiz attempt and there is an override]]

Notice the newly added R5(P). This is the override. It is in the fourth row because the override was made in the quiz context, and it is in the course column because the Student role was assigned in the Course context.

The calculated permission is now P, as expected.

====How Moodle calculates the final permission====

By scanning the table in a certain way, you can see how Moodle
arrives at its calculated permission. You can always do this with a quick visual scan, regardless of how many role assignments and overrides the table contains.

For the original example (where we only had role assignments in row 1),
scan row 1 from right to left,
[[Image:sample_output_quiz_attempt_showing_path.png|how to scan the table when investigating a quiz attempt]]

* if there is an X anywhere in the row, the operation is prevented
* otherwise, scan the row from right to left, ignoring N's
* if the first R you hit is an A, the operation is allowed
* if the first R value you hit is P, the operation is prevented
* if a column contains one or more A's AND one or more P's cancel pairs of A-P pairs until either (1) all pairs cancel or (2) you are left with one or more A's or P's. If you are left with A's, the operation is allowed. If you are left with P's, the operation is prevented.
* if your scan takes you all the way to the leftmost column and you still haven't found a conclusive result, the operation is prevented.

When there are overrides, you do the same thing, but your scan follows a different path.
[[Image:sample_output_quiz_attempt_with_override_showing_path.png|how to scan the table when investigating a quiz attempt and there is an override]]

For a complete explanation of how permissions are calculated, read the article [[How permissions are calculated | How permissions are calculated]].

==How to determine the context id==
Here are rules for determining the context id for each context type.
===COURSE===
For a COURSE context, the context id is the course id. You can get the course id from the URL that appears in the address bar when when you're on the course page. For example when I point my browser at the "Features" course on demo.moodle.org, I see this:

[[Image:URI_of_course_in_address_bar.png|URI of course is shown in the address bar]]

The course id, and therefore the context id for this course is 2.

If Moodle won't let you enter the course for some reason, but you can see a link to the course, let your mouse hover over the link as in the following screenshot. Your browser will show you the address at the bottom of the window.

[[Image:URI_of_course_at_bottom_of_browser_window.png|URI of course is shown at the bottom of the browser window]]

The front page of a Moodle site is also a course, but you can't use either of the above tricks to get the id. ''The front page course id is 1.''

===MODULE (activity or resource)===
For a MODULE context, the context id is the activity or resource id. You can get the id from the URL that appears in the address bar when you're viewing the activity or resource, or from the bottom of the browser window when you let your mouse hover over a link. Here are some examples:

http://demo.moodle.org/mod/choice/view.php?id=25
http://demo.moodle.org/mod/forum/view.php?id=28
http://demo.moodle.org/mod/lesson/view.php?id=38
http://demo.moodle.org/mod/quiz/view.php?id=61
http://demo.moodle.org/mod/resource/view.php?id=10
http://demo.moodle.org/mod/resource/view.php?id=48

The context id's for these modules are 25, 28, 38, 61, 10, and 48.

===BLOCK===
For a BLOCK context, the context id is the "instanceid" of the block. To get the instanceid, turn editing on and let the mouse hover over the "eye" icon in the block header. Then take the instanceid from URL that appears in the at the bottom of the window. For example:

http://demo.moodle.org/course/view.php?id=28&instanceid=19...

The context id for this block is 19. Note that for blocks, only a user who can turn editing on can get the instanceid.

===COURSECAT===
For a COURSECAT context, the context id is the category id. You can get the id from the URL that appears in the address bar when you're on the category page. If the site has only one category (usually called "Miscellaneous") the id is 1. If there is more than one category, the easiest way to get the category id for a specific category is to have a Category list or a Combo list on the front page of the site (or a Courses block) and let your mouse hover over one of the links. For example:

http://mysite/course/category.php?id=3

The context id for this category is 3

===USER===
For a USER context, the context id is the user id. You can get the id from the URL that appears in the address bar when you're on a profile page, or from the bottom of the browser window when you let your mouse hover over a user's name. For example:

http://demo.moodle.org/user/view.php?id=6&course=1

The context id for this user is 6

===SYSTEM===
There is only one SYSTEM context. Its id is 1.

[[Category:Contributed code]]

The rolesdebug.php roles debugging script

2008-05-01T12:19:32Z

Jisner: /* How to read the output */

{{Roles}}{{Moodle 1.9}}
Rolesdebug.php is a stand-alone script that is extremely useful for debugging problems related to roles and permissions. The output can be interpreted by anyone with a good understanding of Moodle's [[Roles and capabilities]] system. If you're a "roles novice" and you need help with a roles-related problem, you can ask a roles expert to help you with running the script and interpreting the output. Simply post a request for help to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum].

You can download rolesdebug.php from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and Plugins database]. To install the script, simply drop it into the Moodle root directory or any directory under the root directory.

Rolesdebug.php requires a login, so only someone with a Moodle user account who is currently logged in can use it. Since it is a php script, you will see the output in your browser. No one else will see it unless they're looking over your shoulder. Furthermore, rolesdebug.php gives you information about YOUR permissions. You cannot use it to get information about another user's permissions, unless you can login as them.

Rolesdebug.php returns a table that gives a spatial view of the role assignments and overrides that affect you in a specified context. From the table, you will be able to see how Moodle calculates a specified permission. The table format is explained (and several examples are given) in the article [[How permissions are calculated]].

Rolesdebug.php reads permission data from the Moodle database but does not modify the database in any way. In this respect, it is similar to other debug scripts in the standard distribution, like the [[TeX_notation_filter#Debugging_TeX_filter | TeX notation debugger]].

==The use case for rolesdebug.php==

The main use case for rolesdebug.php is a ''roles expert helping a roles novice troubleshoot a roles-related problem''. A ''roles expert'' is anyone with a basic understanding of the [[#Essential roles and capabilities concepts | essential roles concepts]] listed in the next section. A ''roles novice'' is any Moodle user with the ability to follow simple instructions from the expert. While the expert and novice may occasionally share the same physical location and have accounts on the same Moodle site, it is not required. The expert must be able to help the novice without logging in to the novice's site, and by communicating with the novice only by e-mail, messaging, forum posts, etc.. For example, the novice may be a user posting to a moodle.org forum and the expert may be a moodler wanting to be helpful. Even when expert and novice share a physical location and have accounts on the same Moodle site, the expert may not be in a position to give direct help, e.g., by "logging in as" the novice or meeting with the novice. For example, the expert may be a Moodle administrator with an extremely busy schedule.

Here's a typical scenario. Supposed the novice is a teacher who has created a quiz, but is being prevented from previewing the quiz for some unknown reason. The novice reports the problem to moodle.org in a forum post. The expert (a helpful moodler) suspects a roles problem and replies by asking the novice to (1) log in to Moodle, reproduce the problem (2) browse to rolesdebug.php (3) enter two or three parameters as specified by the expert (4) paste the output from rolesdebug.php into a reply to this forum post. The expert reviews the output and (hopefully) diagnoses the problem.

Secondary use cases for rolesdebug.php include
* a user troubleshooting his own problems
* a user troubleshooting another user's problem while logged in as that user

Note that both of these secondary use cases are equivalent, since there is only one actor (the expert), not two. To keep things simple in the remainder of the article, I'll describe the secondary use case, and I'll refer only to YOU. Keeping the primary use case in mind, it should be clear when "you" means roles expert and when it means the roles novice.

==Essential roles and capabilities concepts==

Interpreting the output from rolesdebug.php requires at least a basic understanding of the concepts listed below. If any of these concepts are unfamiliar to you, stop and follow the documentation link.

* [[Assign_roles#Contexts | Context]]
* [[Capabilities | Capability]]
* [[Capabilities | Permission]]
* [[Capabilities | Role]]
* [[Assign_roles | Role assignment]]
* [[Override_permissions | Role override]]
* [[How permissions are calculated]]

==Overview of a script session==

First, you will log in to Moodle and navigate to the context where you're having the problem. Perhaps this is a quiz which Moodle, for some unknown reason, is preventing you from attempting. Then, without logging out of Moodle, point your browser at rolesdebug.php (I find it convenient to open a new browser tab for this). Input the ''context'' you're interested in and (optionally) the name of a ''capability'' to investigate, then press the Go button. The script will return a page with a table presenting a spatial view of the role assignments and overrides that affect you in the specified context. From the table, you will be able to see why Moodle is preventing you from attempting the quiz.

==Using the script==

===STEP1===
This step is done in Moodle (you won't use the script until STEP 2). Login to Moodle and navigate into the context where the problem is occurring. Once you're there, you'll make note of the context id, which is needed in STEP 2. I'll tell you [[#How to determine the context id|how to determine the context id]] later.

Incidentally, even if you know the context id, it is essential that you actually navigate to the context. This is because Moodle loads certain permission data "lazily" -- i.e., only when actually needed. Navigating to the context guarantees that Moodle will have loaded the data. For example, suppose the target context is a certain quiz in some course. You must enter the course and click on the Quiz icon.

However if you are debugging a problem related to a change to a user policy such as Site administration -> Front page -> Front page settings -> Default front page role, you must logout and log back in after making the change.

Do not log out!

===STEP 2===
Open a second browser window. In the window, point your browser at
rolesdebug.php. The script URL will be something like

http://yoursite/moodle/rolesdebug.php

Rolesdebug.php will NOT ask you to login because you are already logged in. The script will ask you for three inputs:

* CAPABILITY. If you're only interested in seeing your role assignments and overrides, you can leave this field empty. If you're interested in analyzing a particular permission, you'll need to enter the capability name. For example, if you're interested in the capability that controls your ability to attempt quizzes, enter [[Capabilities/mod/quiz:attempt | mod/quiz:attempt]].

* CONTEXT TYPE. Choose one of the following from the dropdown menu:
**COURSE
**MODULE
**BLOCK
**COURSECAT
**USER
**SYSTEM

* CONTEXT ID. The context id is a number at the end of the URL of the page you found in STEP 1. See [[#How to determine the context id|How to determine the context id]] below.

Incidentally, MODULE means activity or resource. There is no FRONT PAGE context. If you're interested in the Front page context, choose COURSE and specify a context id of 1.

Here's an example of input:

[[Image:sample_input_quiz_attempt.png|sample input when investigating a quiz attempt]]

===STEP 3===
Press the Go button. Rolesdebug.php will return a page of information. The main item on the page is a table giving a spatial view of all the role assignments and overrides that affect you in the specified context.

==How to read the output==
Let's look at a typical output for the input parameters from the last section.
[[Image:sample_output_quiz_attempt.png|sample output when investigating a quiz attempt]]

The first three lines of output (1) simply echo your input values, and the next two lines (2) remind you of who YOU are, and tell you the actual name of the context you have selected. Check these carefully to make
sure you are who you think you are, and have specified the correct context.

For each of your roles, you will see a line of the form ''alias = role name'' where
* ''role name'' is the actual role name
* ''alias'' is the name used to represent the role in the table

In the example, ''R7 = user'' means the the role user (the shortname of Authorized user) will be represented in the table by the alias R7. Aliases are used because long role names could make the table very wide, forcing you to scroll horizontally. By using aliases, the table will hopefully fit in a window, allowing you to see the entire table in a single a glance.

Next comes the table (4). I'll have a lot more to say about the table below.

If you specified a capability, then you will see the three lines immediately after the table (5).
* The first line gives the calculated permission, which is based on the table. The value can be either A (Allow) or P (Prevent).
* The second line tells you if you are able to "do anything," that is, if you have moodle/site:doanything = Allow (this is typically only true for administrators)
* The third line tells you if you can "do this." If you can do anything, you can obviously do this regardless of the calculated permission.

====How to read the table====

If the target context is N levels deep, the table will have N rows and N columns, one for each context level. The example above has four levels:

System
|
|
Category "A"
|
|
Course "cooking"
|
|
Module "quiz-1"

The column headings give the names of the contexts. These are listed in order of increasing depth: System, A, cooking, quiz-1.

To save space, the table does not have row headings. If it did, they would be the same as the column headings. For example, row 1 would be labeled "System" and row 4 would be labeled "quiz-1".

The first row of the table contains the role assignments made in each context level. In the example, you can see that R7 (Authorized user) is assigned in the System context and R5 (Student) is assigned in the course context. If there are no overrides (as in this example) you will only see entries in row 1.

The letters N and A in parentheses are the values of the capabilities in the role definitions. The possible values are:

N - Not set
A - Allow
P - Prevent
X - Prohibit

"Not set" means that the role doesn't say anything about the capability. In the example, we see that the Student role allows
quiz attempts, while the Authorized user role doesn't have anything
to say about quiz attempts.

If there are role overrides, there will be entries in other rows of the table. Overrides have the same format as the assignments in row 1. An override is shown in the ROW of the context where it is made, and the COLUMN of the assignment that it overrides.

To illustrate, let's override the Student role in the Quiz context, setting mod/quiz:attempt to Prevent, and then rerun rolesdebug.php. Of course before running the script, the student must attempt the quiz. This time, the student should be prevented because of the override. Now we run the script and get the following output:
[[Image:sample_output_quiz_attempt_with_override.png|sample output when investigating a quiz attempt and there is an override]]

Notice the newly added R5(P). This is the override. It is in the fourth row because the override was made in the quiz context, and it is in the course column because the Student role was assigned in the Course context.

Finally, notice that Moodle now tells us that the calculated permission is "false," exactly as we expect.

====How Moodle calculates the final permission====

By scanning the table in a certain way, you can see how Moodle
arrives at its calculated permission. You can always do this with a quick visual scan, regardless of how many role assignments and overrides the table contains.

For the original example (where we only had role assignments in row 1),
scan row 1 from right to left,
[[Image:sample_output_quiz_attempt_showing_path.png|how to scan the table when investigating a quiz attempt]]

* if there is an X anywhere in the row, the operation is prevented
* otherwise, scan the row from right to left, ignoring N's
* if the first R you hit is an A, the operation is allowed
* if the first R value you hit is P, the operation is prevented
* if a column contains one or more A's AND one or more P's cancel pairs of A-P pairs until either (1) all pairs cancel or (2) you are left with one or more A's or P's. If you are left with A's, the operation is allowed. If you are left with P's, the operation is prevented.
* if your scan takes you all the way to the leftmost column and you still haven't found a conclusive result, the operation is prevented.

When there are overrides, you do the same thing, but your scan follows a different path.
[[Image:sample_output_quiz_attempt_with_override_showing_path.png|how to scan the table when investigating a quiz attempt and there is an override]]

For a complete explanation of how permissions are calculated, read the article [[How permissions are calculated | How permissions are calculated]].

==How to determine the context id==
Here are rules for determining the context id for each context type.
===COURSE===
For a COURSE context, the context id is the course id. You can get the course id from the URL that appears in the address bar when when you're on the course page. For example when I point my browser at the "Features" course on demo.moodle.org, I see this:

[[Image:URI_of_course_in_address_bar.png|URI of course is shown in the address bar]]

The course id, and therefore the context id for this course is 2.

If Moodle won't let you enter the course for some reason, but you can see a link to the course, let your mouse hover over the link as in the following screenshot. Your browser will show you the address at the bottom of the window.

[[Image:URI_of_course_at_bottom_of_browser_window.png|URI of course is shown at the bottom of the browser window]]

The front page of a Moodle site is also a course, but you can't use either of the above tricks to get the id. ''The front page course id is 1.''

===MODULE (activity or resource)===
For a MODULE context, the context id is the activity or resource id. You can get the id from the URL that appears in the address bar when you're viewing the activity or resource, or from the bottom of the browser window when you let your mouse hover over a link. Here are some examples:

http://demo.moodle.org/mod/choice/view.php?id=25
http://demo.moodle.org/mod/forum/view.php?id=28
http://demo.moodle.org/mod/lesson/view.php?id=38
http://demo.moodle.org/mod/quiz/view.php?id=61
http://demo.moodle.org/mod/resource/view.php?id=10
http://demo.moodle.org/mod/resource/view.php?id=48

The context id's for these modules are 25, 28, 38, 61, 10, and 48.

===BLOCK===
For a BLOCK context, the context id is the "instanceid" of the block. To get the instanceid, turn editing on and let the mouse hover over the "eye" icon in the block header. Then take the instanceid from URL that appears in the at the bottom of the window. For example:

http://demo.moodle.org/course/view.php?id=28&instanceid=19...

The context id for this block is 19. Note that for blocks, only a user who can turn editing on can get the instanceid.

===COURSECAT===
For a COURSECAT context, the context id is the category id. You can get the id from the URL that appears in the address bar when you're on the category page. If the site has only one category (usually called "Miscellaneous") the id is 1. If there is more than one category, the easiest way to get the category id for a specific category is to have a Category list or a Combo list on the front page of the site (or a Courses block) and let your mouse hover over one of the links. For example:

http://mysite/course/category.php?id=3

The context id for this category is 3

===USER===
For a USER context, the context id is the user id. You can get the id from the URL that appears in the address bar when you're on a profile page, or from the bottom of the browser window when you let your mouse hover over a user's name. For example:

http://demo.moodle.org/user/view.php?id=6&course=1

The context id for this user is 6

===SYSTEM===
There is only one SYSTEM context. Its id is 1.

[[Category:Contributed code]]

The rolesdebug.php roles debugging script

2008-05-01T11:57:02Z

Jisner: /* STEP1 */

{{Roles}}{{Moodle 1.9}}
Rolesdebug.php is a stand-alone script that is extremely useful for debugging problems related to roles and permissions. The output can be interpreted by anyone with a good understanding of Moodle's [[Roles and capabilities]] system. If you're a "roles novice" and you need help with a roles-related problem, you can ask a roles expert to help you with running the script and interpreting the output. Simply post a request for help to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum].

You can download rolesdebug.php from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and Plugins database]. To install the script, simply drop it into the Moodle root directory or any directory under the root directory.

Rolesdebug.php requires a login, so only someone with a Moodle user account who is currently logged in can use it. Since it is a php script, you will see the output in your browser. No one else will see it unless they're looking over your shoulder. Furthermore, rolesdebug.php gives you information about YOUR permissions. You cannot use it to get information about another user's permissions, unless you can login as them.

Rolesdebug.php returns a table that gives a spatial view of the role assignments and overrides that affect you in a specified context. From the table, you will be able to see how Moodle calculates a specified permission. The table format is explained (and several examples are given) in the article [[How permissions are calculated]].

Rolesdebug.php reads permission data from the Moodle database but does not modify the database in any way. In this respect, it is similar to other debug scripts in the standard distribution, like the [[TeX_notation_filter#Debugging_TeX_filter | TeX notation debugger]].

==The use case for rolesdebug.php==

The main use case for rolesdebug.php is a ''roles expert helping a roles novice troubleshoot a roles-related problem''. A ''roles expert'' is anyone with a basic understanding of the [[#Essential roles and capabilities concepts | essential roles concepts]] listed in the next section. A ''roles novice'' is any Moodle user with the ability to follow simple instructions from the expert. While the expert and novice may occasionally share the same physical location and have accounts on the same Moodle site, it is not required. The expert must be able to help the novice without logging in to the novice's site, and by communicating with the novice only by e-mail, messaging, forum posts, etc.. For example, the novice may be a user posting to a moodle.org forum and the expert may be a moodler wanting to be helpful. Even when expert and novice share a physical location and have accounts on the same Moodle site, the expert may not be in a position to give direct help, e.g., by "logging in as" the novice or meeting with the novice. For example, the expert may be a Moodle administrator with an extremely busy schedule.

Here's a typical scenario. Supposed the novice is a teacher who has created a quiz, but is being prevented from previewing the quiz for some unknown reason. The novice reports the problem to moodle.org in a forum post. The expert (a helpful moodler) suspects a roles problem and replies by asking the novice to (1) log in to Moodle, reproduce the problem (2) browse to rolesdebug.php (3) enter two or three parameters as specified by the expert (4) paste the output from rolesdebug.php into a reply to this forum post. The expert reviews the output and (hopefully) diagnoses the problem.

Secondary use cases for rolesdebug.php include
* a user troubleshooting his own problems
* a user troubleshooting another user's problem while logged in as that user

Note that both of these secondary use cases are equivalent, since there is only one actor (the expert), not two. To keep things simple in the remainder of the article, I'll describe the secondary use case, and I'll refer only to YOU. Keeping the primary use case in mind, it should be clear when "you" means roles expert and when it means the roles novice.

==Essential roles and capabilities concepts==

Interpreting the output from rolesdebug.php requires at least a basic understanding of the concepts listed below. If any of these concepts are unfamiliar to you, stop and follow the documentation link.

* [[Assign_roles#Contexts | Context]]
* [[Capabilities | Capability]]
* [[Capabilities | Permission]]
* [[Capabilities | Role]]
* [[Assign_roles | Role assignment]]
* [[Override_permissions | Role override]]
* [[How permissions are calculated]]

==Overview of a script session==

First, you will log in to Moodle and navigate to the context where you're having the problem. Perhaps this is a quiz which Moodle, for some unknown reason, is preventing you from attempting. Then, without logging out of Moodle, point your browser at rolesdebug.php (I find it convenient to open a new browser tab for this). Input the ''context'' you're interested in and (optionally) the name of a ''capability'' to investigate, then press the Go button. The script will return a page with a table presenting a spatial view of the role assignments and overrides that affect you in the specified context. From the table, you will be able to see why Moodle is preventing you from attempting the quiz.

==Using the script==

===STEP1===
This step is done in Moodle (you won't use the script until STEP 2). Login to Moodle and navigate into the context where the problem is occurring. Once you're there, you'll make note of the context id, which is needed in STEP 2. I'll tell you [[#How to determine the context id|how to determine the context id]] later.

Incidentally, even if you know the context id, it is essential that you actually navigate to the context. This is because Moodle loads certain permission data "lazily" -- i.e., only when actually needed. Navigating to the context guarantees that Moodle will have loaded the data. For example, suppose the target context is a certain quiz in some course. You must enter the course and click on the Quiz icon.

However if you are debugging a problem related to a change to a user policy such as Site administration -> Front page -> Front page settings -> Default front page role, you must logout and log back in after making the change.

Do not log out!

===STEP 2===
Open a second browser window. In the window, point your browser at
rolesdebug.php. The script URL will be something like

http://yoursite/moodle/rolesdebug.php

Rolesdebug.php will NOT ask you to login because you are already logged in. The script will ask you for three inputs:

* CAPABILITY. If you're only interested in seeing your role assignments and overrides, you can leave this field empty. If you're interested in analyzing a particular permission, you'll need to enter the capability name. For example, if you're interested in the capability that controls your ability to attempt quizzes, enter [[Capabilities/mod/quiz:attempt | mod/quiz:attempt]].

* CONTEXT TYPE. Choose one of the following from the dropdown menu:
**COURSE
**MODULE
**BLOCK
**COURSECAT
**USER
**SYSTEM

* CONTEXT ID. The context id is a number at the end of the URL of the page you found in STEP 1. See [[#How to determine the context id|How to determine the context id]] below.

Incidentally, MODULE means activity or resource. There is no FRONT PAGE context. If you're interested in the Front page context, choose COURSE and specify a context id of 1.

Here's an example of input:

[[Image:sample_input_quiz_attempt.png|sample input when investigating a quiz attempt]]

===STEP 3===
Press the Go button. Rolesdebug.php will return a page of information. The main item on the page is a table giving a spatial view of all the role assignments and overrides that affect you in the specified context.

==How to read the output==
Let's look at a typical output for the input parameters from the last section.
[[Image:sample_output_quiz_attempt.png|sample output when investigating a quiz attempt]]

The first three lines of output (1) simply echo your input values, and the next two lines (2) remind you of who YOU are, and tell you the actual name of the context you have selected. Check these carefully to make
sure you are who you think you are, and have specified the correct context.

For each of your roles, you will see a line of the form ''alias = role name'' where
* ''role name'' is the actual role name
* ''alias'' is the name used to represent the role in the table

In the example, ''R7 = user'' means the the role user (the shortname of Authorized user) will be represented in the table by the alias R7. Aliases are used because long role names could make the table very wide, forcing you to scroll horizontally. By using aliases, the table will hopefully fit in a window, allowing you to see the entire table in a single a glance.

Next comes the table (4). I'll have a lot more to say about the table below.

If you specified a capability, then below the table, you'll see the
value of the permission that Moodle calculated (5). "True" means you are allowed to perform the action and "False" means that you are prevented from performing the action.

====How to read the table====

If the target context is N levels deep, the table will have N rows and N columns, one for each context level. The example above has four levels:

System
|
|
Category "A"
|
|
Course "cooking"
|
|
Module "quiz-1"

The column headings give the names of the contexts. These are listed in order of increasing depth: System, A, cooking, quiz-1.

To save space, the table does not have row headings. If it did, they would be the same as the column headings. For example, row 1 would be labeled "System" and row 4 would be labeled "quiz-1".

The first row of the table contains the role assignments made in each context level. In the example, you can see that R7 (Authorized user) is assigned in the System context and R5 (Student) is assigned in the course context. If there are no overrides (as in this example) you will only see entries in row 1.

The letters N and A in parentheses are the values of the capabilities in the role definitions. The possible values are:

N - Not set
A - Allow
P - Prevent
X - Prohibit

"Not set" means that the role doesn't say anything about the capability. In the example, we see that the Student role allows
quiz attempts, while the Authorized user role doesn't have anything
to say about quiz attempts.

If there are role overrides, there will be entries in other rows of the table. Overrides have the same format as the assignments in row 1. An override is shown in the ROW of the context where it is made, and the COLUMN of the assignment that it overrides.

To illustrate, let's override the Student role in the Quiz context, setting mod/quiz:attempt to Prevent, and then rerun rolesdebug.php. Of course before running the script, the student must attempt the quiz. This time, the student should be prevented because of the override. Now we run the script and get the following output:
[[Image:sample_output_quiz_attempt_with_override.png|sample output when investigating a quiz attempt and there is an override]]

Notice the newly added R5(P). This is the override. It is in the fourth row because the override was made in the quiz context, and it is in the course column because the Student role was assigned in the Course context.

Finally, notice that Moodle now tells us that the calculated permission is "false," exactly as we expect.

====How Moodle calculates the final permission====

By scanning the table in a certain way, you can see how Moodle
arrives at its calculated permission. You can always do this with a quick visual scan, regardless of how many role assignments and overrides the table contains.

For the original example (where we only had role assignments in row 1),
scan row 1 from right to left,
[[Image:sample_output_quiz_attempt_showing_path.png|how to scan the table when investigating a quiz attempt]]

* if there is an X anywhere in the row, the operation is prevented
* otherwise, scan the row from right to left, ignoring N's
* if the first R you hit is an A, the operation is allowed
* if the first R value you hit is P, the operation is prevented
* if a column contains one or more A's AND one or more P's cancel pairs of A-P pairs until either (1) all pairs cancel or (2) you are left with one or more A's or P's. If you are left with A's, the operation is allowed. If you are left with P's, the operation is prevented.
* if your scan takes you all the way to the leftmost column and you still haven't found a conclusive result, the operation is prevented.

When there are overrides, you do the same thing, but your scan follows a different path.
[[Image:sample_output_quiz_attempt_with_override_showing_path.png|how to scan the table when investigating a quiz attempt and there is an override]]

For a complete explanation of how permissions are calculated, read the article [[How permissions are calculated | How permissions are calculated]].

==How to determine the context id==
Here are rules for determining the context id for each context type.
===COURSE===
For a COURSE context, the context id is the course id. You can get the course id from the URL that appears in the address bar when when you're on the course page. For example when I point my browser at the "Features" course on demo.moodle.org, I see this:

[[Image:URI_of_course_in_address_bar.png|URI of course is shown in the address bar]]

The course id, and therefore the context id for this course is 2.

If Moodle won't let you enter the course for some reason, but you can see a link to the course, let your mouse hover over the link as in the following screenshot. Your browser will show you the address at the bottom of the window.

[[Image:URI_of_course_at_bottom_of_browser_window.png|URI of course is shown at the bottom of the browser window]]

The front page of a Moodle site is also a course, but you can't use either of the above tricks to get the id. ''The front page course id is 1.''

===MODULE (activity or resource)===
For a MODULE context, the context id is the activity or resource id. You can get the id from the URL that appears in the address bar when you're viewing the activity or resource, or from the bottom of the browser window when you let your mouse hover over a link. Here are some examples:

http://demo.moodle.org/mod/choice/view.php?id=25
http://demo.moodle.org/mod/forum/view.php?id=28
http://demo.moodle.org/mod/lesson/view.php?id=38
http://demo.moodle.org/mod/quiz/view.php?id=61
http://demo.moodle.org/mod/resource/view.php?id=10
http://demo.moodle.org/mod/resource/view.php?id=48

The context id's for these modules are 25, 28, 38, 61, 10, and 48.

===BLOCK===
For a BLOCK context, the context id is the "instanceid" of the block. To get the instanceid, turn editing on and let the mouse hover over the "eye" icon in the block header. Then take the instanceid from URL that appears in the at the bottom of the window. For example:

http://demo.moodle.org/course/view.php?id=28&instanceid=19...

The context id for this block is 19. Note that for blocks, only a user who can turn editing on can get the instanceid.

===COURSECAT===
For a COURSECAT context, the context id is the category id. You can get the id from the URL that appears in the address bar when you're on the category page. If the site has only one category (usually called "Miscellaneous") the id is 1. If there is more than one category, the easiest way to get the category id for a specific category is to have a Category list or a Combo list on the front page of the site (or a Courses block) and let your mouse hover over one of the links. For example:

http://mysite/course/category.php?id=3

The context id for this category is 3

===USER===
For a USER context, the context id is the user id. You can get the id from the URL that appears in the address bar when you're on a profile page, or from the bottom of the browser window when you let your mouse hover over a user's name. For example:

http://demo.moodle.org/user/view.php?id=6&course=1

The context id for this user is 6

===SYSTEM===
There is only one SYSTEM context. Its id is 1.

[[Category:Contributed code]]

The rolesdebug.php roles debugging script

2008-05-01T11:55:14Z

Jisner: /* STEP1 */

{{Roles}}{{Moodle 1.9}}
Rolesdebug.php is a stand-alone script that is extremely useful for debugging problems related to roles and permissions. The output can be interpreted by anyone with a good understanding of Moodle's [[Roles and capabilities]] system. If you're a "roles novice" and you need help with a roles-related problem, you can ask a roles expert to help you with running the script and interpreting the output. Simply post a request for help to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum].

You can download rolesdebug.php from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and Plugins database]. To install the script, simply drop it into the Moodle root directory or any directory under the root directory.

Rolesdebug.php requires a login, so only someone with a Moodle user account who is currently logged in can use it. Since it is a php script, you will see the output in your browser. No one else will see it unless they're looking over your shoulder. Furthermore, rolesdebug.php gives you information about YOUR permissions. You cannot use it to get information about another user's permissions, unless you can login as them.

Rolesdebug.php returns a table that gives a spatial view of the role assignments and overrides that affect you in a specified context. From the table, you will be able to see how Moodle calculates a specified permission. The table format is explained (and several examples are given) in the article [[How permissions are calculated]].

Rolesdebug.php reads permission data from the Moodle database but does not modify the database in any way. In this respect, it is similar to other debug scripts in the standard distribution, like the [[TeX_notation_filter#Debugging_TeX_filter | TeX notation debugger]].

==The use case for rolesdebug.php==

The main use case for rolesdebug.php is a ''roles expert helping a roles novice troubleshoot a roles-related problem''. A ''roles expert'' is anyone with a basic understanding of the [[#Essential roles and capabilities concepts | essential roles concepts]] listed in the next section. A ''roles novice'' is any Moodle user with the ability to follow simple instructions from the expert. While the expert and novice may occasionally share the same physical location and have accounts on the same Moodle site, it is not required. The expert must be able to help the novice without logging in to the novice's site, and by communicating with the novice only by e-mail, messaging, forum posts, etc.. For example, the novice may be a user posting to a moodle.org forum and the expert may be a moodler wanting to be helpful. Even when expert and novice share a physical location and have accounts on the same Moodle site, the expert may not be in a position to give direct help, e.g., by "logging in as" the novice or meeting with the novice. For example, the expert may be a Moodle administrator with an extremely busy schedule.

Here's a typical scenario. Supposed the novice is a teacher who has created a quiz, but is being prevented from previewing the quiz for some unknown reason. The novice reports the problem to moodle.org in a forum post. The expert (a helpful moodler) suspects a roles problem and replies by asking the novice to (1) log in to Moodle, reproduce the problem (2) browse to rolesdebug.php (3) enter two or three parameters as specified by the expert (4) paste the output from rolesdebug.php into a reply to this forum post. The expert reviews the output and (hopefully) diagnoses the problem.

Secondary use cases for rolesdebug.php include
* a user troubleshooting his own problems
* a user troubleshooting another user's problem while logged in as that user

Note that both of these secondary use cases are equivalent, since there is only one actor (the expert), not two. To keep things simple in the remainder of the article, I'll describe the secondary use case, and I'll refer only to YOU. Keeping the primary use case in mind, it should be clear when "you" means roles expert and when it means the roles novice.

==Essential roles and capabilities concepts==

Interpreting the output from rolesdebug.php requires at least a basic understanding of the concepts listed below. If any of these concepts are unfamiliar to you, stop and follow the documentation link.

* [[Assign_roles#Contexts | Context]]
* [[Capabilities | Capability]]
* [[Capabilities | Permission]]
* [[Capabilities | Role]]
* [[Assign_roles | Role assignment]]
* [[Override_permissions | Role override]]
* [[How permissions are calculated]]

==Overview of a script session==

First, you will log in to Moodle and navigate to the context where you're having the problem. Perhaps this is a quiz which Moodle, for some unknown reason, is preventing you from attempting. Then, without logging out of Moodle, point your browser at rolesdebug.php (I find it convenient to open a new browser tab for this). Input the ''context'' you're interested in and (optionally) the name of a ''capability'' to investigate, then press the Go button. The script will return a page with a table presenting a spatial view of the role assignments and overrides that affect you in the specified context. From the table, you will be able to see why Moodle is preventing you from attempting the quiz.

==Using the script==

===STEP1===
This step is done in Moodle (you won't use the script until STEP 2). Login to Moodle and navigate into the context where the problem is occurring. Once you're there, you'll make note of the context id, which is needed in STEP 2. I'll tell you [[#How to determine the context id|how to determine the context id]] later.

Incidentally, even if you know the context id, it is essential that you actually navigate to the context. This is because Moodle loads certain permission data "lazily" -- i.e., only when actually needed. Navigating to the context guarantees that Moodle will have loaded the data.

For example, suppose the target context is a certain quiz in some course. You must enter the course and click on the Quiz icon.

If you are debugging a problem related to a change to a user policy such as Site administration -> Front page -> Front page settings -> Default front page role, you must logout and log back in prior to STEP 1.

Remain logged in for the next step!

===STEP 2===
Open a second browser window. In the window, point your browser at
rolesdebug.php. The script URL will be something like

http://yoursite/moodle/rolesdebug.php

Rolesdebug.php will NOT ask you to login because you are already logged in. The script will ask you for three inputs:

* CAPABILITY. If you're only interested in seeing your role assignments and overrides, you can leave this field empty. If you're interested in analyzing a particular permission, you'll need to enter the capability name. For example, if you're interested in the capability that controls your ability to attempt quizzes, enter [[Capabilities/mod/quiz:attempt | mod/quiz:attempt]].

* CONTEXT TYPE. Choose one of the following from the dropdown menu:
**COURSE
**MODULE
**BLOCK
**COURSECAT
**USER
**SYSTEM

* CONTEXT ID. The context id is a number at the end of the URL of the page you found in STEP 1. See [[#How to determine the context id|How to determine the context id]] below.

Incidentally, MODULE means activity or resource. There is no FRONT PAGE context. If you're interested in the Front page context, choose COURSE and specify a context id of 1.

Here's an example of input:

[[Image:sample_input_quiz_attempt.png|sample input when investigating a quiz attempt]]

===STEP 3===
Press the Go button. Rolesdebug.php will return a page of information. The main item on the page is a table giving a spatial view of all the role assignments and overrides that affect you in the specified context.

==How to read the output==
Let's look at a typical output for the input parameters from the last section.
[[Image:sample_output_quiz_attempt.png|sample output when investigating a quiz attempt]]

The first three lines of output (1) simply echo your input values, and the next two lines (2) remind you of who YOU are, and tell you the actual name of the context you have selected. Check these carefully to make
sure you are who you think you are, and have specified the correct context.

For each of your roles, you will see a line of the form ''alias = role name'' where
* ''role name'' is the actual role name
* ''alias'' is the name used to represent the role in the table

In the example, ''R7 = user'' means the the role user (the shortname of Authorized user) will be represented in the table by the alias R7. Aliases are used because long role names could make the table very wide, forcing you to scroll horizontally. By using aliases, the table will hopefully fit in a window, allowing you to see the entire table in a single a glance.

Next comes the table (4). I'll have a lot more to say about the table below.

If you specified a capability, then below the table, you'll see the
value of the permission that Moodle calculated (5). "True" means you are allowed to perform the action and "False" means that you are prevented from performing the action.

====How to read the table====

If the target context is N levels deep, the table will have N rows and N columns, one for each context level. The example above has four levels:

System
|
|
Category "A"
|
|
Course "cooking"
|
|
Module "quiz-1"

The column headings give the names of the contexts. These are listed in order of increasing depth: System, A, cooking, quiz-1.

To save space, the table does not have row headings. If it did, they would be the same as the column headings. For example, row 1 would be labeled "System" and row 4 would be labeled "quiz-1".

The first row of the table contains the role assignments made in each context level. In the example, you can see that R7 (Authorized user) is assigned in the System context and R5 (Student) is assigned in the course context. If there are no overrides (as in this example) you will only see entries in row 1.

The letters N and A in parentheses are the values of the capabilities in the role definitions. The possible values are:

N - Not set
A - Allow
P - Prevent
X - Prohibit

"Not set" means that the role doesn't say anything about the capability. In the example, we see that the Student role allows
quiz attempts, while the Authorized user role doesn't have anything
to say about quiz attempts.

If there are role overrides, there will be entries in other rows of the table. Overrides have the same format as the assignments in row 1. An override is shown in the ROW of the context where it is made, and the COLUMN of the assignment that it overrides.

To illustrate, let's override the Student role in the Quiz context, setting mod/quiz:attempt to Prevent, and then rerun rolesdebug.php. Of course before running the script, the student must attempt the quiz. This time, the student should be prevented because of the override. Now we run the script and get the following output:
[[Image:sample_output_quiz_attempt_with_override.png|sample output when investigating a quiz attempt and there is an override]]

Notice the newly added R5(P). This is the override. It is in the fourth row because the override was made in the quiz context, and it is in the course column because the Student role was assigned in the Course context.

Finally, notice that Moodle now tells us that the calculated permission is "false," exactly as we expect.

====How Moodle calculates the final permission====

By scanning the table in a certain way, you can see how Moodle
arrives at its calculated permission. You can always do this with a quick visual scan, regardless of how many role assignments and overrides the table contains.

For the original example (where we only had role assignments in row 1),
scan row 1 from right to left,
[[Image:sample_output_quiz_attempt_showing_path.png|how to scan the table when investigating a quiz attempt]]

* if there is an X anywhere in the row, the operation is prevented
* otherwise, scan the row from right to left, ignoring N's
* if the first R you hit is an A, the operation is allowed
* if the first R value you hit is P, the operation is prevented
* if a column contains one or more A's AND one or more P's cancel pairs of A-P pairs until either (1) all pairs cancel or (2) you are left with one or more A's or P's. If you are left with A's, the operation is allowed. If you are left with P's, the operation is prevented.
* if your scan takes you all the way to the leftmost column and you still haven't found a conclusive result, the operation is prevented.

When there are overrides, you do the same thing, but your scan follows a different path.
[[Image:sample_output_quiz_attempt_with_override_showing_path.png|how to scan the table when investigating a quiz attempt and there is an override]]

For a complete explanation of how permissions are calculated, read the article [[How permissions are calculated | How permissions are calculated]].

==How to determine the context id==
Here are rules for determining the context id for each context type.
===COURSE===
For a COURSE context, the context id is the course id. You can get the course id from the URL that appears in the address bar when when you're on the course page. For example when I point my browser at the "Features" course on demo.moodle.org, I see this:

[[Image:URI_of_course_in_address_bar.png|URI of course is shown in the address bar]]

The course id, and therefore the context id for this course is 2.

If Moodle won't let you enter the course for some reason, but you can see a link to the course, let your mouse hover over the link as in the following screenshot. Your browser will show you the address at the bottom of the window.

[[Image:URI_of_course_at_bottom_of_browser_window.png|URI of course is shown at the bottom of the browser window]]

The front page of a Moodle site is also a course, but you can't use either of the above tricks to get the id. ''The front page course id is 1.''

===MODULE (activity or resource)===
For a MODULE context, the context id is the activity or resource id. You can get the id from the URL that appears in the address bar when you're viewing the activity or resource, or from the bottom of the browser window when you let your mouse hover over a link. Here are some examples:

http://demo.moodle.org/mod/choice/view.php?id=25
http://demo.moodle.org/mod/forum/view.php?id=28
http://demo.moodle.org/mod/lesson/view.php?id=38
http://demo.moodle.org/mod/quiz/view.php?id=61
http://demo.moodle.org/mod/resource/view.php?id=10
http://demo.moodle.org/mod/resource/view.php?id=48

The context id's for these modules are 25, 28, 38, 61, 10, and 48.

===BLOCK===
For a BLOCK context, the context id is the "instanceid" of the block. To get the instanceid, turn editing on and let the mouse hover over the "eye" icon in the block header. Then take the instanceid from URL that appears in the at the bottom of the window. For example:

http://demo.moodle.org/course/view.php?id=28&instanceid=19...

The context id for this block is 19. Note that for blocks, only a user who can turn editing on can get the instanceid.

===COURSECAT===
For a COURSECAT context, the context id is the category id. You can get the id from the URL that appears in the address bar when you're on the category page. If the site has only one category (usually called "Miscellaneous") the id is 1. If there is more than one category, the easiest way to get the category id for a specific category is to have a Category list or a Combo list on the front page of the site (or a Courses block) and let your mouse hover over one of the links. For example:

http://mysite/course/category.php?id=3

The context id for this category is 3

===USER===
For a USER context, the context id is the user id. You can get the id from the URL that appears in the address bar when you're on a profile page, or from the bottom of the browser window when you let your mouse hover over a user's name. For example:

http://demo.moodle.org/user/view.php?id=6&course=1

The context id for this user is 6

===SYSTEM===
There is only one SYSTEM context. Its id is 1.

[[Category:Contributed code]]

How permissions are calculated

2008-04-27T03:42:49Z

Jisner:

{{Roles}}
One of the most frequently asked question is: ''What are my permissions in this context?'' This article will document the function that Moodle uses to answer this question. The article is written for non-programmers as well as programmers, since it describes ''what'' the function does, not ''how''. The ''how'' is very complicated. The ''what'' turns out to be relatively simple! If you insist on reading the code, the function is named ''has_capability()'' and can be found in ''lib/accesslib.php''.

Given a user, a capability, and a context, ''has_capability()'' returns ''true'' if the user is allowed to perform the action controlled by the capability in the given context, and ''false'' otherwise. In calculating the permission, the function considers all of the relevant permission data, which include role definitions, assignments, and overrides.

Moodle never calculates a user's complete set of permissions. It would be very costly to do so and also wasteful, since most of those permissions would never be tested. Instead, Moodle calculates permissions only as needed. It does not store the permissions that it calculates, but recalculates them every time it needs to test them. This is why role assignments and overrides no longer have delayed effects, as they did in Moodle 1.7 and 1.8.

You can generate tables like the ones in this article using [[The rolesdebug.php roles debugging script]]. The tables are very helpful in debugging roles-related problems.

==The calculation==

The function is called as follows:

has_capability(CAP,CONTEXT,USER);

where
*CAP is the capability being tested (e.g., mod/quiz:attempt)
*CONTEXT can be System context or some context nested arbitrarily deeply within System. Internally, the function uses Unix-style paths to represent contexts (e.g., /1/3/4/150), but such details do not concern us here
*USER is the user.

The function returns a true/false result

* ''true'' means the user should be allowed to perform the action
* ''false'' means the user should be prevented from perfoming the action

===Data used by the function===

Suppose USER is about to attempt a quiz (''CAP = mod/quiz:attempt'') in a Module context nested four levels deep within System.

System
|
Category A
|
Subcategory B
|
Course
|
Quiz <--- the user is here

The quiz module will call ''has_capability()'' to see if the user should be allowed to perform this action.

The function considers the following permissions data:

* ''Role definitions'' (these are in the System context)
* ''Role assignments'' which have been made in any of the five contexts
* ''Role overrides'' which may occur in any of the contexts except System (there is no concept of override in System).

Note that there may be multiple assignments and/or overrides in any single context.

Whether or not the user can attempt the quiz is a function of the permissions data, as well as the location of the data in the context chain.

''has_capability()'' considers all roles and overrides that impact USER in CONTEXT, but it ignores capabilities other than CAP. This simplification lets us view each role or override as a ''single permission'' having one of the following values

N - Not set
A - Allow
P - Prevent
X - Prohibit

We use the following notation: for a role ''R1'' with permission ''P'', we write ''R1(P)''.

===An example===

In the quiz example, suppose that the user has four roles (''R1'', ''R2'', ''R3'', and ''R4'') and each of the roles has been assigned and overridden as follows:

0 System <---- define R1(A), R2(N), R3(N), R4(P)
| assign R1
|
1 Category A <-------------- overide R1(N) and R4(N)
|
|
2 Subcategory B <---- assign R2 and R3
|
|
3 Course <-------------- override R2(X) and R3(A)
|
|
4 Quiz <---- assign R4 and R1

Note that ''R1'' has been assigned in two different contexts. This is an unusual practice (it is probably someone's error), but since it is legal, we have to consider the possibility that it can happen. In fact this entire example has been contrived to explore the edge cases of the algorithm. In practice, the calculation of permissions is trivial and the function calculates the result you would expect based on common sense and simple mental analysis (for further discussion of this, see [[#A note about the algorithm|A note about the algorithm]] near the end of this article.

===Representing the data in tabular form===

We will set up a table to hold the permission data. The table has
*a column for each context, ordered from highest level (System) to lowest (the context where we want to compute the permission).
*a row for each context, also listed from highest to lowest.

[[Image:Calculation-3A.png|Empty table]]

The role definitions go in the first row. Put each definition in the column(s) coresponding to the context(s) in which the role is assigned:

[[Image:Calculation-5A.png|Table with assignments added]]

The overrides go in the remaining rows. Each override goes
*in the same column as the role being overridden
*in the row corresponding the context in which the override is made.

To illustrate, let's add just one of the overrides:

[[Image:Calculation-6A.png|Table with just one override]]

R2(X) represents the override to role R2 made in the course context. Let's add the rest of the overrides:

[[Image:Calculation-7A.png|Table with remaining overrides shown]]

The table is now fully populated, and we are ready to calculate the permission.

===The algorithm===

The algorithm follows a path through the table indicated by nodes and arrows in the diagram below and stops as soon as it has a conclusive result.

[[Image:Algorithm_path_through_permission_table_A.png|Algorithm path through permissions data]]

# If there is an X anywhere in the table, STOP. The calculated permission is ''X''
# Go to the START node
# If there is no next node, STOP. The calculated permission is ''P''
# Otherwise, follow the arrow to the next node
#Add the permissions in the node using the numerical equivalents: N = 0, A = +1, P = -1
#* If the sum is positive, STOP. The calculated permission is ''A''
#* If the sum is negative, STOP. The calculated permission is ''P''
#* If the sum is zero, GO TO step 3

Notice that the algorithm stops when either (1) a conclusive result is obtained, or (2) the algorithm reaches the last node without a conclusive result.

===Applying the algorithm to our example===

If we execute the algorithm with the quiz data, we stop at step 1 with a calculated permission of X. That's not very interesting, so let's change the X to a P and see what happens:

[[Image:Calculation-8A.png|Change X to P in permission table]]

Run the algorithm:

*There is No X in the table
*Go to the START node
*Go to the next node
*N + N = 0
*the sum is zero; go to the next node
*A + P = 0
*the sum is zero; go to the next node
*P + A = 0
*the sum is zero; go to the next node
*A + P = 0
*the sum is zero; go to the next node
*N = 0
*the sum is zero; go to the next node
*A = +1
*the sum is positive; STOP. The calculated permission is ''A''

If the calculated permission is ''A'', ''has_capability()'' returns ''true'', and the user is allowed to perform the action.

Had the calculated permission been ''P'' or ''X'', ''has_capability()'' would not immediately return ''false''. Rather, it would test if the user has ''moodle/site:doanything = Allow'' (since this permission trumps all others). The function does this by calling itself:

final result = has_capability(moodle/site:doanything,CONTEXT, USER);

==A note about the algorithm==

Earlier, we said that the algorithm "calculates the result you would expect." But what do we expect? Intuition tells us that permissions closer to the user should carry more weight than more distant permissions. That's why we set up the table the way we did and why the algorithm walks the table in the order that it does. The last column of the table represents the role assignment(s) closest to the user. The second-to-last column represents the role assignent(s) that are next in terms of distance from the user, and so-on. That's why the algorithm considers the columns from right-to-left. Within a column, the algorithm searches upward in order to give higher weight to overrides that are closer to the user. Once again, this matches our intuition about overrides. If there are no overrides in a column (or the overrides are all Not set), the permission in the role definition is used.

==Getting the result you expect==

The calculation is more likely to give "the result you would expect" if you keep your permissions as simple as possible. Therefore, we recommend the following 'rules' for defining and overriding roles. If you understand the description of the calculation above, you should understand why they make sense.

===When defining roles===

... use Allow (A) for things you want the role to be able to do, and use Not set (N) for things you don't care about (which should include most things).

===When overriding permissions===

... leave the permission for every capability as Inherit (N) apart from the few you want to change. For those, use Allow (A) for things you want to allow, and Prevent (P) for things you want to prevent.

===Only use prohibit in special roles===

Prohibit exists to cover extreme scenarios such as the following: Suppose you have a naughty student who is posting inappropriate content in your Moodle site. You need to be able to remove their ability to contribute to public discussions until they have promised not to do it again, but during that time, you cannot completely block them from the resources, quizzes, etc. because they must keep up with their studying. Therefore, you need a way to block their access to specific capabilities e.g. mod/forum:replypost in a way that cannot be overridden. You can do this by creating a special 'Naughty student' role defined with the required permission(s) set to prohibit. Then when you are having problems with a user, you can temporarily assign them this role, either at site level or at course level.

==A practical example==

Suppose that a user, who is assigned the role of Course creator in category B, creates a course (becoming Teacher in the course) and then creates a Lesson within the course. The user is about to edit the lesson (editing lessons is controlled by capability ''mod/lesson:edit''). Here is the permission data:

0 System <---- define Auth user(N), Creator(N), Teacher(A)
| assign Auth user
|
1 Category A
|
|
2 Subcategory B <---- assign Creator
|
|
3 Course <---- assign Teacher
|
|
4 Lesson <---- user attempts to edit lesson

We set up the table and populate it with permission data.

[[Image:Calculation-10A.png|A practical example]]

Since there are no overrides, the table only has data in the first row. The algorithm quickly calculates a permission of ''A'' and returns true. The user is allowed to edit the Lesson!

Now suppose Teacher is overridden in the Lesson context with ''mod/lesson:edit = P''. Then the table changes

[[Image:Calculation-11A.png|A practical example with first override]]

and clearly the user is no longer allowed to edit the Lesson.

But suppose the administrator (or whoever is making the overrides) decided instead to override the ''Creator role'', setting ''mod/lesson:edit = Prevent'' in the Categoy B context:

[[Image:Calculation-12A.png|A practical example with second override]]

Much to everyone's surprise, the user is still allowed to edit the Lesson! If you understood this article, you shouldn't be surprised, and you should be able to explain what happened.

==See also==

*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=90140 Logged in: what role am I?] and [http://moodle.org/mod/forum/discuss.php?d=66782 What happens if a user has multiple roles in a course?] forum discussions.

There is a script that you can use to create tables like the ones in this article. It is very useful for debugging roles-related problems. See [[The rolesdebug.php roles debugging script]].

[[Category:Roles]]

[[fr:Comment les permissions sont calculées ?]]

How permissions are calculated

2008-04-27T03:36:29Z

Jisner:

{{Roles}}
One of the most frequently asked question is: ''What permissions do I have in this context?'' This article will document the function that Moodle uses to answer this question. The article is written for non-programmers as well as programmers, since it describes ''what'' the function does, not ''how''. The ''how'' is complicated. The ''what'' turns out to be relatively simple! In case you want to look it up, the function is named ''has_capability()'' and can be found in ''lib/accesslib.php''.

Given a user, a capability, and a context, the function returns ''true'' if the user is allowed to perform the action controlled by the capability in the given context, and ''false'' otherwise. In calculating the permission, the function considers all of the relevant permission data, which include role definitions, assignments, and overrides.

Notice that the function does not actually answer the big question posed in the first sentence of this article. Moodle never calculates a user's complete set of permissions. It would be very costly to do so and also wasteful, since most of the permissions would never be tested. Instead, Moodle calculates permissions ''as needed''. Moodle does not store the permissions that it calculates, but recalculates them every time it needs to test them. This is why role assignments and overrides no longer have delayed effects, as they did in Moodle 1.7 and 1.8.

You can generate tables like the ones in this article using [[The rolesdebug.php roles debugging script]]. The tables are very helpful in debugging roles-related problems.

==The calculation==

The function is called as follows:

has_capability(CAP,CONTEXT,USER);

where
*CAP is the capability being tested (e.g., mod/quiz:attempt)
*CONTEXT can be System context or some context nested arbitrarily deeply within System. Internally, the function uses Unix-style paths to represent contexts (e.g., /1/3/4/150), but such details do not concern us here
*USER is the user.

The function returns a true/false result

* ''true'' means the user should be allowed to perform the action
* ''false'' means the user should be prevented from perfoming the action

===Data used by the function===

Suppose USER is about to attempt a quiz (''CAP = mod/quiz:attempt'') in a Module context nested four levels deep within System.

System
|
Category A
|
Subcategory B
|
Course
|
Quiz <--- the user is here

The quiz module will call ''has_capability()'' to see if the user should be allowed to perform this action.

The function considers the following permissions data:

* ''Role definitions'' (these are in the System context)
* ''Role assignments'' which have been made in any of the five contexts
* ''Role overrides'' which may occur in any of the contexts except System (there is no concept of override in System).

Note that there may be multiple assignments and/or overrides in any single context.

Whether or not the user can attempt the quiz is a function of the permissions data, as well as the location of the data in the context chain.

''has_capability()'' considers all roles and overrides that impact USER in CONTEXT, but it ignores capabilities other than CAP. This simplification lets us view each role or override as a ''single permission'' having one of the following values

N - Not set
A - Allow
P - Prevent
X - Prohibit

We use the following notation: for a role ''R1'' with permission ''P'', we write ''R1(P)''.

===An example===

In the quiz example, suppose that the user has four roles (''R1'', ''R2'', ''R3'', and ''R4'') and each of the roles has been assigned and overridden as follows:

0 System <---- define R1(A), R2(N), R3(N), R4(P)
| assign R1
|
1 Category A <-------------- overide R1(N) and R4(N)
|
|
2 Subcategory B <---- assign R2 and R3
|
|
3 Course <-------------- override R2(X) and R3(A)
|
|
4 Quiz <---- assign R4 and R1

Note that ''R1'' has been assigned in two different contexts. This is an unusual practice (it is probably someone's error), but since it is legal, we have to consider the possibility that it can happen. In fact this entire example has been contrived to explore the edge cases of the algorithm. In practice, the calculation of permissions is trivial and the function calculates the result you would expect based on common sense and simple mental analysis (for further discussion of this, see [[#A note about the algorithm|A note about the algorithm]] near the end of this article.

===Representing the data in tabular form===

We will set up a table to hold the permission data. The table has
*a column for each context, ordered from highest level (System) to lowest (the context where we want to compute the permission).
*a row for each context, also listed from highest to lowest.

[[Image:Calculation-3A.png|Empty table]]

The role definitions go in the first row. Put each definition in the column(s) coresponding to the context(s) in which the role is assigned:

[[Image:Calculation-5A.png|Table with assignments added]]

The overrides go in the remaining rows. Each override goes
*in the same column as the role being overridden
*in the row corresponding the context in which the override is made.

To illustrate, let's add just one of the overrides:

[[Image:Calculation-6A.png|Table with just one override]]

R2(X) represents the override to role R2 made in the course context. Let's add the rest of the overrides:

[[Image:Calculation-7A.png|Table with remaining overrides shown]]

The table is now fully populated, and we are ready to calculate the permission.

===The algorithm===

The algorithm follows a path through the table indicated by nodes and arrows in the diagram below and stops as soon as it has a conclusive result.

[[Image:Algorithm_path_through_permission_table_A.png|Algorithm path through permissions data]]

# If there is an X anywhere in the table, STOP. The calculated permission is ''X''
# Go to the START node
# If there is no next node, STOP. The calculated permission is ''P''
# Otherwise, follow the arrow to the next node
#Add the permissions in the node using the numerical equivalents: N = 0, A = +1, P = -1
#* If the sum is positive, STOP. The calculated permission is ''A''
#* If the sum is negative, STOP. The calculated permission is ''P''
#* If the sum is zero, GO TO step 3

Notice that the algorithm stops when either (1) a conclusive result is obtained, or (2) the algorithm reaches the last node without a conclusive result.

===Applying the algorithm to our example===

If we execute the algorithm with the quiz data, we stop at step 1 with a calculated permission of X. That's not very interesting, so let's change the X to a P and see what happens:

[[Image:Calculation-8A.png|Change X to P in permission table]]

Run the algorithm:

*There is No X in the table
*Go to the START node
*Go to the next node
*N + N = 0
*the sum is zero; go to the next node
*A + P = 0
*the sum is zero; go to the next node
*P + A = 0
*the sum is zero; go to the next node
*A + P = 0
*the sum is zero; go to the next node
*N = 0
*the sum is zero; go to the next node
*A = +1
*the sum is positive; STOP. The calculated permission is ''A''

If the calculated permission is ''A'', ''has_capability()'' returns ''true'', and the user is allowed to perform the action.

Had the calculated permission been ''P'' or ''X'', ''has_capability()'' would not immediately return ''false''. Rather, it would test if the user has ''moodle/site:doanything = Allow'' (since this permission trumps all others). The function does this by calling itself:

final result = has_capability(moodle/site:doanything,CONTEXT, USER);

==A note about the algorithm==

Earlier, we said that the algorithm "calculates the result you would expect." But what do we expect? Intuition tells us that permissions closer to the user should carry more weight than more distant permissions. That's why we set up the table the way we did and why the algorithm walks the table in the order that it does. The last column of the table represents the role assignment(s) closest to the user. The second-to-last column represents the role assignent(s) that are next in terms of distance from the user, and so-on. That's why the algorithm considers the columns from right-to-left. Within a column, the algorithm searches upward in order to give higher weight to overrides that are closer to the user. Once again, this matches our intuition about overrides. If there are no overrides in a column (or the overrides are all Not set), the permission in the role definition is used.

==Getting the result you expect==

The calculation is more likely to give "the result you would expect" if you keep your permissions as simple as possible. Therefore, we recommend the following 'rules' for defining and overriding roles. If you understand the description of the calculation above, you should understand why they make sense.

===When defining roles===

... use Allow (A) for things you want the role to be able to do, and use Not set (N) for things you don't care about (which should include most things).

===When overriding permissions===

... leave the permission for every capability as Inherit (N) apart from the few you want to change. For those, use Allow (A) for things you want to allow, and Prevent (P) for things you want to prevent.

===Only use prohibit in special roles===

Prohibit exists to cover extreme scenarios such as the following: Suppose you have a naughty student who is posting inappropriate content in your Moodle site. You need to be able to remove their ability to contribute to public discussions until they have promised not to do it again, but during that time, you cannot completely block them from the resources, quizzes, etc. because they must keep up with their studying. Therefore, you need a way to block their access to specific capabilities e.g. mod/forum:replypost in a way that cannot be overridden. You can do this by creating a special 'Naughty student' role defined with the required permission(s) set to prohibit. Then when you are having problems with a user, you can temporarily assign them this role, either at site level or at course level.

==A practical example==

Suppose that a user, who is assigned the role of Course creator in category B, creates a course (becoming Teacher in the course) and then creates a Lesson within the course. The user is about to edit the lesson (editing lessons is controlled by capability ''mod/lesson:edit''). Here is the permission data:

0 System <---- define Auth user(N), Creator(N), Teacher(A)
| assign Auth user
|
1 Category A
|
|
2 Subcategory B <---- assign Creator
|
|
3 Course <---- assign Teacher
|
|
4 Lesson <---- user attempts to edit lesson

We set up the table and populate it with permission data.

[[Image:Calculation-10A.png|A practical example]]

Since there are no overrides, the table only has data in the first row. The algorithm quickly calculates a permission of ''A'' and returns true. The user is allowed to edit the Lesson!

Now suppose Teacher is overridden in the Lesson context with ''mod/lesson:edit = P''. Then the table changes

[[Image:Calculation-11A.png|A practical example with first override]]

and clearly the user is no longer allowed to edit the Lesson.

But suppose the administrator (or whoever is making the overrides) decided instead to override the ''Creator role'', setting ''mod/lesson:edit = Prevent'' in the Categoy B context:

[[Image:Calculation-12A.png|A practical example with second override]]

Much to everyone's surprise, the user is still allowed to edit the Lesson! If you understood this article, you shouldn't be surprised, and you should be able to explain what happened.

==See also==

*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=90140 Logged in: what role am I?] and [http://moodle.org/mod/forum/discuss.php?d=66782 What happens if a user has multiple roles in a course?] forum discussions.

There is a script that you can use to create tables like the ones in this article. It is very useful for debugging roles-related problems. See [[The rolesdebug.php roles debugging script]].

[[Category:Roles]]

[[fr:Comment les permissions sont calculées ?]]

The rolesdebug.php roles debugging script

2008-04-25T14:25:14Z

Jisner:

{{Roles}}{{Moodle 1.9}}
Rolesdebug.php is a stand-alone script that is extremely useful for debugging problems related to roles and permissions. The output can be interpreted by anyone with a good understanding of Moodle's [[Roles and capabilities]] system. If you're a "roles novice" and you need help with a roles-related problem, you can ask a roles expert to help you with running the script and interpreting the output. Simply post a request for help to the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum].

You can download rolesdebug.php from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and Plugins database]. To install the script, simply drop it into the Moodle root directory or any directory under the root directory.

Rolesdebug.php requires a login, so only someone with a Moodle user account who is currently logged in can use it. Since it is a php script, you will see the output in your browser. No one else will see it unless they're looking over your shoulder. Furthermore, rolesdebug.php gives you information about YOUR permissions. You cannot use it to get information about another user's permissions, unless you can login as them.

Rolesdebug.php returns a table that gives a spatial view of the role assignments and overrides that affect you in a specified context. From the table, you will be able to see how Moodle calculates a specified permission. The table format is explained (and several examples are given) in the article [[How permissions are calculated]].

Rolesdebug.php reads permission data from the Moodle database but does not modify the database in any way. In this respect, it is similar to other debug scripts in the standard distribution, like the [[TeX_notation_filter#Debugging_TeX_filter | TeX notation debugger]].

==The use case for rolesdebug.php==

The main use case for rolesdebug.php is a ''roles expert helping a roles novice troubleshoot a roles-related problem''. A ''roles expert'' is anyone with a basic understanding of the [[#Essential roles and capabilities concepts | essential roles concepts]] listed in the next section. A ''roles novice'' is any Moodle user with the ability to follow simple instructions from the expert. While the expert and novice may occasionally share the same physical location and have accounts on the same Moodle site, it is not required. The expert must be able to help the novice without logging in to the novice's site, and by communicating with the novice only by e-mail, messaging, forum posts, etc.. For example, the novice may be a user posting to a moodle.org forum and the expert may be a moodler wanting to be helpful. Even when expert and novice share a physical location and have accounts on the same Moodle site, the expert may not be in a position to give direct help, e.g., by "logging in as" the novice or meeting with the novice. For example, the expert may be a Moodle administrator with an extremely busy schedule.

Here's a typical scenario. Supposed the novice is a teacher who has created a quiz, but is being prevented from previewing the quiz for some unknown reason. The novice reports the problem to moodle.org in a forum post. The expert (a helpful moodler) suspects a roles problem and replies by asking the novice to (1) log in to Moodle, reproduce the problem (2) browse to rolesdebug.php (3) enter two or three parameters as specified by the expert (4) paste the output from rolesdebug.php into a reply to this forum post. The expert reviews the output and (hopefully) diagnoses the problem.

Secondary use cases for rolesdebug.php include
* a user troubleshooting his own problems
* a user troubleshooting another user's problem while logged in as that user

Note that both of these secondary use cases are equivalent, since there is only one actor (the expert), not two. To keep things simple in the remainder of the article, I'll describe the secondary use case, and I'll refer only to YOU. Keeping the primary use case in mind, it should be clear when "you" means roles expert and when it means the roles novice.

==Essential roles and capabilities concepts==

Interpreting the output from rolesdebug.php requires at least a basic understanding of the concepts listed below. If any of these concepts are unfamiliar to you, stop and follow the documentation link.

* [[Assign_roles#Contexts | Context]]
* [[Capabilities | Capability]]
* [[Capabilities | Permission]]
* [[Capabilities | Role]]
* [[Assign_roles | Role assignment]]
* [[Override_permissions | Role override]]
* [[How permissions are calculated]]

==Overview of a script session==

First, you will log in to Moodle and navigate to the context where you're having the problem. Perhaps this is a quiz which Moodle, for some unknown reason, is preventing you from attempting. Then, without logging out of Moodle, point your browser at rolesdebug.php (I find it convenient to open a new browser tab for this). Input the ''context'' you're interested in and (optionally) the name of a ''capability'' to investigate, then press the Go button. The script will return a page with a table presenting a spatial view of the role assignments and overrides that affect you in the specified context. From the table, you will be able to see why Moodle is preventing you from attempting the quiz.

==Using the script==

===STEP1===
This step is done in Moodle (you won't use the script until STEP 2). Login to Moodle and navigate into the context where the problem is occurring. Once you're there, you'll make note of the context id, which is needed in STEP 2. I'll tell you [[#How to determine the context id|how to determine the context id]] later.

Incidentally, even if you know the context id, it is essential that you actually navigate to the context. This is because Moodle loads certain permission data "lazily" -- i.e., only when actually needed. Navigating to the context guarantees that Moodle will have loaded the data.

For example, suppose the target context is a certain quiz in some course. You must enter the course and click on the Quiz icon.

If you are debugging a problem related to an ''automatic role assignment'', you must logout and log back in prior to STEP 1. Automatic role assignments are those which are controlled by user policies such as Site administration -> Front page -> Front page settings -> Default front page role.

Do not log out!

===STEP 2===
Open a second browser window. In the window, point your browser at
rolesdebug.php. The script URL will be something like

http://yoursite/moodle/rolesdebug.php

Rolesdebug.php will NOT ask you to login because you are already logged in. The script will ask you for three inputs:

* CAPABILITY. If you're only interested in seeing your role assignments and overrides, you can leave this field empty. If you're interested in analyzing a particular permission, you'll need to enter the capability name. For example, if you're interested in the capability that controls your ability to attempt quizzes, enter [[Capabilities/mod/quiz:attempt | mod/quiz:attempt]].

* CONTEXT TYPE. Choose one of the following from the dropdown menu:
**COURSE
**MODULE
**BLOCK
**COURSECAT
**USER
**SYSTEM

* CONTEXT ID. The context id is a number at the end of the URL of the page you found in STEP 1. See [[#How to determine the context id|How to determine the context id]] below.

Incidentally, MODULE means activity or resource. There is no FRONT PAGE context. If you're interested in the Front page context, choose COURSE and specify a context id of 1.

Here's an example of input:

[[Image:sample_input_quiz_attempt.png|sample input when investigating a quiz attempt]]

===STEP 3===
Press the Go button. Rolesdebug.php will return a page of information. The main item on the page is a table giving a spatial view of all the role assignments and overrides that affect you in the specified context.

==How to read the output==
Let's look at a typical output for the input parameters from the last section.
[[Image:sample_output_quiz_attempt.png|sample output when investigating a quiz attempt]]

The first three lines of output (1) simply echo your input values, and the next two lines (2) remind you of who YOU are, and tell you the actual name of the context you have selected. Check these carefully to make
sure you are who you think you are, and have specified the correct context.

For each of your roles, you will see a line of the form ''alias = role name'' where
* ''role name'' is the actual role name
* ''alias'' is the name used to represent the role in the table

In the example, ''R7 = user'' means the the role user (the shortname of Authorized user) will be represented in the table by the alias R7. Aliases are used because long role names could make the table very wide, forcing you to scroll horizontally. By using aliases, the table will hopefully fit in a window, allowing you to see the entire table in a single a glance.

Next comes the table (4). I'll have a lot more to say about the table below.

If you specified a capability, then below the table, you'll see the
value of the permission that Moodle calculated (5). "True" means you are allowed to perform the action and "False" means that you are prevented from performing the action.

====How to read the table====

If the target context is N levels deep, the table will have N rows and N columns, one for each context level. The example above has four levels:

System
|
|
Category "A"
|
|
Course "cooking"
|
|
Module "quiz-1"

The column headings give the names of the contexts. These are listed in order of increasing depth: System, A, cooking, quiz-1.

To save space, the table does not have row headings. If it did, they would be the same as the column headings. For example, row 1 would be labeled "System" and row 4 would be labeled "quiz-1".

The first row of the table contains the role assignments made in each context level. In the example, you can see that R7 (Authorized user) is assigned in the System context and R5 (Student) is assigned in the course context. If there are no overrides (as in this example) you will only see entries in row 1.

The letters N and A in parentheses are the values of the capabilities in the role definitions. The possible values are:

N - Not set
A - Allow
P - Prevent
X - Prohibit

"Not set" means that the role doesn't say anything about the capability. In the example, we see that the Student role allows
quiz attempts, while the Authorized user role doesn't have anything
to say about quiz attempts.

If there are role overrides, there will be entries in other rows of the table. Overrides have the same format as the assignments in row 1. An override is shown in the ROW of the context where it is made, and the COLUMN of the assignment that it overrides.

To illustrate, let's override the Student role in the Quiz context, setting mod/quiz:attempt to Prevent, and then rerun rolesdebug.php. Of course before running the script, the student must attempt the quiz. This time, the student should be prevented because of the override. Now we run the script and get the following output:
[[Image:sample_output_quiz_attempt_with_override.png|sample output when investigating a quiz attempt and there is an override]]

Notice the newly added R5(P). This is the override. It is in the fourth row because the override was made in the quiz context, and it is in the course column because the Student role was assigned in the Course context.

Finally, notice that Moodle now tells us that the calculated permission is "false," exactly as we expect.

====How Moodle calculates the final permission====

By scanning the table in a certain way, you can see how Moodle
arrives at its calculated permission. You can always do this with a quick visual scan, regardless of how many role assignments and overrides the table contains.

For the original example (where we only had role assignments in row 1),
scan row 1 from right to left,
[[Image:sample_output_quiz_attempt_showing_path.png|how to scan the table when investigating a quiz attempt]]

* if there is an X anywhere in the row, the operation is prevented
* otherwise, scan the row from right to left, ignoring N's
* if the first R you hit is an A, the operation is allowed
* if the first R value you hit is P, the operation is prevented
* if a column contains one or more A's AND one or more P's cancel pairs of A-P pairs until either (1) all pairs cancel or (2) you are left with one or more A's or P's. If you are left with A's, the operation is allowed. If you are left with P's, the operation is prevented.
* if your scan takes you all the way to the leftmost column and you still haven't found a conclusive result, the operation is prevented.

When there are overrides, you do the same thing, but your scan follows a different path.
[[Image:sample_output_quiz_attempt_with_override_showing_path.png|how to scan the table when investigating a quiz attempt and there is an override]]

For a complete explanation of how permissions are calculated, read the article [[How permissions are calculated | How permissions are calculated]].

==How to determine the context id==
Here are rules for determining the context id for each context type.
===COURSE===
For a COURSE context, the context id is the course id. You can get the course id from the URL that appears in the address bar when when you're on the course page. For example when I point my browser at the "Features" course on demo.moodle.org, I see this:

[[Image:URI_of_course_in_address_bar.png|URI of course is shown in the address bar]]

The course id, and therefore the context id for this course is 2.

If Moodle won't let you enter the course for some reason, but you can see a link to the course, let your mouse hover over the link as in the following screenshot. Your browser will show you the address at the bottom of the window.

[[Image:URI_of_course_at_bottom_of_browser_window.png|URI of course is shown at the bottom of the browser window]]

The front page of a Moodle site is also a course, but you can't use either of the above tricks to get the id. ''The front page course id is 1.''

===MODULE (activity or resource)===
For a MODULE context, the context id is the activity or resource id. You can get the id from the URL that appears in the address bar when you're viewing the activity or resource, or from the bottom of the browser window when you let your mouse hover over a link. Here are some examples:

http://demo.moodle.org/mod/choice/view.php?id=25
http://demo.moodle.org/mod/forum/view.php?id=28
http://demo.moodle.org/mod/lesson/view.php?id=38
http://demo.moodle.org/mod/quiz/view.php?id=61
http://demo.moodle.org/mod/resource/view.php?id=10
http://demo.moodle.org/mod/resource/view.php?id=48

The context id's for these modules are 25, 28, 38, 61, 10, and 48.

===BLOCK===
For a BLOCK context, the context id is the "instanceid" of the block. To get the instanceid, turn editing on and let the mouse hover over the "eye" icon in the block header. Then take the instanceid from URL that appears in the at the bottom of the window. For example:

http://demo.moodle.org/course/view.php?id=28&instanceid=19...

The context id for this block is 19. Note that for blocks, only a user who can turn editing on can get the instanceid.

===COURSECAT===
For a COURSECAT context, the context id is the category id. You can get the id from the URL that appears in the address bar when you're on the category page. If the site has only one category (usually called "Miscellaneous") the id is 1. If there is more than one category, the easiest way to get the category id for a specific category is to have a Category list or a Combo list on the front page of the site (or a Courses block) and let your mouse hover over one of the links. For example:

http://mysite/course/category.php?id=3

The context id for this category is 3

===USER===
For a USER context, the context id is the user id. You can get the id from the URL that appears in the address bar when you're on a profile page, or from the bottom of the browser window when you let your mouse hover over a user's name. For example:

http://demo.moodle.org/user/view.php?id=6&course=1

The context id for this user is 6

===SYSTEM===
There is only one SYSTEM context. Its id is 1.

[[Category:Contributed code]]

The rolesdebug.php roles debugging script

2008-04-20T16:30:58Z

Jisner:

{{Roles}}{{Moodle 1.9}}
Rolesdebug.php is a stand-alone script that is extremely useful for debugging problems related to roles and permissions. The output can be interpreted by anyone with a basic understanding of Moodle's [[Roles and capabilities]] system.

You can download rolesdebug.php from the [http://moodle.org/mod/data/view.php?d=13&rid=1204 Modules and Plugins database]. To install the script, simply drop it into the Moodle root directory or any directory under the root directory.

Rolesdebug.php requires a login, so only someone with a Moodle user account who is currently logged in can use it. Since it is a php script, you will see the output in your browser. No one else will see it unless they're looking over your shoulder. Furthermore, rolesdebug.php gives you information about YOUR permissions. You cannot use it to get information about another user's permissions, unless you can login as them.

Rolesdebug.php returns a table that gives you a spatial view of the role assignments and overrides that affect you in a specified context. From the table, you will can easily see how Moodle calculates a specified permission. The table format is explained (and several examples are given) in the article [[How permissions are calculated]].

Rolesdebug.php reads permission data from the Moodle database but does not modify the database in any way. In this respect, it is similar to other debug scripts in the standard distribution, like the [[TeX_notation_filter#Debugging_TeX_filter | TeX notation debugger]].

==The use case for rolesdebug.php==

The main use case for rolesdebug.php is a ''roles expert helping a roles novice troubleshoot a roles-related problem''. A ''roles expert'' is anyone with a basic understanding of the [[#Essential roles and capabilities concepts | essential roles concepts]] listed in the next section. A ''roles novice'' is any Moodle user with the ability to follow simple instructions from the expert. While the expert and novice may occasionally share the same physical location and have accounts on the same Moodle site, it is not required. The expert must be able to help the novice without logging in to the novice's site, and by communicating with the novice only by e-mail, messaging, forum posts, etc.. For example, the novice may be a user posting to a moodle.org forum and the expert may be a moodler wanting to be helpful. Even when expert and novice share a physical location and have accounts on the same Moodle site, the expert may not be in a position to give direct help, e.g., by "logging in as" the novice or meeting with the novice. For example, the expert may be a Moodle administrator with an extremely busy schedule.

Here's a typical scenario. Supposed the novice is a teacher who has created a quiz, but is being prevented from previewing the quiz for some unknown reason. The novice reports the problem to moodle.org in a forum post. The expert (a helpful moodler) suspects a roles problem and replies by asking the novice to (1) log in to Moodle, reproduce the problem (2) browse to rolesdebug.php (3) enter two or three parameters as specified by the expert (4) paste the output from rolesdebug.php into a reply to this forum post. The expert reviews the output and (hopefully) diagnoses the problem.

Secondary use cases for rolesdebug.php include
* a user troubleshooting his own problems
* a user troubleshooting another user's problem while logged in as that user

Note that both of these secondary use cases are equivalent, since there is only one actor (the expert), not two. To keep things simple in the remainder of the article, I'll describe the secondary use case, and I'll refer only to YOU. Keeping the primary use case in mind, it should be clear when "you" means roles expert and when it means the roles novice.

==Essential roles and capabilities concepts==

Interpreting the output from rolesdebug.php requires at least a basic understanding of the concepts listed below. If any of these concepts are unfamiliar to you, stop and follow the documentation link.

* [[Assign_roles#Contexts | Context]]
* [[Capabilities | Capability]]
* [[Capabilities | Permission]]
* [[Capabilities | Role]]
* [[Assign_roles | Role assignment]]
* [[Override_permissions | Role override]]
* [[How permissions are calculated]]

==Overview of a script session==

First, you will log in to Moodle and navigate to the context where you're having the problem. Perhaps this is a quiz which Moodle, for some unknown reason, is preventing you from attempting. Then, without logging out of Moodle, point your browser at rolesdebug.php (I find it convenient to open a new browser tab for this). Input the ''context'' you're interested in and (optionally) the name of a ''capability'' to investigate, then press the Go button. The script will return a page with a table presenting a spatial view of the role assignments and overrides that affect you in the specified context. From the table, you will be able to see why Moodle is preventing you from attempting the quiz.

==Using the script==

===STEP1===
This step is done in Moodle (you won't use the script until STEP 2). Login to Moodle and navigate into the context where the problem is occurring. Once you're there, you'll make note of the context id, which is needed in STEP 2. I'll tell you [[#How to determine the context id|how to determine the context id]] later.

Incidentally, even if you know the context id, it is essential that you actually navigate to the context. This is because Moodle loads certain permission data "lazily" -- i.e., only when actually needed. Navigating to the context guarantees that Moodle will have loaded the data.

For example, suppose the target context is a certain quiz in some course. You must enter the course and click on the Quiz icon.

If you are debugging a problem related to an ''automatic role assignment'', you must logout and log back in prior to STEP 1. Automatic role assignments are those which are controlled by user policies such as Site administration -> Front page -> Front page settings -> Default front page role.

Do not log out!

===STEP 2===
Open a second browser window. In the window, point your browser at
rolesdebug.php. The script URL will be something like

http://yoursite/moodle/rolesdebug.php

Rolesdebug.php will NOT ask you to login because you are already logged in. The script will ask you for three inputs:

* CAPABILITY. If you're only interested in seeing your role assignments and overrides, you can leave this field empty. If you're interested in analyzing a particular permission, you'll need to enter the capability name. For example, if you're interested in the capability that controls your ability to attempt quizzes, enter [[Capabilities/mod/quiz:attempt | mod/quiz:attempt]].

* CONTEXT TYPE. Choose one of the following from the dropdown menu:
**COURSE
**MODULE
**BLOCK
**COURSECAT
**USER
**SYSTEM

* CONTEXT ID. The context id is a number at the end of the URL of the page you found in STEP 1. See [[#How to determine the context id|How to determine the context id]] below.

Incidentally, MODULE means activity or resource. There is no FRONT PAGE context. If you're interested in the Front page context, choose COURSE and specify a context id of 1.

Here's an example of input:

[[Image:sample_input_quiz_attempt.png|sample input when investigating a quiz attempt]]

===STEP 3===
Press the Go button. Rolesdebug.php will return a page of information. The main item on the page is a table giving a spatial view of all the role assignments and overrides that affect you in the specified context.

==How to read the output==
Let's look at a typical output for the input parameters from the last section.
[[Image:sample_output_quiz_attempt.png|sample output when investigating a quiz attempt]]

The first three lines of output (1) simply echo your input values, and the next two lines (2) remind you of who YOU are, and tell you the actual name of the context you have selected. Check these carefully to make
sure you are who you think you are, and have specified the correct context.

For each of your roles, you will see a line of the form ''alias = role name'' where
* ''role name'' is the actual role name
* ''alias'' is the name used to represent the role in the table

In the example, ''R7 = user'' means the the role user (the shortname of Authorized user) will be represented in the table by the alias R7. Aliases are used because long role names could make the table very wide, forcing you to scroll horizontally. By using aliases, the table will hopefully fit in a window, allowing you to see the entire table in a single a glance.

Next comes the table (4). I'll have a lot more to say about the table below.

If you specified a capability, then below the table, you'll see the
value of the permission that Moodle calculated (5). "True" means you are allowed to perform the action and "False" means that you are prevented from performing the action.

====How to read the table====

If the target context is N levels deep, the table will have N rows and N columns, one for each context level. The example above has four levels:

System
|
|
Category "A"
|
|
Course "cooking"
|
|
Module "quiz-1"

The column headings give the names of the contexts. These are listed in order of increasing depth: System, A, cooking, quiz-1.

To save space, the table does not have row headings. If it did, they would be the same as the column headings. For example, row 1 would be labeled "System" and row 4 would be labeled "quiz-1".

The first row of the table contains the role assignments made in each context level. In the example, you can see that R7 (Authorized user) is assigned in the System context and R5 (Student) is assigned in the course context. If there are no overrides (as in this example) you will only see entries in row 1.

The letters N and A in parentheses are the values of the capabilities in the role definitions. The possible values are:

N - Not set
A - Allow
P - Prevent
X - Prohibit

"Not set" means that the role doesn't say anything about the capability. In the example, we see that the Student role allows
quiz attempts, while the Authorized user role doesn't have anything
to say about quiz attempts.

If there are role overrides, there will be entries in other rows of the table. Overrides have the same format as the assignments in row 1. An override is shown in the ROW of the context where it is made, and the COLUMN of the assignment that it overrides.

To illustrate, let's override the Student role in the Quiz context, setting mod/quiz:attempt to Prevent, and then rerun rolesdebug.php. Of course before running the script, the student must attempt the quiz. This time, the student should be prevented because of the override. Now we run the script and get the following output:
[[Image:sample_output_quiz_attempt_with_override.png|sample output when investigating a quiz attempt and there is an override]]

Notice the newly added R5(P). This is the override. It is in the fourth row because the override was made in the quiz context, and it is in the course column because the Student role was assigned in the Course context.

Finally, notice that Moodle now tells us that the calculated permission is "false," exactly as we expect.

====How Moodle calculates the final permission====

By scanning the table in a certain way, you can see how Moodle
arrives at its calculated permission. You can always do this with a quick visual scan, regardless of how many role assignments and overrides the table contains.

For the original example (where we only had role assignments in row 1),
scan row 1 from right to left,
[[Image:sample_output_quiz_attempt_showing_path.png|how to scan the table when investigating a quiz attempt]]

* if there is an X anywhere in the row, the operation is prevented
* otherwise, scan the row from right to left, ignoring N's
* if the first R you hit is an A, the operation is allowed
* if the first R value you hit is P, the operation is prevented
* if a column contains one or more A's AND one or more P's cancel pairs of A-P pairs until either (1) all pairs cancel or (2) you are left with one or more A's or P's. If you are left with A's, the operation is allowed. If you are left with P's, the operation is prevented.
* if your scan takes you all the way to the leftmost column and you still haven't found a conclusive result, the operation is prevented.

When there are overrides, you do the same thing, but your scan follows a different path.
[[Image:sample_output_quiz_attempt_with_override_showing_path.png|how to scan the table when investigating a quiz attempt and there is an override]]

For a complete explanation of how permissions are calculated, read the article [[How permissions are calculated | How permissions are calculated]].

==How to determine the context id==
Here are rules for determining the context id for each context type.
===COURSE===
For a COURSE context, the context id is the course id. You can get the course id from the URL that appears in the address bar when when you're on the course page. For example when I point my browser at the "Features" course on demo.moodle.org, I see this:

[[Image:URI_of_course_in_address_bar.png|URI of course is shown in the address bar]]

The course id, and therefore the context id for this course is 2.

If Moodle won't let you enter the course for some reason, but you can see a link to the course, let your mouse hover over the link as in the following screenshot. Your browser will show you the address at the bottom of the window.

[[Image:URI_of_course_at_bottom_of_browser_window.png|URI of course is shown at the bottom of the browser window]]

The front page of a Moodle site is also a course, but you can't use either of the above tricks to get the id. ''The front page course id is 1.''

===MODULE (activity or resource)===
For a MODULE context, the context id is the activity or resource id. You can get the id from the URL that appears in the address bar when you're viewing the activity or resource, or from the bottom of the browser window when you let your mouse hover over a link. Here are some examples:

http://demo.moodle.org/mod/choice/view.php?id=25
http://demo.moodle.org/mod/forum/view.php?id=28
http://demo.moodle.org/mod/lesson/view.php?id=38
http://demo.moodle.org/mod/quiz/view.php?id=61
http://demo.moodle.org/mod/resource/view.php?id=10
http://demo.moodle.org/mod/resource/view.php?id=48

The context id's for these modules are 25, 28, 38, 61, 10, and 48.

===BLOCK===
For a BLOCK context, the context id is the "instanceid" of the block. To get the instanceid, turn editing on and let the mouse hover over the "eye" icon in the block header. Then take the instanceid from URL that appears in the at the bottom of the window. For example:

http://demo.moodle.org/course/view.php?id=28&instanceid=19...

The context id for this block is 19. Note that for blocks, only a user who can turn editing on can get the instanceid.

===COURSECAT===
For a COURSECAT context, the context id is the category id. You can get the id from the URL that appears in the address bar when you're on the category page. If the site has only one category (usually called "Miscellaneous") the id is 1. If there is more than one category, the easiest way to get the category id for a specific category is to have a Category list or a Combo list on the front page of the site (or a Courses block) and let your mouse hover over one of the links. For example:

http://mysite/course/category.php?id=3

The context id for this category is 3

===USER===
For a USER context, the context id is the user id. You can get the id from the URL that appears in the address bar when you're on a profile page, or from the bottom of the browser window when you let your mouse hover over a user's name. For example:

http://demo.moodle.org/user/view.php?id=6&course=1

The context id for this user is 6

===SYSTEM===
There is only one SYSTEM context. Its id is 1.

[[Category:Contributed code]]