Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Enrolment plugins: Difference between revisions

From MoodleDocs
Line 55: Line 55:
* [[Enrolment API]]
* [[Enrolment API]]
* [[Enrolment usage overview]]
* [[Enrolment usage overview]]
* [[New_enrolments in 2.0]]
* [[New enrolments in 2.0]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] forum
* Using Moodle [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] forum


[[Category:Enrolment]]
[[Category:Enrolment]]
[[Category:Plugins]]
[[Category:Plugins]]

Revision as of 18:27, 26 January 2013

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 available methods and developer documentation.

Course enrolment information is stored in tables enrol and user_enrolments and optionally other custom database tables defined by enrolment plugins. Each plugin has complete control over own instance record and user enrolments, by defaults user enrolments are protected and can not be modified manually by teachers.

Enrolment gives user following privileges:

  • User with active enrolment may enter course, without enrolment user needs 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.

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 bellow may be attached to user enrolments.

User enrolment process

Manual enrolment plugins are the simplest way to handle user enrolments. enrol_flatfile plugin allows automation of enrolment and unernolment actions.

Fully automatic plugins are configured at the system level, they usually synchronise user enrolments with information stored in external systems (ex.: enrol_ldap and enrol_database). Some non-interactive plugins require only configuration of instance (ex.: enrol_cohort).

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 also implement adding and editing of enrol instance.

Enrolment expiration and suspending

Active user enrolment is defined as condition: user has record in user_enrolments AND user enrolment already started AND user enrolment is not past timeend AND user enrolment has active status AND enrol_instance has active status AND enrol plugin is enabled.

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 using cli/sync.php and as part of standard cron.

Time based expiration was fully 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().

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() or enrol_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.

Manual enrolment modifications

Standard user enrolment UI does not use these methods directly, developer needs to describe all possible UI enrolments actions via enrol_plugin::get_user_enrolment_actions().

the following methods are used to describe what modifications are allowed:

  • enrol_plugin::roles_protected() - Protected roles cannot be modified manually by users. Return false if you want to allow users to remove all roles assigned by plugin. Since Moodle 2.5 it is possible to assign roles with component+itemid even if roles are not protected.
  • enrol_plugin::allow_enrol() - Each plugin is responsible for implementing own UI for enrolment see enrol_plugin::get_manual_enrol_link(). externallib methods must respect this property.
  • enrol_plugin::allow_unenrol() and enrol_plugin::allow_unenrol_user() - Is user allowed to unenrol everybody from one instance or one specific user? True is required for course reset and manual user unenrolment. externallib methods must respect this property.
  • enrol_plugin:allow_manage() - Return true if plugin allows manual modification of user enrolments. False is usually returned from plugin that synchronise data with external systems, otherwise the manual changes would be immediately reverted. externallib methods must respect this property.

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 crated 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