External database enrolment



Using an external database to control enrolments

You may use a external database (of nearly any kind) to control your enrolments. It is assumed your external database contains a field containing a course ID, a field containing a user ID, and optionally a field containing a role. These are compared against fields that you choose in the local course, user tables, and role tables.

The following are the supported data sources, but note that we will need to have to compiled PHP with the appropriate options or through ODBC.

Enrolment and unenrolment

External database enrolment happens at the moment when a user logs into Moodle. The plugin will attempt to automatically enrol the student in all their courses according to the data in the external database and, optionally, create empty courses where they do not already exist. To check if it is working, we can log in as a student and then check that their list of courses is as you would expect.

The process also unenrols users from courses if they are no longer in the database. User records are marked according to their original enrolment method. Therefore the external database plugin can only unenrol users who were enroled by the plugin in the first place.

Hidden courses

Courses that are set to "Course is not available to students" can be ignored for enrolment purposes by setting the "enrol_db_ignorehiddencourse" to yes.

Enrolment and roles

The "enrol_database | defaultrole" setting in the plugin settings page specifies the role that the user will take when they are added to the course. The default setting will set them to the course default setting (initially "student"). However, we can specify a field in the external table (specified in the "enrol_database | remoterolefield" setting) that contains the short name or id for the user's role. This could, for example, be used to enrol both students and teachers into courses using a suitably configured database.


The External unenrol action ("enrol_database | unenrolaction") setting in the plugin settings page defines what action should be taken when a user enrolment disappears from external enrolment source. Each setting does the following:

  1. "Unenrol user from course" When the user disappears from the external source, the enrolment is completely removed and all the roles removed. This means some user data and settings are purged from course during course unenrolment (that usually include grades, activity attempts, etc.)
  2. "Keep user enrolled" When the user disappears from the external source, the enrolment is kept as is, and the user is still able to enter the course and perform activities, access resources, etc. It's a "do nothing" option.
  3. "Disable course enrolment" When the user disappears from the external source, user enrolment is suspended (the user can't access the course, but user data and settings are kept), and roles are kept as is. You might use this because in some cases the user needs a role with some capability to be visible in UI - such has in gradebook, assignments, etc.
  4. "Disable course enrolment and remove roles" When the user disappears from the external source, the enrolment is suspended and roles assigned by enrol instance are removed. Please note that user may "disappear" from gradebook and other areas.

Creating courses

Optionally courses that do not exist in the Moodle site can be created.

We can additionally specify the Category into which the new course will be placed, in the New course category id field. The data in this field must be the id of a currently existing category; it will not create a new category. The id number is number assigned by Moodle in the database when the category is created (e.g. mdl_course_categories.id).

Default new course category is the category to which courses will be assigned and created in, unless you set up and so indicate in the data field of the "New course category id field."

You may also specify a New course template: a "template" course from which the new course will be copied. The data for this field should be the shortname of the template course.

Synchronization script

A script is provided that can synchronize all your user enrollments at once - both adding and removing user enrolments (and creating courses if specified). The script is called sync.php and is found in the enrol/database/cli folder.

This script is meant to be called from a system cronjob to sync moodle enrolments with enrolments in the external database. You need to make sure all the users present in the external enrolments are already created in moodle. If we are using external authentication plugins (db, ldap, etc.) we can use the scripts provided by those plugins to synchronize your users before running this script.

Example cron entry

   # 5 minutes past 4am
   5 4 * * * /usr/bin/php -c /path/to/php.ini /path/to/moodle/enrol/database/cli/sync.php


Setting up enrolment sync (How to)

We will need to perform (as a minimum) the following steps to enable external database enrolment - only a single table is required in the database which contains a record for every user/course combination. If the table is large it is a good idea to make sure appropriate indexes have been created:

Field Mapping Example:

Choose your fields from the Moodle database:

Create a view in your external database which matches the chosen field values from Moodle:

Potential s

Errors and diagnostics

The plugin produces a number of diagnostic messages and/or errors which are recorded to the PHP error log (as defined in the php.ini file). In addition messages about courses that are in the database for the user but that do not exist in the Moodle site will only be produced if debugging is set to ALL or DEVELOPER.

We can get detailed progress information by executing the sync script with -v parameter:

 php /path/to/moodle/enrol/database/cli/sync.php -v

See also