LEGACY roles and capabilities - what does that mean?

LEGACY roles and capabilities - what does that mean?

by Bente Olsen -
Number of replies: 28
Picture of Testers Picture of Translators
I continue to be confused about the term "legacy". Right now I discovered that LEGACY (often with capitals) is used not only connected to roles but to capabilities too.
What is the meaning by using this term, and especially what is the meaning in the two contexts, roles and capabilities?

The only place in the user interfase where the word is used, is on the page
Frontpage ► Administration ► Users ► Permissions ► User policies:

"Role for guest guestroleid
This role is automatically assigned to the guest user. It is also temporarily assigned to not enrolled users when they enter course that allows guests without password. Please verify that the role has moodle/legacy:guest and moodle/course:view capability."
(yourdomain.tld/admin/settings.php?section=userpolicies)

Besides that it is used in the documentation: docs.moodle.org/ search=legacy

Greg Lyon's interpretation is "Roles are aggregates of many capabilities." And that is how I understood it until now, but I am not so sure anymore. Anyway, if that is what they are, then the only reason to build a new role on another, should be for your own convenience, that you want the new one to be a little different from the one you use as template. If I want to create eg. a secretary I can modify a copy of any other role until I am satisfied. If that is correctly understood you might as well use the term standard roles instead of legacy roles? (Then my confusion would be over, I guess, and I have an meaningful word for translation).

On every page in the documentation (eg. Capabilities/moodle/legacy:guest) that describes each legacy role you can read:
"Note: It is not necessary to to allow any legacy capabilities unless using old 3rd party code that was not designed for Moodle 1.7 and doesn't yet support roles."
This simply makes no sense to me, what does it mean? And which type of capabilities exists besides the legacy type?
Average of ratings: -
In reply to Bente Olsen

Re: LEGACY roles and capabilities - what does that mean?

by John Isner -

Legacy capabilities have been a huge source of confusion for Moodle administrators. The first thing to make clear is this: Legacy capabilities have nothing to do with the Predefined roles.

Legacy capabilities are a device created by developers to allow legacy code (i.e., code that has not been fully migrated to the new Roles and Capabilities system) to continue to function under the Roles and Capabilities system.

With my limited understanding of Moodle internals, I will try to explain how Legacy capabilities work. Prior to Moodle 1.7, Moodle would either do something or refuse to do something depending on a user's role: student, teacher, administrator, and so-on. If a user tried to attempt a quiz, for example, Moodle would (internally) ask isstudent(user) ("Is this user a student?") before permitting the quiz attempt, since only students were allowed to attempt quizzes under the old fixed roles system. Under the new Roles and Capabilities system, the equivalent question would be "Does this user have a capability 'Attempt quizzes' with the value Allow?" The full story is more complicated, thanks to multiple assignments and overrides, but I hope you get the idea.

Migrating Moodle to Roles and Capabilities was (and continues to be) a huge undertaking. It was not possible to complete the migration in time for Moodle 1.7. So What about the code that couldn't be fully migrated? It had to be at least partially migrated to keep it functioning, since questions like "Is this user a student?" were no longer valid questions. As a minimum, such questions had to be recoded, and the replacement code needed to be simple because of the time constraint. Legacy capabilities provided the solution.

More internals: Under Roles and Capabilities, Moodle can ask if a role has a particular capability. Specifically, Moodle can ask "Does this user have a role that has an X capability?". Notice that the value of the X capability (Allow, Prevent, etc.) is unimportant, but only its presence or absence of the capability in the role. I call a capability that is used this way a "marker capability."

A Legacy capability is an extra capability in a role that is used as a marker. For example, the predefined Teacher role contains the legacy capability LEGACY ROLE:Teacher. Everywhere that Moodle used to ask "is this user a teacher?" the code was changed to ask "does this user have a role that contains the capability LEGACY ROLE:Teacher?" Remember that these tests can only be found in code that has not been fully migrated. When the code has been fully migrated, legacy capability tests will be replaced by tests of specific capabilities (such as Attempt quiz = Allow). Eventually all of the legacy code tests have been replaced, and Moodle will no longer need legacy capabilities.

When you define a new role (either from scratch or by copying an existing role), or when you edit an existing role, you are allowed to select from a dropdown list labeled Legacy role type. If you remove the default Legacy capability from Guest, setting it to None, you will see some interesting results, since the tests that rely on the legacy capability will fail and the normal capabilities will take over.

As of version 1.9, Moodle still contains a fair number of of "legacy code" (code that relies on legacy capabilities) in both core and non-core modules. From what I can see, most the tests are isguest() tests. For example, the Forum module still tests for the legacy capability LEGACY ROLE:Guest to determine whether a user should be allowed to start new discussions or reply to posts. This can be frustrating if you've allowed those capabilities for Guest but you keep getting "Sorry, Guests can't post." Want to allow Guests to post to a forum? Fine. Remove the Legacy capability from Guest and override Can start discussions in the forum context. Boom. You're in.

Unfortunately, the legacy capability dropdown is only seen by the administrator, so teachers can't play with the legacy capability in a course context. That's probably by design, not an oversight.

HTH

Average of ratings: Useful (1)
In reply to John Isner

Ang: Re: LEGACY roles and capabilities - what does that mean?

by Bente Olsen -
Picture of Testers Picture of Translators
Thank you very much, now I am getting to understand that a role can be a role, a capability and an aggregate of capabilities and how! It took it's time, but your explanation lightened things up. I even see why "It is not necessary to allow any legacy capabilities unless using old 3rd party code that was not designed for Moodle 1.7 and doesn't yet support roles"!
Average of ratings: -
In reply to Bente Olsen

Re: Ang: Re: LEGACY roles and capabilities - what does that mean?

by John Isner -
Hi Bente,
You wrote

It is not necessary to allow any legacy capabilities unless using old 3rd party code that was not designed for Moodle 1.7 and doesn't yet support roles

and I believe you are quoting from the Moodle docs. However the statement is simply not true. As I pointed out, there is plenty of what I would call "Legacy code" remaining in the core of Moodle. I counted at least a hundred calls to isguest(), isstudent() etc in core code (mostly isguest()). So setting the Legacy capability to None in Guest will change behavior in core Moodle, not just 3rd party code. For example the Forum module denies Guests from posting even if capabilities like Start discussions and Reply to posts have been set to Allow in the Guest role. This is because Forum continues to test the legacy capability LEGACY Role:Guest through a call it isguest(). Set the legacy capability to None and Guests will be able to post to the forum.

I'm not a developer, so I don't know the thinking that went into retaining these legacy calls in core code. I'm sure it was a balancing act -- trying to make the transition to 1.7 as smooth as possible by making the new roles behave exactly like the old roles, and when that couldn't be done easily with a new role, they decided to fall back on the old legacy role.
Average of ratings: Useful (1)
In reply to John Isner

Ang: Re: Ang: Re: LEGACY roles and capabilities - what does that mean?

by Bente Olsen -
Picture of Testers Picture of Translators
Hi John!

Thanks for getting back on this - though you between the lines tell me that I do not understand ;-(

But OK now, I see what you mean, in fact I already have been into the "guest trap". Actually I must admit that I didn't read the words as they are, but as I understand it, that "it is not by default necessary to allow any legacy..."

Besides, I totally agree with Matt Campbell, you have provided a really good explanation. It deserves a place in the documentation. Thanks!
Average of ratings: -
In reply to Bente Olsen

Re: Ang: Re: Ang: Re: LEGACY roles and capabilities - what does that mean?

by John Isner -
Hi Bente,
You wrote "between the lines tell me that I do not understand." I re-read it, and you are right, it does sound that way! I just copied and pasted the text from something I'm writing, so it wasn't aimed at you personally.

These are just my opinions, based on reading of code and experimenting. I write things like this hoping a developer will enter the discussion and give a more correct explanation. For example, I say that legacy capabilities will eventually be phased out, but maybe developers see some lasting value in them (ugh).

There is one thing worse than the isguest trap. It is when the code tests for the guest account. You can't beat those tests by removing the legacy capability LEGACY:Guest. I didn't count how many such tests there are, but I know of at least one (in Quiz).
Average of ratings: -
In reply to John Isner

Ang: Re: Ang: Re: Ang: Re: LEGACY roles and capabilities - what does that mean?

by Bente Olsen -
Picture of Testers Picture of Translators
Hi John
I know you didn't refer to my (lack of) understanding, I attempted to make a joke, which could have come out clearer. Well, I'll continue practising so my next attempt hopefully will be a bit more enjoyable smile

Apropos the "guest trap", I was trapped in connection with the quiz module.

Anyway, I just looked at the documentation for the guest role again (which is similar to the other roles) and must say that the last two bullets are hard to understand:
  • This does NOT provide a role with all capabilities of a pre-Moodle 1.7 guest. All guest capabilities must be individually allowed.
  • Note: It is not necessary to to allow any legacy capabilities unless using old 3rd party code that was not designed for Moodle 1.7 and doesn't yet support roles.
I can't see what can be the reason why they don't contradict each other, which they probably don't. So all though I've got a far better insight in the role system now, I still find it hard to understand the documentation.
Average of ratings: -
In reply to Bente Olsen

Re: Ang: Re: Ang: Re: Ang: Re: LEGACY roles and capabilities - what does that mean?

by John Isner -
The documentation you refer to is for the legacy capability, moodle/legacy:guest.

The first bullet (I admit it is worded confusingly) means that by including this capability in role R (using the Legacy role dropdown), you do not make R "guest-like." Remember that legacy:guest is only used to pick up little bits of guest-like behavior here and there (e.g., in 3rd party code and some core code), but most of the behavior of R will be determined by its normal capabilities.

The second bullet would be true if all calls to isguest() had been removed from core code. However this is not the case. There are 100 calls to isguest() in core code. So removing legacy:guest from R = Guest (for example) will actually change the behavior of the Guest role. My favorite example is that if you Allow "Can start discussions" in Guest, it has no effect UNTIL you remove legacy:guest from Guest. Then Guests can happily start discussions.
Average of ratings: -
In reply to John Isner

Ang: Re: Ang: Re: Ang: Re: Ang: Re: LEGACY roles and capabilities - what does that mean?

by Bente Olsen -
Picture of Testers Picture of Translators
Thanks again & oh yeah, of cause. My brain hadn't got used to my new understanding yet!
Average of ratings: Useful (1)
In reply to John Isner

Re: Ang: Re: LEGACY roles and capabilities - what does that mean?

by Alan Zaitchik -
John,
Your note is the best explanation of roles and capabilities around, so I hope you won't mind my hitch-hiking on it to ask a related question.
First off, I am using Moodle 1.9.3 (various recent builds from December 08).
I am auto-creating courses and assigning roles using the external database plugin. The course template is set to "not visible" so students won't be able to access it until the instructor manually makes it available. The external database returns a role of 'student' for students and 'editingteacher' for instructors, as I can see by querying the Moodle database. E.g.

SELECT c.visible,c.startdate,r.shortname,rc.contextid,rc.permission,rc.capability,u.username,c.shortname,ra.enrol FROM mdl_user u JOIN mdl_role_assignments ra ON ra.userid = u.id JOIN mdl_role r ON ra.roleid = r.id JOIN mdl_context con ON ra.contextid = con.id JOIN mdl_course c ON c.id = con.instanceid AND con.contextlevel = 50 JOIN mdl_role_capabilities rc ON r.id=rc.id where u.username='jpjones' and c.shortname='CHE201_2008FL_02';

*BUT*
1. The instructor has a 'capability' of 'moodle/legacy:editingteacher'. Does this mean that the external database plugin has not been fully integrated with the roles and capabilites system?
2. Despite the above, the instructor cannot access the course until I set the course to "available" to students! This makes me wonder if the legacy role has the right capability.
Needless to say what I care about is only the instructor's ability to edit the course and eventually make it available to students, without involvement by the admin, not the internals by which this happens.
All help much appreciated.
Alan
PS/ I posted the substance of this question elsewhere in Using Moodle (the Enrolment Plugins forum) but so far have got no response.
Average of ratings: -
In reply to Alan Zaitchik

Re: Ang: Re: LEGACY roles and capabilities - what does that mean?

by Tim Hunt -
Picture of Core developers Picture of Documentation writers Picture of Particularly helpful Moodlers Picture of Peer reviewers Picture of Plugin developers
1. No. the legacy capabilities are internal to Moodle. Just ignore them.

2. This problem is not related to 1.

I think the instructor needs a combination of moodle/course:view and moodle/course:viewhidden, or something like that.

The logic for whether the current user can get into a course is contained in the require_login function in lib/moodlelib.php.
Average of ratings: -
In reply to Tim Hunt

Re: Ang: Re: LEGACY roles and capabilities - what does that mean?

by Alan Zaitchik -
The external database table returns the string "editingteacher" for the instructors. Wouldn't the assignment of the role "editingteacher" automatically grant the capabilities for getting into a course whose visible setting is false? I am pretty sure that this is what I recall from earlier Moode sites, but maybe I am wrong...

This is the weekly build of 1.9.3 from the 24th December. Is it possible there is a bug that has crept into this build?

Thanks,

Alan
Average of ratings: -
In reply to Alan Zaitchik

Re: Ang: Re: LEGACY roles and capabilities - what does that mean?

by Tim Hunt -
Picture of Core developers Picture of Documentation writers Picture of Particularly helpful Moodlers Picture of Peer reviewers Picture of Plugin developers
A bug is possible.

Assigning someone as an editing teacher should let them in to the course.

One think to test would be to manually assign a test user as a teacher in a course, and check that works.

If you get completely stuck, one (rather extreme) option would be to make a copy of your site, upgrade it to Moodle 2.0 dev version, and use some of the diagnostic tools there to discover what is going on with the permissions.
Average of ratings: -
In reply to Tim Hunt

Re: Ang: Re: LEGACY roles and capabilities - what does that mean?

by Alan Zaitchik -
Tim,

Since installing Moodle 2 is not an option at this point, I took your suggestion of manually creating an editingteacher account ('test001') and manually assigning the editingteacher role to this account for the course in question. Unfortunately this account was also unable to see the course after login!

In case you (or another Moodle guru reading this thread) has time to think about this, I am attaching the XML output that shows both accounts are editingteachers in the course and the sql query used to get that output. I have also determined through the course's administration ("Assign roles") interface that Moodle sees the two accounts as "Teachers (editing)" and that in general (Users>Permissions>Define Roles) the Teacher (editing) role has the capability "View hidden courses".

I will also post this query in the Enrolment Plugins forum.

Alan

Average of ratings: -
In reply to Tim Hunt

Re: Ang: Re: LEGACY roles and capabilities - what does that mean?

by Alan Zaitchik -
I tried the same experiment with a 1.9.3 build from 20081210 and the editingteacher account I created (manually) was able to access the hidden course to which I (manually) assigned it as an instructor.
I don't see this as a bug in Tracker. DO you think I should submit it?
Alan
Average of ratings: -
In reply to Alan Zaitchik

Re: Ang: Re: LEGACY roles and capabilities - what does that mean?

by Tim Hunt -
Picture of Core developers Picture of Documentation writers Picture of Particularly helpful Moodlers Picture of Peer reviewers Picture of Plugin developers
The thing is, we don't yet know whether the bug is with the particular version of Moodle, or with the configuration of your Moodle site.

I just tested on my latest 1.9.3+ test site, and an editing teacher can access a hidden course.

So before filing a tracker bug, you need to spend more time investigating the changes you have made to the default configuration to determine the cause more precisely.

Things to check:
  1. Have you changed the permissions for any other capabilities on the editing teacher or logged in user roles?
  2. Do these users have any other roles assigned at the site, category or course level?
  3. Are the permissions for any of these roles overridden at the category or course level?
Average of ratings: -
In reply to Tim Hunt

Re: Ang: Re: LEGACY roles and capabilities - what does that mean?

by Alan Zaitchik -
Well, I retried everything using a build from 2008-12-10 and found that the instructor I created (through LDAP Synchronization) and assigned as an editingteacher to the course-section in question (through External DB plugin) does not see the link to the course. The same turned out to be true, however, even for a "test" account I manually created as an editingteacher and manually assigned as an editingteacher to the course, contrary to what I was sure I saw the other day. (Too much New Year's alcohol??) Nonetheless, the instructor (as well as the test account) are both listed as instructors for the course in the display that an admin can see, and this is what the MySQL database clearly returns when queried.

So probably the culprit is something I am doing in setting up the site rather than a bug in the latest build of 1.9.3, as you observe.

If you are willing to read on, please consider this.

In the Site Administration Users > Permissions > Define Roles I can see that the editing teacher ("Teacher") has no capabilities explicitly denied, and indeed explicitly has granted the capabilities of seeing hidden courses and sections etc. I do note that the editingteacher does not explicitly have granted the capability of seeing hidden Categories, so would have to inherit this from somewhere (I assume)-- and so I thought that maybe the "Miscellaneous" category is hidden for some reason. BUT I do not know how to check this, nor yet how to change the editingteacher's capability to see hidden categories (if I need to change this, i.e. if the Miscellaneous category is indeed hidden and the source of the problem).

If I look at the Front Page settings I see that I have the default value (NO) for the option "Allow visible courses in hidden categories". I do not know how this might be relevant, however. Also, Front Page roles are not assigned to any account. From the little I understand I believe that I would NOT want to assign a Front Page role of any capabilities to all instructors. Also not sure that this is relevant to the problem.

In general I have not knowingly changed any roles at any level. I simply had the external database return 'student' or 'editingteacher' as appropriate, and create courses using a template course prepared for this purpose. The template course is set to hidden, as it must be, and is created in the "Miscellaneous" category. I did not change the visibility of the category; indeed I do not know where to determine its visibility nor where to change it.

Can you suggest to me how to follow up with more steps? Thanks so much!

Alan
Average of ratings: -
In reply to John Isner

Re: LEGACY roles and capabilities - what does that mean?

by Matt Campbell -
Thanks, John, for this great explanation of what LEGACY means and what it's for!

Thanks,
Matt
Average of ratings: -
In reply to Matt Campbell

Re: LEGACY roles and capabilities - what does that mean?

by Paul 'Fire' Preibisch -
Hi everyone,

I am coding a module, and need to know, what capabilities do I check against to see which users of the full user list are teachers of the class?
Average of ratings: -
In reply to Paul 'Fire' Preibisch

Re: LEGACY roles and capabilities - what does that mean?

by Paul 'Fire' Preibisch -
I think I figured it out myself - and built this function....

function is_teacher($userid){

if (has_capability('moodle/course:manageactivities', $this->courseContext, $userid)) {
return true;
}
else return false;


}

Average of ratings: -
In reply to Paul 'Fire' Preibisch

Re: LEGACY roles and capabilities - what does that mean?

by Tim Hunt -
Picture of Core developers Picture of Documentation writers Picture of Particularly helpful Moodlers Picture of Peer reviewers Picture of Plugin developers
You will notice that is_teacher is a deprecated function. Meaning you should not use it. It is only there so old code can keep on working.

In your code, you need to stop thinking about roles, and start thinking about capabilities. What is it that you want only teacher, and not students, to do? Perhaps it is viewing reports. So you should create a capability mod/mymodule:viewreports, and say that by default teachers have it and students don't. Then in your code, wherever something releates to reports, you do

$context = get_context_instance(CONTEXT_MODULE, $cm->id);
if (has_capability('mod/mymodule:viewreports', $context)) {
// ...
}

That way, you module works the way you want by default, but if somebody want to vary the rules for who can do what, they can do it just by configuring roles, without having to hack the code.
Average of ratings: -
In reply to John Isner

Letting Guests do Quizzes, etc. was Re: LEGACY roles and capabilities - what does that mean?

by Glenys Hanson -
Hi there,

I realise this is an old thread, but John Isner seems to be explaining what I want to do
  • "As of version 1.9, Moodle still contains a fair number of of "legacy code" (code that relies on legacy capabilities) in both core and non-core modules. From what I can see, most the tests are isguest() tests. For example, the Forum module still tests for the legacy capability LEGACY ROLE:Guest to determine whether a user should be allowed to start new discussions or reply to posts. This can be frustrating if you've allowed those capabilities for Guest but you keep getting "Sorry, Guests can't post." Want to allow Guests to post to a forum? Fine. Remove the Legacy capability from Guest and override Can start discussions in the forum context. Boom. You're in."
I'm in the process of creating a course whose objective is to show new teachers what Quiz, Test, Questionnaire, etc. can be used for. I'd like them to be able to access the course and try some activities out as Guests without necessarily having to log in.

I've removed the Legacy capability from Guest (as admin at site level) and overriden, at course level, for example, in Quiz:

mod/quiz:attempt
mod/quiz:view
mod/quiz:preview

But Guests still cannot attempt a Quiz though they can see it and even Preview it (if as newbies they're savvy enough to do that).

For some Activities, everything works as I would expect after I've done the overides at course level: Guests can do Hot Potatoes and Questionnaires no problem.

I'm testing in 1.9.8 and 1.9.9.

Any help appreciated.

Glenys
Average of ratings: -
In reply to Glenys Hanson

Re: Letting Guests do Quizzes, etc. was Re: LEGACY roles and capabilities - what does that mean?

by Susan Mangan -
We ran into problems with this as well. We were able to allow Guests to do a quiz but it was 'clunky' (eg, some error messages would still pop up re: not being allowed to do things...) so, I could be wrong, but I think that unless you want to do some manually hacking, even with role overrides, the "Guest" role might not be able to do all you want it to do.

What we did in the end was create a separate manual account that would represent the 'Guest' user. Kind of like a demo account. This new account would have full student privileges in new courses and many people could use it.
Average of ratings: -
In reply to Susan Mangan

Re: Letting Guests do Quizzes, etc. was Re: LEGACY roles and capabilities - what does that mean?

by Glenys Hanson -
Hi Susan,

Thanks for the speedy reply but could you enlarge a bit? How does a "passer by" access the "separate manual account"? I'm thinking of teachers with little or no experience of Moodle (or other CMSs) who more or less happen on the course and start to click around. I'm thinking of my very non-techie language teaching colleagues.

Cheers,
Glenys
Average of ratings: -
In reply to Glenys Hanson

Re: Letting Guests do Quizzes, etc. was Re: LEGACY roles and capabilities - what does that mean?

by Susan Mangan -
You could post the generic id and password on your Moodle home page with a little blurb about the demo course. You could link directly to the demo course here as well.

... or are you wanting an account to be able to access ALL/ANY course(s)?

For our purposes we just have one or more 'specific' courses that will be used by the 'generic' account. I can't imagine how you would do that for all the courses... unless you had no enrolment keys and just opened everything up.
Average of ratings: -
In reply to Susan Mangan

Re: Letting Guests do Quizzes, etc. was Re: LEGACY roles and capabilities - what does that mean?

by Glenys Hanson -
Hi Susan,

What I'm trying to achieve is to avoid them having to log in at all for certain courses (understanding how to log in to Moodle is a very difficult for many non techie people). I know how to achieve this (no log in for Guests) but I don't know how to make certain activities available to them. No, I don't want them to be able to write in forums, wikis, blogs, etc., but why can they participate in some activities and not in others: Hot Potatoes and Quiz are rather similar so why can they do Hot Potatoes quizzes but not Quiz ones? Questionnaire and Feedback are also similar but again Guests can fill in a Questionnaire but not a Feedback.

Maybe someone else can help? thoughtful

Cheers,
Glenys
Average of ratings: -
In reply to Glenys Hanson

Re: Letting Guests do Quizzes, etc. was Re: LEGACY roles and capabilities - what does that mean?

by Susan Mangan -
hmm I see your conundrum ... we also use the no log in for Guests. I would be interested in a solution for this myself smile

You might want to check out and vote for: http://tracker.moodle.org/browse/MDL-17892

...oh and here is a brief explanation as to the "why" http://docs.moodle.org/en/Quiz_FAQ#Why_can.27t_people_.28guests.29_take_a_quiz_without_creating_an_account_and_logging_in.3F
Average of ratings: -
In reply to Susan Mangan

Re: Letting Guests do Quizzes, etc. was Re: LEGACY roles and capabilities - what does that mean?

by Glenys Hanson -
Thanks a lot Susan. I've been and voted for MDL-17892 but I doubt if anything is going to happen in the run up to version 2.

We hear a lot about how few of us there are who propose courses that are more than just repositories for documents, and those of us that do find it difficult to show what it's possible to do. As I see it, a constructivist course is all about what the participants do, not the empty framework the teacher creates. My courses are by no means models - they're often quite messy, but they do encourage people to do things. I'm also frustrated because I'm sure there other people out there doing great things that I can't see because of these technical problems. Rant! Rant!

Cheers,
Glenys
Average of ratings: -