Note: You are currently viewing documentation for Moodle 2.3. Up-to-date documentation for the latest stable version is available here: External database enrolment.

External database enrolment: Difference between revisions

From MoodleDocs
 
(20 intermediate revisions by 14 users not shown)
Line 1: Line 1:
{{Enrolment}}
Location: External database edit settings link in ''Settings > Site administration > Plugins > Enrolments > Manage enrol plugins''
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.
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 you will need to have to compile PHP with the appropriate options or through ODBC.
The following are the supported data sources, but note that you will need to have to compiled PHP with the appropriate options or through [[ODBC]].


*access
*access
Line 47: Line 51:
== Creating Courses ==
== Creating Courses ==


Optionally courses that do not exist in the Moodle site can be created. Switch the "enrol_db_autocreate" option to "yes" in the plugin settings. You can additionally specify the Category into which the new course will be placed and may also specify a "template" course from which the new course will be copied.  
Optionally courses that do not exist in the Moodle site can be created. Switch the "enrol_db_autocreate" option to "yes" in the plugin settings.  
 
You 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).
 
* Do not confuse this ''category id'' with the new custom ''category id number'' field that you can manually assign to a category. (See Trackers http://tracker.moodle.org/browse/MDL-28518 and http://tracker.moodle.org/browse/MDL-31845).
* Leaving the category id data empty means that a course will be assigned to the default category.
* If you assign data to categories that do  not exist already in Moodle, the courses will not be created.
 
'''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 ==
== Synchronization Script ==
Line 55: Line 69:
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 you are using external authentication plugins (db, ldap, etc.) you can use the scripts provided by those plugins to synchronize your users before running this script.
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 you are using external authentication plugins (db, ldap, etc.) you can use the scripts provided by those plugins to synchronize your users before running this script.


Example cron entry:
Example cron entry for Moodle 2.0
    # 5 minutes past 4am
    5 4 * * * /usr/bin/php -c /path/to/php.ini /path/to/moodle/enrol/database/cli/sync.php


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


Notes:
Notes:
Line 65: Line 79:
* This only works for users that already exist in your Moodle site (see comment above)
* This only works for users that already exist in your Moodle site (see comment above)


== Setting It Up (Howto) ==
== Setting up enrolment sync (How to) ==


You 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:
You 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:


* Use an existing database or create a new one. Use an existing or create a new table with the following minimum fields:
* Use an existing database or create a new one. Use an existing table or create a new one with the following minimum fields.
** course identifier (to match unique course identifier in Moodle)
*# A unique course identifier to match one of the following fields.
** user identifier (to match unique user identifier in Moodle)
*#* the "idnumber" field in Moodle's course table (varchar 100), which is manually specified as the "Course ID number" when editing a course's settings
** (optional) role identifier (to match unique role identifier in Moodle)
*#* the "shortname" field in Moodle's course table (varchar 255), which is manually specified as the "Course short name" when editing a course's settings
* Populate the database table. Each user/course combination to have a record in the table
*#* the "id" field in Moodle's course table (int 10), which is based on course creation order
* In Moodle, go to Site Administration => Courses => Enrolments, find External Database in the list and click Settings
*# A unique user identifier to match one of the following fields.
*#* the "idnumber" field in Moodle's user table (varchar 255), which is manually specified as the "ID number" when editing a user's profile
*#* the "username" field in Moodle's user table (varchar 100), which is manually specified as the "Username" when editing a user's profile
*#* the "email" field in Moodle's user table (varchar 100), which is manually specified as the "Email address" when editing a user's profile
*#* the "id" field in Moodle's user table (int 10), which is based on user creation order
*# (optional) A unique role identifier to match one of the following fields.
*#* the "shortnname" field in Moodle's role table (varchar 100), for example editingteacher, coursecreator, student, ...
*#* the "name" field in Moodle's role table (varchar 255), for example Teacher, Course creator, Student, ...
*#* the "id" field in Moodle's role table (int 10), which is based on initial installation and new role creation order
* Populate the database table. Each user/course combination to have a record in the table.
* In Moodle, go to Site administration => Plugins => Enrolments => Manage enrol plugins, find External Database in the list, enable it (click the closed-eye icon) and click Settings.
* In the top panel, select the database type (make sure you have the necessary configuration in PHP for that type) and then supply the information to connect to the database.
* In the top panel, select the database type (make sure you have the necessary configuration in PHP for that type) and then supply the information to connect to the database.
* The middle panel creates the mapping between Moodle and the external database. The first three settings are for the local (Moodle) field names and the last three for the remote (external database) settings. They are in the same order.
* The middle panel creates the mapping between Moodle and the external database. The first three settings are for the local (Moodle) field names and the last three for the remote (external database) settings. They are in the same order.
Line 110: Line 134:
==Errors and Diagnostics==
==Errors and Diagnostics==


The plugin produces a number of diagnostic messages and/or errors. Before Moodle 1.8.3 they were displayed directly to the screen. From 1.8.3 they 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.
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.


==See also==
==See also==
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=49475 MySQL enrolment plugin doesn't seem to work] forum discussion
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=49475 MySQL enrolment plugin doesn't seem to work] forum discussion
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=74133 Someone explain external database enrolment, please??] forum discussion
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=74133 Someone explain external database enrolment, please??] forum discussion
*Example Setup [https://docs.moodle.org/en/Talk:External_database_enrolment#Example_External_Enrollment] Example Database Enrollment Setup


[[Category:Enrolment]]
[[es:Matriculación Base de Datos Externa]]
 
[[fr:Base de données externe]]
[[fr:Base de données externe]]
[[de:Einschreibung über externe Datenbank]]
[[ja:外部データベース登録]]

Latest revision as of 17:12, 17 July 2012

Location: External database edit settings link in Settings > Site administration > Plugins > Enrolments > Manage enrol plugins


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 you will need to have to compiled PHP with the appropriate options or through ODBC.

  • access
  • ado
  • mssql
  • borland_ibase
  • csv
  • db2
  • fbsql
  • firebird
  • ibase
  • informix72
  • informix
  • mysql
  • mysqlt
  • oci805
  • oci8
  • oci8po
  • odbc
  • odbc_mssql
  • odbc_oracle
  • oracle
  • postgres64
  • postgres7
  • postgres
  • proxy
  • sqlanywhere
  • sybase
  • vfp

Enrolment & 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, you 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 & Roles

The "enrol_db_defaultcourseroleid" 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, you can specify a field in the external table (specified in the "enrol_db_remoterolefield" setting) that contains the short name for the user's role. This could, for example, be used to enrol both students and teachers into courses using a suitably configured database.

Creating Courses

Optionally courses that do not exist in the Moodle site can be created. Switch the "enrol_db_autocreate" option to "yes" in the plugin settings.

You 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).

  • Do not confuse this category id with the new custom category id number field that you can manually assign to a category. (See Trackers http://tracker.moodle.org/browse/MDL-28518 and http://tracker.moodle.org/browse/MDL-31845).
  • Leaving the category id data empty means that a course will be assigned to the default category.
  • If you assign data to categories that do not exist already in Moodle, the courses will not be created.

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 enrol_database_sync.php and is found in the enrol/database 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 you are using external authentication plugins (db, ldap, etc.) you can use the scripts provided by those plugins to synchronize your users before running this script.

Example cron entry for Moodle 2.0

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


Notes:

  • If you have a large number of enrolments, you may want to raise the memory limits by passing -d memory_limit=256M
  • For debugging & better logging, you are encouraged to use in the command line: -d log_errors=1 -d error_reporting=E_ALL -d display_errors=0 -d html_errors=0
  • This only works for users that already exist in your Moodle site (see comment above)

Setting up enrolment sync (How to)

You 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:

  • Use an existing database or create a new one. Use an existing table or create a new one with the following minimum fields.
    1. A unique course identifier to match one of the following fields.
      • the "idnumber" field in Moodle's course table (varchar 100), which is manually specified as the "Course ID number" when editing a course's settings
      • the "shortname" field in Moodle's course table (varchar 255), which is manually specified as the "Course short name" when editing a course's settings
      • the "id" field in Moodle's course table (int 10), which is based on course creation order
    2. A unique user identifier to match one of the following fields.
      • the "idnumber" field in Moodle's user table (varchar 255), which is manually specified as the "ID number" when editing a user's profile
      • the "username" field in Moodle's user table (varchar 100), which is manually specified as the "Username" when editing a user's profile
      • the "email" field in Moodle's user table (varchar 100), which is manually specified as the "Email address" when editing a user's profile
      • the "id" field in Moodle's user table (int 10), which is based on user creation order
    3. (optional) A unique role identifier to match one of the following fields.
      • the "shortnname" field in Moodle's role table (varchar 100), for example editingteacher, coursecreator, student, ...
      • the "name" field in Moodle's role table (varchar 255), for example Teacher, Course creator, Student, ...
      • the "id" field in Moodle's role table (int 10), which is based on initial installation and new role creation order
  • Populate the database table. Each user/course combination to have a record in the table.
  • In Moodle, go to Site administration => Plugins => Enrolments => Manage enrol plugins, find External Database in the list, enable it (click the closed-eye icon) and click Settings.
  • In the top panel, select the database type (make sure you have the necessary configuration in PHP for that type) and then supply the information to connect to the database.
  • The middle panel creates the mapping between Moodle and the external database. The first three settings are for the local (Moodle) field names and the last three for the remote (external database) settings. They are in the same order.
    • enrol_localcoursefield / enrol_remotecoursefield - in Moodle the name of the field in the course settings the uniquely identifies the course (e.g., idnumber). In the external database the name of the matching field.
    • enrol_localuserfield / enrol_remoteuserfield - in Moodle the name of the field in the user profile that uniquely identified the user (e.g., idnumber). In the external database the name of the matching field.
    • enrol_db_localrolefield / enrol_db_remoterolefield - (optional) in Moodle the name of the field in the role edit page the uniquely identifies the role (e.g., shortname). In the external database the name of the matching field.
  • The Roles panel specifies the role that the user will get in the course if their role is not specified in the external database.
  • The final panel enables auto creation of courses.
  • Save changes, and then tick the box to enable external database enrolment.

Database enrolment does not appear in the course enrolment drop down menu. Why?

The course enrolment drop down menu only lists interactive enrolment plugins. External database enrolment is not such a plugin, so it doesn't appear in the list. Similarly, the "Course Enrollable" setting (in the Course Settings) page also only applies to interactive enrolment plugins and has no effect on external database enrollment.

As of this writing, the only interactive enrolment plugins are manual (also know as internal), paypal and authorize.net.

Field Mapping Example:

Choose your fields from the Moodle database:

  • enrol_localcoursefield: A course identifier from mdl_course, e.g. "idnumber"
  • enrol_localuserfield: A user identifier from mdl_user, e.g. "idnumber"
  • enrol_localrolefield: (optional) A role identifier from mdl_role, e.g. "shortname"

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

  • enrol_remotecoursefield: A matching course identifier from your external database table, e.g. "course_number"
  • enrol_remoteuserfield: A matching user identifier from your external database table, e.g. "userid"
  • enrol_remoterolefield: (optional) A matching role identifier from your external database table, e.g. "role_name"

Potential Gotchas

  • It almost goes without saying that the integrity of the external database is important. If data is missing from the database then there is a potential for users being unenrolled from some or all of their courses. The unenrollment process will remove them from any group assignments and also poll each module type to give the module the option of removing that user's data if appropriate (for example, however, forum posts are never deleted). It is therefore prudent that you take the utmost care to ensure that the data in the external bass is correct at all times.
  • Minor Security Issue Consider that if the ID field you use to identify your students is editable by the students (in their profile), then there is a potential for them changing this to the id of another valid student and gaining access to resources that they should not. However, they will still appear as themselves, they cannot impersonate the other user or otherwise gain access to their resources.

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.

See also