Gradebook import
Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.
Introduction
This document is for developers wanting to allow users to import Moodle grade information in a format that is not currently supported by Moodle. Here is another document if you are looking for an introduction to importing grades into Moodle
Moodle allows authorised users to import grade information. This can be used to transfer student grades from another piece of software into Moodle.
Since 1.9 the Moodle gradebook has provided support for the addition of plug-in import modules to allow Moodle to import grade information in new or custom formats. Moodle includes two default gradebook import modules, csv and xml.
This document describes how to implement a custom gradebook import plug-in.
Getting started
The gradebook import modules are located in the grade/import directory. To create a new gradebook import module complete the steps listed below.
Note: For the remainder of this topic when you see [newimport], replace it with the short name you chose for your import module. Do not include the []. Moodle comes with the following import modules: csv and xml so you cannot use those names.
New Gradebook Import Module Creation Steps
- Decide on a short name for this new import module. This name will be referred to as [newimport] in this document.
- Create a new directory in Moodle's grade/import directory for your files.
- Review the import formats that ship with Moodle and choose the import format most like the one you wish to develop. Refer to that import's files as needed.
- Copy the files from the import format you selected into your newly created directory of grade/import/[newimport]
- Remove references to the import module you copied and alter each of the files listed below.
- Click on Notifications link in the Site Administration menu to go through the upgrade process (if one didn't happen automatically) and set up the permissions for your import module.
- Test, test, test - until your import module performs properly.
Remove References to the Original Import Module
You must make sure to replace all references to the import module you copied with the name of your new import module. In Linux you can use grep to look for references to the import module you copied. Equivalent commands exist for both Windows and Mac. The following is an example that will list all the places that "csv" appears in your new import module.
grep -R "csv" ./grade/import/[newimport]/
Files That Need Special Attention
Some of the files need some thought about your requirements.
/grade/import/[newimport]/db/access.php
The access.php file makes your gradebook import module available to teachers and allows the security administrator to decide who can and cannot access the module. See the "View role details" page in Site Administration > Users > Permissions > Define roles for more details.
Review access.php of both csv and xml import modules and decide which capabilities make sense for your import module.
The new security role entries will be available after an upgrade has been completed (click the Notifications link in Site Administration). This should not be done until you believe your import module is ready to test.
Note: The gradeimport_[newimport].php file in the lang directory works with the :view and :publish settings to provide a description. See the information about that file for more details.
/grade/import/[newimport]/index.php
When a user selects Import > [newimport] from the gradebook navigation drop down they will be taken to your import module's index.php. It typically displays a form to allow the user to upload the data that will be imported. You can use the class grade_import_form at /grade/import/grade_import_form.php or you can implement your own class. The csv import module uses the standard form. The xml import module implements its own form class which can be found at /grade/import/xml/grade_import_form.php. Make sure your index.php is instantiating the class you want to use.
Customise Your Import Module
At this point you should have an import module that functions however it will behave exactly the same as the module you copied. Now you can start making modifications and altering it to your requirements. Remember to refer to both the csv and xml import modules. They will hopefully provide guidance about how grade importing works and working with Moodle in general.
