I have written an article in the documentation wiki called Rules for adding permissions. I welcome your feedback.
Thanks for your effort!
To me it is a god article. I read about the role system when I worked with the translation files, but I have forgotten how it works. I am sure that your article will make it easier for me to remember. Especially I like the idea to present the capability values in a table, it makes it easier to cope with.
To me it is a god article. I read about the role system when I worked with the translation files, but I have forgotten how it works. I am sure that your article will make it easier for me to remember. Especially I like the idea to present the capability values in a table, it makes it easier to cope with.
Oh, boy. I read this and my conclusion: Roles are hard -- very hard. But, John, I do admire your willingness to take on a difficult subject and to make it as simple as possible. This will make for fun discussions with students in our software club and my students in my Software Development class.
But more generally, I head a math department, I have a technical staff with advanced degrees in computer science + experience, have a math faculty including those who have been captains of nuclear submarines, and we attract some of the top students in math in the city of Seattle. But I have to say, given anything other than a simple variant of a default configuration, I think we would have a very difficult time, even working together, to determine the answer to an arbitrary collection of role assignments. And if we were to get out of practice(and context) for even a few weeks, we would probably fail miserably. It is hard for me to imagine having such a discussion with a member of my humanities or theater departments, each and every one who has very real needs in facilitating their courses with Moodle and are heavy users.
So, I think the challenge for those of us who think about these things is how to make some fairly basic configuration options for our users to choose from and to have them feel comfortable with the results. Perhaps that at is a reasonable target for version 2.0. An example is something I have worked on in the past few days: keep my courses public while restricting copyright restricted information to my enrolled students. But even though that is clearly a permissions issue and a common enough type of consideration, it seems like I need to go outside of the role configurations to give me what I want.
Sad, but true... Although I am an optimist looking forward, and am overall very happy with what Moodle has done for us
--Gary
But more generally, I head a math department, I have a technical staff with advanced degrees in computer science + experience, have a math faculty including those who have been captains of nuclear submarines, and we attract some of the top students in math in the city of Seattle. But I have to say, given anything other than a simple variant of a default configuration, I think we would have a very difficult time, even working together, to determine the answer to an arbitrary collection of role assignments. And if we were to get out of practice(and context) for even a few weeks, we would probably fail miserably. It is hard for me to imagine having such a discussion with a member of my humanities or theater departments, each and every one who has very real needs in facilitating their courses with Moodle and are heavy users.
So, I think the challenge for those of us who think about these things is how to make some fairly basic configuration options for our users to choose from and to have them feel comfortable with the results. Perhaps that at is a reasonable target for version 2.0. An example is something I have worked on in the past few days: keep my courses public while restricting copyright restricted information to my enrolled students. But even though that is clearly a permissions issue and a common enough type of consideration, it seems like I need to go outside of the role configurations to give me what I want.
Sad, but true... Although I am an optimist looking forward, and am overall very happy with what Moodle has done for us
--Gary
But more generally, I head a math department, I have a technical staff with advanced degrees in computer science + experience, have a math faculty including those who have been captains of nuclear submarines, and we attract some of the top students in math in the city of Seattle. But I have to say, given anything other than a simple variant of a default configuration, I think we would have a very difficult time, even working together, to determine the answer to an arbitrary collection of role assignments. And if we were to get out of practice(and context) for even a few weeks, we would probably fail miserably. It is hard for me to imagine having such a discussion with a member of my humanities or theater departments, each and every one who has very real needs in facilitating their courses with Moodle and are heavy users.
Brilliant...I will most definitely have to cite this in my "users guide". Currently the roles chapter in my guide only contains one line: "Don't touch them unless absolutely necessary and then only to the extent absolutely necessary"...I think I'll cite this and consider that chapter complete.
This is about the best summary of roles I've seen anywhere
Steve
Hi Gary,
As a challenge to your programming club, have them code up the algorithm in Scheme. Keep the code at the same level of abstraction as the article (for example, model a permission as a (cap,value) pair, and the data structure as a list of lists of permissions). I'm guessing 10-20 lines of code, max. We'll put the most readable and elegant version in docs.
As I mentioned in the article, I was struck at the amazing simplicity of the permission calculation. I now agree with Tim in this discussion that it "normally does what you expect." However this is true only when "you" are someone who knows what he's doing. The majority of cases "requiring analysis," resulting in "arbitrary collections of role assignments" etc. etc. are being created by people who are fiddling blindly with roles. As an administrator, there is no escaping it: you must know this stuff. Don't enable override for Teacher until you do, and until they have gotten some training. You can selectively enable override for specific teachers in specific courses. Nobody is forcing you take an all-or-nothing approach to roles.
I agree roles in general are overly complex and can be frustrating, even for people who are trained and supposedly know what they're doing. However ideas about simplifying roles should be brought up in a different discussion.
As a challenge to your programming club, have them code up the algorithm in Scheme. Keep the code at the same level of abstraction as the article (for example, model a permission as a (cap,value) pair, and the data structure as a list of lists of permissions). I'm guessing 10-20 lines of code, max. We'll put the most readable and elegant version in docs.
As I mentioned in the article, I was struck at the amazing simplicity of the permission calculation. I now agree with Tim in this discussion that it "normally does what you expect." However this is true only when "you" are someone who knows what he's doing. The majority of cases "requiring analysis," resulting in "arbitrary collections of role assignments" etc. etc. are being created by people who are fiddling blindly with roles. As an administrator, there is no escaping it: you must know this stuff. Don't enable override for Teacher until you do, and until they have gotten some training. You can selectively enable override for specific teachers in specific courses. Nobody is forcing you take an all-or-nothing approach to roles.
I agree roles in general are overly complex and can be frustrating, even for people who are trained and supposedly know what they're doing. However ideas about simplifying roles should be brought up in a different discussion.
John:
I think that there is a remarkable amount of agreement on roles, including by those who developed the system. But since you asked for feedback, I thought that it was important to point out that the "amazing simplicity" that you referred to was a description of your "breakthrough moment" much like when we understand an important new concept in physics for the first time, rather than that the framework itself might be easily understood by the common user or even many system admins.
Your article will certainly help in shortening that path to that "breakthrough moment" for the next person, however, and for that we should all be grateful.
And it seems like we all agree that there is work to be done to make roles more useful and intuitive.
Take care,
--Gary
I think that there is a remarkable amount of agreement on roles, including by those who developed the system. But since you asked for feedback, I thought that it was important to point out that the "amazing simplicity" that you referred to was a description of your "breakthrough moment" much like when we understand an important new concept in physics for the first time, rather than that the framework itself might be easily understood by the common user or even many system admins.
Your article will certainly help in shortening that path to that "breakthrough moment" for the next person, however, and for that we should all be grateful.
And it seems like we all agree that there is work to be done to make roles more useful and intuitive.
Take care,
--Gary
Great effort! It seems pretty correct, but I have to say it looks a lot more complicated than my mental model feels.
I've moved it temporarily to How permissions are calculated because the name was a bit ambiguous before, I think, but will happily move it anywhere more appropriate.
I've moved it temporarily to How permissions are calculated because the name was a bit ambiguous before, I think, but will happily move it anywhere more appropriate.
That's a good name. Mine was just a working title, as they say in show biz.
I simplified the descriptions last night a bit too.
It looks way more complicated than my mental model too. I will try to find the time to help here, and simplify if possible.
The first 3 paragraphs are also confusing. The first one says we'll answer a question we won't. The 3rd one explains that we won't. Maybe we need to fix the opening paragraph
The first 3 paragraphs are also confusing. The first one says we'll answer a question we won't. The 3rd one explains that we won't. Maybe we need to fix the opening paragraph
Looks like I owe you a beer or two then John. A very clear description. I now fully understand roles. Yay!
Thanks Tim. I'd love to take you up on it, but my budget will only get me about half-way to San Francisco
Perhaps you should try contacting the organisers saying that you can give a talk to explain to the world how roles work, just to see if that would get them to pay your expenses 
I just realized there's a serious flaw in my model of the algorithm. I'm surprised nobody caught it yet. No wonder it's so simple! The model ignores the level at which role assignments occur. Clearly, if role A has been assigned at a deeper level than role B, the permissions in A win over those in B. The model treats all assignments as having been made at the same level (effectively, at System).
I can still use the addition tableau as a model, but I need to modify the steps of the algorithm. Here are the two big changes: (1) you DO have to put the overrides in same column as the role being overridden (2) you must consider the columns, not just rows. Specifically for (2), you must consider the columns in order of role assignment.
I'll fix this today and post again here. I apologize for any false euphoria I've created, and I yield my two beers back to Tim!
The new version of the article is ready. I'm 99.99% sure I got it right this time. If you are listening, Martin Langhoff, I would appreciate you reviewing it and giving us your expert opinion.
I just took the liberty of adding some section headings to break it up a bit. I hope that is OK. Also, the description of what happened when the algorithm was applied did not tally with the table, so I took the liberty of swapping the A and P in the definition of R1 and R4, so they did match. I hope that is OK.
Also, note that in fact, Ns are never stored in the database. It is only necessary to store A, P and X's (since N is worth 0, just like an empty cell, it doesn't really matter whether they are stored or not, it does not really matter whether they are left in or taken out of the explanation.)
Also, note that in fact, Ns are never stored in the database. It is only necessary to store A, P and X's (since N is worth 0, just like an empty cell, it doesn't really matter whether they are stored or not, it does not really matter whether they are left in or taken out of the explanation.)
Thanks Tim, I'll take a look at the changes. I think section headings were needed.
I intentionally did not mention the database in the article, since the article explains what, not how. I say nothing about the data structure or algorithm used by the actual function, and I hope people understand that. If they want to read the code, more power to them
The issue you raise about the N's was very much in my mind when I wrote the article. My decision to keep them was to help the bookkeeping when doing calculations on paper. I think you should make a physical entry in the table for every role definition and each override, even if it's Not set. If you leave an entry blank because its value is Not set, then how do you tell the difference between (1) I took this override into consideration (2) I accidentally overlooked it?
I intentionally did not mention the database in the article, since the article explains what, not how. I say nothing about the data structure or algorithm used by the actual function, and I hope people understand that. If they want to read the code, more power to them
The issue you raise about the N's was very much in my mind when I wrote the article. My decision to keep them was to help the bookkeeping when doing calculations on paper. I think you should make a physical entry in the table for every role definition and each override, even if it's Not set. If you leave an entry blank because its value is Not set, then how do you tell the difference between (1) I took this override into consideration (2) I accidentally overlooked it?
Of course, the two beers I owe you are reinstated now.
Do you remember a few weeks ago, we were talking about a UI screen to help users understand the permissions in a particular context. Now we have the notation in your article it is clear that what we need is, for users who have roles-related capabilities (either assign or override plus view participants), a new tab next to assign and override that lets you select a user and a capability, and then automatically draws the table like in your article, and gives the worked application of the algorithm. Should be doable, if only I had the time.
Do you remember a few weeks ago, we were talking about a UI screen to help users understand the permissions in a particular context. Now we have the notation in your article it is clear that what we need is, for users who have roles-related capabilities (either assign or override plus view participants), a new tab next to assign and override that lets you select a user and a capability, and then automatically draws the table like in your article, and gives the worked application of the algorithm. Should be doable, if only I had the time.
Hi Tim,
That's a very good idea, and it sounds like it would be fun to do (if only you had time ).
IMO the question "What are my permissions here?" is THE question that people need answered most, not "What is the value of CAP here?" When you're having problems with permissions, you need to see them all because you don't know which one (or ones) are causing the trouble. Seeing them all will help you figure that out. Having to diagnose a problem by probing the capabilities one at a time and looking at little tables would frustrate me and probably most users.
I'm wondering if the suggestion in MDL-13228 is practical or not. Is there a more efficient way of calculating a user's complete set of permissions than calling has_capability() 200 times? How does Moodle figure out which cells to highlight on the override page?
That's a very good idea, and it sounds like it would be fun to do (if only you had time
IMO the question "What are my permissions here?" is THE question that people need answered most, not "What is the value of CAP here?" When you're having problems with permissions, you need to see them all because you don't know which one (or ones) are causing the trouble. Seeing them all will help you figure that out. Having to diagnose a problem by probing the capabilities one at a time and looking at little tables would frustrate me and probably most users.
I'm wondering if the suggestion in MDL-13228 is practical or not. Is there a more efficient way of calculating a user's complete set of permissions than calling has_capability() 200 times? How does Moodle figure out which cells to highlight on the override page?
Duh, of course the permissions of a single role (highlighted on the override page) is completely different from a user's set of permissions, and much easier to calculate. What was I thinking?
By the way, it looks like MDL-13538 is a duplicate of MDL-13228. Someone attached a patch to the former that computes all of a user's capabilities. And yes, it makes 200 calls to has_capability
:
+foreach($caps as $cap) {
+ if (has_capability($cap->name, $testedcontext, $user->id)) {
+ $hascaps[$cap->name] = $cap;
+ }
By the way, it looks like MDL-13538 is a duplicate of MDL-13228. Someone attached a patch to the former that computes all of a user's capabilities. And yes, it makes 200 calls to has_capability
+foreach($caps as $cap) {
+ if (has_capability($cap->name, $testedcontext, $user->id)) {
+ $hascaps[$cap->name] = $cap;
+ }
Tim and others,
I wrote the code that displays the permission table. It's only a prototype, but it works just fine and it's very easy to use. Code is attached to MDL-13228. I started a new discussion for questions and feedback. Have fun
I wrote the code that displays the permission table. It's only a prototype, but it works just fine and it's very easy to use. Code is attached to MDL-13228. I started a new discussion for questions and feedback. Have fun
Thanks for this very good article
I just have one question : does it apply to Moodle 1.9 only, or 1.8 and 1.9 (because you say "This is why role assignments and overrides no longer have delayed effects, as they did in Moodle 1.7.") ?
Séverin
I just have one question : does it apply to Moodle 1.9 only, or 1.8 and 1.9 (because you say "This is why role assignments and overrides no longer have delayed effects, as they did in Moodle 1.7.") ?
Séverin
The statement applies to Moodle 1.8 and beyond. The algorithm was changed in 1.8 to compute permissions on demand. In 1.7, permissions were cached, resulting in the delayed effect. Since 1.8, a user no longer needs to log out and log back in for a role assignment or override take effect.
Hi John,
Regarding whether a user needs to logout then login for a role change to take effect, as far as I know, this is still necessary in Moodle 1.8 - it's only in 1.9 onwards that role changes are immediate.
Regarding whether a user needs to logout then login for a role change to take effect, as far as I know, this is still necessary in Moodle 1.8 - it's only in 1.9 onwards that role changes are immediate.
Thanks, Helen. I changed the article to say that.
It was the sense of my question, before modifying (the french version)
I understand that Rules & Permissions have changed for 1.9.
Could the wise, awe-inspiring, guru's who did this please give some details re how roles & permissions work in 1.9? What can we expect?
Thanks,
Sandy Wagner
And the calculation performed should not have changed between 1.7 and 1.9. However, I believe that John wrote the article looking at the 1.9 code, and we are now fairly confident it is right. Whether the code in 1.8 and 1.7 is completely bug free in all cases is anybody's guess.
Hi Tim,
I wrote that function you suggested, and worked up a crude user interface for it. It was my first php programming exercise, and my brain hurts. But so far it confirms what I wrote in the article. I want to play with it some more to be sure. Then I'll post it as an attachment to MDL-13228.
The function takes a capability, a context level, and an instance id. Originally, it also took a userid, but I ran into the following issue. Since access data below course level is loaded only when needed, and since I could not find any function in accesslib that loads ALL permission data for given userid, the function assumes the current user. If you (as say, admin) want to diagnose a problem that one of your users is having, you must log in as the user (I wouldn't trust switch roles for this), then attempt to do whatever the user was trying to do in order to load the necessary access data, then ask for the table. This will also be an issue for a more general "View permissions" solution.
I wrote that function you suggested, and worked up a crude user interface for it. It was my first php programming exercise, and my brain hurts. But so far it confirms what I wrote in the article. I want to play with it some more to be sure. Then I'll post it as an attachment to MDL-13228.
The function takes a capability, a context level, and an instance id. Originally, it also took a userid, but I ran into the following issue. Since access data below course level is loaded only when needed, and since I could not find any function in accesslib that loads ALL permission data for given userid, the function assumes the current user. If you (as say, admin) want to diagnose a problem that one of your users is having, you must log in as the user (I wouldn't trust switch roles for this), then attempt to do whatever the user was trying to do in order to load the necessary access data, then ask for the table. This will also be an issue for a more general "View permissions" solution.
Tim,
Re your new material on "Getting the result you expect:" I agree that something like this is needed. But I think it's premature to express them as "rules" or even guidelines. The way you use roles and the way someone else uses them may be completely different (more about this below).
Meanwhile, I made one small change. Under When defining roles I changed
to
Re your new material on "Getting the result you expect:" I agree that something like this is needed. But I think it's premature to express them as "rules" or even guidelines. The way you use roles and the way someone else uses them may be completely different (more about this below).
Meanwhile, I made one small change. Under When defining roles I changed
use Not set (N) for things you don't want the role to be able to do
to
use Not set (N) for things you don't care about (which should include most things)
I think the differences in wording are a clue to how we may think differently about roles. IMO new roles should be extremely reusable, and there should be very few of them -- certainly no more than 10. The fewer permissions that are set in a role, the more flexibility users have in combining it with other roles, hence the more reusable it is. For me, "Not set" really does mean "don't care," and the ultimately-reusable role would have all permissions Not set because I don't care what you do with them! I suppose it boils down to whether the admin is an autocrat or a libertarian. Anyway, "roles methodology" is a wide open subject and needs a lot more discussion and should eventually have one or more articles of its own.
I wasn't particularly happy about the work 'rule'. It is rule as in rule-of-thumb, not rule as in law. However, it is a nice short word and I can't currently think of a better one.
This whole 'suggestions for how to configure roles may actually be better on a separate page.
There was another point I wanted to make in this section but could not find the right words. That is that there are two common types of roles:
1. Full roles. Like student or Teacher. These defines a complete set of permissions, and you can happily work in Moodle if you just have that role.
2. Modifier roles. For example Forum moderator. These are roles that just set a few capabilities and you expect them to be used in in combination with a full role, for example to give a specific Student a bit more power in one particular forum.
Finally, I don't like your one small change. The point is, when you are defining a full role, you don't think 'I don't care whether Teachers should be able to override roles'. You think 'I don't want teachers to be able to override roles'. So my wording is better for Full roles. Ah, but your wording is better for Modifier roles.
This whole 'suggestions for how to configure roles may actually be better on a separate page.
There was another point I wanted to make in this section but could not find the right words. That is that there are two common types of roles:
1. Full roles. Like student or Teacher. These defines a complete set of permissions, and you can happily work in Moodle if you just have that role.
2. Modifier roles. For example Forum moderator. These are roles that just set a few capabilities and you expect them to be used in in combination with a full role, for example to give a specific Student a bit more power in one particular forum.
Finally, I don't like your one small change. The point is, when you are defining a full role, you don't think 'I don't care whether Teachers should be able to override roles'. You think 'I don't want teachers to be able to override roles'. So my wording is better for Full roles. Ah, but your wording is better for Modifier roles.
Tim,
"How to configure roles" is a book, not a page
Re full and modifier roles: it boils down to what I said about your orientation as an administrator. In a fledgling roles environment, the admin should be an autocrat. He should not allow other users to override roles, and he should provide a collection of full roles (I'd call them fat roles) for them to assign: the predefined, plus a few others like Parent. But in an environment where every one is a roles "super-user," the admin should be more of a libertarian. This is where the modifier roles (or mixin roles, as I call them) become important; users can override, and you won't see any fat roles except for the predefined roles.
In practice, you need both models at the same time. You have some roles super-users and some roles novices. You want to give flexibility to the super-users and you want to put a straight-jacket on the novices.
I think we have the same view on this, but using different terminology (full = fat, modifier = mixin). Also, my ideas on mixins are probably more radical than providing a Forum moderator role to be used in combination with Student. Think about what a teacher could do with a role having all capabilities Not set if she could override that role. Now think about what she could do with ten of them.
"How to configure roles" is a book, not a page
Re full and modifier roles: it boils down to what I said about your orientation as an administrator. In a fledgling roles environment, the admin should be an autocrat. He should not allow other users to override roles, and he should provide a collection of full roles (I'd call them fat roles) for them to assign: the predefined, plus a few others like Parent. But in an environment where every one is a roles "super-user," the admin should be more of a libertarian. This is where the modifier roles (or mixin roles, as I call them) become important; users can override, and you won't see any fat roles except for the predefined roles.
In practice, you need both models at the same time. You have some roles super-users and some roles novices. You want to give flexibility to the super-users and you want to put a straight-jacket on the novices.
I think we have the same view on this, but using different terminology (full = fat, modifier = mixin). Also, my ideas on mixins are probably more radical than providing a Forum moderator role to be used in combination with Student. Think about what a teacher could do with a role having all capabilities Not set if she could override that role. Now think about what she could do with ten of them.