Enrolment plugins: Difference between revisions
mNo edit summary |
|||
Line 10: | Line 10: | ||
* Gradebook tracks grades of all enrolled users, visibility of grades is controlled by role membership. | * Gradebook tracks grades of all enrolled users, visibility of grades is controlled by role membership. | ||
Enrolments and role assignments are now separate concepts, you may be enrolled and not have any role and you may have a role in course and not be enrolled. Roles at course context level and | Enrolments and role assignments are now separate concepts, you may be enrolled and not have any role and you may have a role in course and not be enrolled. Roles at course context level and below may be controlled by enrolment plugins. | ||
==User enrolment process== | ==User enrolment process== |
Revision as of 15:38, 17 June 2014
Since Moodle 2.0 all enrolment plugins must extend enrol_plugin base class which is defined at the end of lib/enrollib.php. This base class contains all standard methods together with developer documentation.
Course enrolment information is stored in tables enrol
and user_enrolments
and optionally other custom database tables defined by individual enrolment plugins. Each plugin has complete total over own instance record and user enrolments, by defaults user enrolments are protected and can not be modified manually by teachers.
Enrolment gives users following privileges:
- User with active enrolment may enter course, other users need either temporary guest access right or moodle/course:view capability.
- "My courses" shows list of active enrolments for current user.
- Course participation - some activities restrict participation to enrolled users only. The behaviour is defined independently by each activity, for example only enrolled users with submit capability may submit assignments, the capability alone is not enough.
- Only enrolled users may be members of groups.
- Gradebook tracks grades of all enrolled users, visibility of grades is controlled by role membership.
Enrolments and role assignments are now separate concepts, you may be enrolled and not have any role and you may have a role in course and not be enrolled. Roles at course context level and below may be controlled by enrolment plugins.
User enrolment process
Manual enrolment plugins are the simplest way to handle user enrolments. This simplest plugin is enrol_manual, users with necessary permissions may enrol or unenrol users manually. enrol_flatfile plugin allows automation of enrolment and unernolment actions.
Fully automatic plugins are configured at the system level, they synchronise user enrolments with information stored in external systems (ex.: enrol_ldap, enrol_database and enrol_category). Some non-interactive plugins may require configuration of enrolment instances (ex.: enrol_cohort and enrol_meta).
Interactive enrolment plugins require user interaction during enrolment (ex.: enrol_self and enrol_paypal). These plugins need to override enrol_plugin::show_enrolme_link()
, enrol_plugin::enrol_page_hook()
and to implement adding and editing of enrol instance.
Enrolment expiration and suspending
User has active enrolment if all following conditions are met:
- user has record in
user_enrolments
table, - user enrolment already started,
- user enrolment is not past timeend,
- user enrolment has active status,
- enrol instance has active status in
enrol
table, - enrol plugin is enabled.
Most synchronisation plugins include a setting called External unenrol action. It is used to decide what happens when previously enrolled user is not supposed to be enrolled any more. Synchronisation is usually executed from cli/sync.php or as part of standard cron.
Time based expiration was implemented in Moodle 2.5. Plugins that set timeend in user_enrolments table may want to specify expiration action and optional expiration notification, see enrol_plugin::process_expirations()
and enrol_plugin::send_expiry_notifications()
.
Manual enrolment modifications
The standard user enrolment UI does not use the following methods directly, so developers need to describe all possible UI enrolments actions via enrol_plugin::get_user_enrolment_actions()
. It is very important to obey these restrictions in all externallib methods!
The following methods describe the allowed modifications for each enrolment instance:
enrol_plugin::roles_protected()
- True means that protected roles (nonempty component+itemid) cannot be modified by any other plugin. Return false if you want to allow users to remove all roles assigned by this plugin. Since Moodle 2.5 it is allowed to assign roles with component+itemid even if roles are not protected.enrol_plugin::allow_enrol()
- True means other code may callenrol_plugin::enrol_user()
, false means only plugin may enrol users. Each plugin is responsible for implementing its own UI for enrolment. Seeenrol_plugin::get_manual_enrol_link()
.enrol_plugin::allow_unenrol()
andenrol_plugin::allow_unenrol_user()
- Is other code allowed to unenrol everybody from one instance or one specific user? True is required for course reset and manual user unenrolment.enrol_plugin:allow_manage()
- Return true if plugin allows manual modification of user enrolments from other code. False is usually returned from plugins that synchronise data with external systems, otherwise the manual changes would be reverted immediately upon synchronisation.
Standard capabilities
- enrol/xxx:enrol - Must be defined when
enrol_plugin::allow_enrol()
returns true. - enrol/xxx:unenrol - Must be implemented when
enrol_plugin::allow_unenrol()
orenrol_plugin::allow_unenrol_user()
returns true. - enrol/xxx:manage - Must be implemented when
enrol_plugin::allow_manage()
returns true. - enrol/xxx:unenrolself - Usually implemented when plugin support self-unenrolment.
- enrol/xxx:config - Implemented when plugin allows user to modify instance properties. Automatic synchronisation plugins do not usually need this capability.
Restore support
Enrolment and role restore is supported since Moodle 2.4, earlier versions can restore only manual and self enrolments.
Plugins with automatic synchronisation may use enrol_plugin:restore_sync_course()
hook to synchronise enrolments in newly created courses. The restore process starts with instance restore which must set mapping information enrol_plugin::restore_instance()
(plugins may decide to map enrolments to other plugin type), then plugin must restore users enrolments enrol_plugin::restore_user_enrolment()
, protected roles enrol_plugin::restore_role_assignment()
and protected group membership enrol_plugin::restore_group_member()
.
See also
- Enrolment API
- Enrolment usage overview
- New enrolments in 2.0
- Using Moodle Enrolment Plugins forum