IMS Enterprise

About IMS Enterprise

IMS Enterprise is an international standard XML file format which may be used to create and update user accounts, enrol and unenrol users from courses, assign roles, create courses and course categories, and update course full and short names.

Using this enrolment method

To use IMS Enterprise enrolment, it must be enabled in 'Manage enrol plugins' in the Site administration.

IMS Enterprise enrolment will import an XML file from on your Moodle server. Set "File location" to the full path to your xml file (locally on the server, e.g. /home/user/imsenterprise/file.xml)

IMS Enterprise is not added to courses, but instead you run the import directly from the "Site administration > Plugins > Enrolments > IMS Enterprise file" page. To do this, click the "perform an IMS Enterprise import right now" link or run cron.

Format overview

Below is a simple guide to the basic structure of a typical IMS Enterprise data file. Much more information is available on the IMS Enterprise official website.

You may like to read the conformance summary which describes which IMS data elements this plugin can process.

Basic guide to IMS Enterprise file format

For any IMS-style enrolment you need a <group> tag which specifies the course, a <person> tag which specifies the user account, and a <membership> tag containing <member> tags which specify a person's role within a given course.

Remember that the numeric keys used in the Moodle databases are not the interoperable data - a student data system is never going to know in advance that Joe is the 20th user added to the Moodle database - so those aren't the keys exchanged in this type of data.

Typically a course would have a reference code as well as a name, so let's assume its code is MOODLE101. If you require a new course to be placed in a category other than the default, you can specify that using the <orgunit> tag. To define your course you could use

 <group>
   <sourcedid>

MyDataSystem

     <id>MOODLE101</id>
   </sourcedid>
   <description>
     <short>Moodle 101</short>
     <long>Moodle 101: Course Name</long>
   </description>
   <org>
     <orgunit>CATEGORY</orgunit>
   </org>
 </group>

The enrolment script will look for a course with code MOODLE101, and (optionally) create it if it doesn't exist, the plugin also allows you to map between group tags and the course shortname, fullname and summary fields. Similarly for the person - let's assume it's "jmoodle":

<person>
   <sourcedid>

MyDataSystem

     <id>jmoodle</id>
   </sourcedid>
   <userid>jmoodle</userid>
   <name>
     <fn>Joe Moodle</fn>
     <n>
       <family>MOODLE</family>
       <given>JOE</given>
     </n>
   </name>
 </person>

If Joe doesn't already have an account, the script can (optionally) create an account for him.

Let's now look at the membership, adding the person to the course:

 <membership>
   <sourcedid>

MyDataSystem

     <id>MOODLE101</id>
   </sourcedid>
   <member>
     <sourcedid>

MyDataSystem

       <id>jmoodle</id>
     </sourcedid>
     <role roletype="01">
       <status>1</status>
       <extension><cohort>unit 2</cohort></extension>
     </role>
   </member>
 </membership>

The IMS Enterprise specification does offer a facility for specifying start/end dates for enrolments, so those can be included using the <timeframe> tag if needed.

If a person is already added to a group within the course, the script won't actually modify that. If they are not grouped, however, then the specified grouping will be applied.

Automatic creation of new courses

If required, the IMS Enterprise enrolment plugin can create new courses for any it finds in the IMS data but not in Moodle's database.

Courses are first queried by their "idnumber" - an alphanumeric field in Moodle's course table, which can specify the code used to identify the course in the Student Information System (for example). If that is not found, the course table is searched for the "short description", which in Moodle is the short course identifier as displayed in the breadcrumbs etc. (In some systems these two fields may well be identical.) Only when that search has failed can the plugin optionally create new courses.

Any newly generated courses are HIDDEN when created. This is to prevent the possibility of students wandering into completely empty courses that the teacher may be unaware of.

Unenrolling students/teachers

If required, the Enterprise data can add as well as remove course enrolments - for students and for teachers. If this setting is turned on, then Moodle will carry out unenrolments when specified in the data. Note, as of Moodle 2, you must use IMSEnterprise to remove members that have been added by the plugin. You cannot manually delete a member.

There are three ways of unenrolling students within the IMS data:

A <member> element which specifies the given student and course, and with the "recstatus" attribute of the <role> element set to 3 (which means "delete"). THIS IS NOT YET IMPLEMENTED IN THE MOODLE PLUGIN.
A <member> element which specifies the given student and course, and with the <status> element set to 0 (which means "inactive").

The third method is slightly different. It does not require this config setting to be activated, and can be specified well in advance of the unenrolment date:

A <member> element which specifies a <timeframe> for the enrolment can specify the begin and/or end dates for enrolment of this particular student. These dates are loaded into Moodle's enrolment data table if present, and so after the end-date, a student will no longer be able to access that particular course.

Documentation