From MoodleDocs
Jump to: navigation, search

Note: This article is a work in progress. Please use the page comments or an appropriate forum for any recommendations/suggestions for improvement.


Executive Summary

This document primarily describes the current workings of the gradebook. For more detailed information about current gradebook development see Gradebook_improvements

The gradebook mechanisms must be rebuilt to:

  1. Improve performance and scalability - All grades from throughout the system will be pushed to a central system of tables. This means reports based on grades can be generated much faster, and the gradebook has ultimate control over the content.
  2. Improve flexibility - All aspects of the new gradebook will use simple plugin structures, namely: exports, imports and displays/reports. It is expected that the community will be very active in producing special-purpose reports analysing the basic grade data in new ways, for example, or writing plugins to transfer grades to student information systems.
  3. Allow rubrics for outcomes (aka standards,competencies,goals) - As well as numerical grades, each grading item can consist of a number of scores made on a rubric against a standard outcome statement. These can be automatically converted to a numerical grade if desired or just shown as is.
  4. Allow arbitrary columns and derived columns - Arbitrary columns of data can be added (either manually or via import). Columns can also be automatically filled based on formulas.
  5. Implement limited public API - Activities may use this API to send grades/outcomes to gradebook and find out the final grades.


Here are some terms used in the gradebook, both in the development and the user interface. Using these terms in discussions about the gradebook will help to reduce confusion.

Term Definition
Activity An instance of an activity module (e.g. a single quiz, assignment etc...)
Calculation A formula used to calculate grades, based (optionally) on other grade items. Not the same as Calculated question types.
Category A set of Grade Items. A Category also has its own aggregated Grade which is calculated from its Grade Items. There is no limit to the level of nesting of Categories (a Category may belong to another Category). However, each Grade Item may belong to only one Category.
Course completion The concept of meeting certain criteria for completing a course. In the context of the gradebook, this means a set of grades that must be reached, or a number of outcomes/competencies to complete/master.
Grade A Grade is a single assessment. It may be a number or an item on a scale (possibly tied to an Outcome). Raw grade value is the numerical or scale grade from activity. Final grade is the grade reported in gradebook.
Gradebook A central location in Moodle where students' Grades are stored and displayed. Teachers can keep track of their students' progress and organise which set of Grades their students will be able to see. Students see their own Grades.
Grade Item A "column" of Grades. It can be created from a specific Activity or other module, calculated from other Grade Items, or entered manually.
Grade Locks See linked section of this page
History The gradebook has its own type of log, which keeps a History of all changes made to grades.
Outcome Outcomes are specific descriptions of what a person is expected to be able to do or understand at the completion of an activity or course. An activity might have more than one outcome, and each may have a grade against it (usually on a scale). Other terms for Outcomes are Competencies and Goals. See some Examples.
Scale A scale is a set of responses from which the teacher can choose one. eg Very cool, Cool, Fairly cool, Not very cool, Not cool
Letter Grades Special representation of grade values similar to scales. Letters are configured in course contexts or above and are defined by lower boundary. eg A (above 90 %), B (above 80 %), C (above 70 %), D (above 50 %), F (above 0 %)

Database structures


This table keeps information about gradeable items (ie columns). If an activity (eg an assignment or quiz) has multiple grade_items associated with it (eg several outcomes and numerical grade), then there will be a corresponding multiple number of rows in this table.

idnumber is a tag unique inside a course identifying the grade item, useful for identifying data in exports and for referring to the grade item in calculations. It is the same as the idnumber in course_modules.

Field Type Default Info
id int(10) autoincrementing
courseid int(10) The course this item is part of
categoryid int(10)
the category group this item belongs to
itemname varchar(255)
The name of this item (pushed in by the module or entered by user)
itemtype varchar(30) 'mod', 'blocks', 'manual', 'course', 'category' etc
itemmodule varchar(30)
'forum', 'quiz', 'csv', etc
iteminstance int(10)
id of the item module
itemnumber int(10)
Can be used to distinguish multiple grades for an activity
iteminfo text
Info and notes about this item XXX
idnumber varchar(255)
Arbitrary idnumber provided by the module responsible (optional and course unique)
calculation text
Spreadsheet-type formula used to process the raw grades into final grades
gradetype int(4)
0 = none, 1 = value, 2 = scale, 3 = text
grademax float(10,5)
What is the maximum allowable grade?
grademin float(10,5)
What is the minimum allowable grade?
scaleid int(10)
If this grade is based on a scale, which one is it?
outcomeid int(10)
If this is outcome item, which outcome is it?
gradepass float(10,5)
What grade is needed to pass? grademin <= gradepass <= grademax
multfactor float(10,5)
Multiply all raw grades from activities by this
plusfactor float(10,5)
Add this to all raw grades from activities by this
aggregationcoef float(10,5)
Weight applied to all grades in this grade item during aggregation with other grade items.
sortorder int(10)
Sorting order of the columns (pre-order walk of the grading tree)
display int(10)
Display as real grades, percentages (in reference to the minimum and maximum grades) or letters (A, B, C etc..), or course default (0)
hidden int(10)
1 is hidden, 1 is hide always, > 1 is a date to hide until (prevents viewing of all user grades)
locked int(10)
0 is not locked, > 0 is a date when was item locked (no final grade or grade_item updates possible)
locktime int(10)
0 no auto locking, > 0 is a date to lock grade item and final grades after automatically
needsupdate int(10)
If this flag is set, then the whole column will be recalculated. If set in course item, some other item needs recalculation. Calculated and category items are recalculated together with any other items.
timecreated int(10) The first time this grade_item was created
timemodified int(10) The last time this grade_item was modified


This table keeps information about categories, used for grouping items. An associated grade_item will be maintained for each category to store the aggregate data.

Field Type Default Info
id int(10) autoincrementing
courseid int(10) The course this grade category is part of
parent int(10)
Parent grade_category (hierarchical)
depth int(10)
How deep is this category from the highest level (1,2,3)
path varchar(255) Shows the path as /1/2/3/
fullname varchar(255) The name of this grade category
aggregation int(10)
A constant pointing to one of the predefined aggregation strategies (none, mean,median,sum, etc)
keephigh int(10)
Keep only the X highest items
droplow int(10)
Drop the X lowest items
aggregateonlygraded int(1)
Aggregate only existing grades
aggregateoutcomes int(1)
Aggregate otcomes together with normal items
aggregatesubcats int(1)
Aggregate only items placed directly in category or all items in subcategories excluding the subcategory totals
timecreated int(10) The first time this grade_category was created
timemodified int(10) The last time this grade_category was modified
hidden int(1)


This table keeps individual grades for each user and each item. The raw grade is exactly as imported or submitted by modules. The rawgrademax/min and rawscaleid are stored here to record the values at the time the grade was stored, because teachers might change this for an activity! All the results are normalised/resampled/calculated for the finalgrade, which is relative to the max/min/scaleid values stored in the grade_item. The finalgrade field is effectively a cache and values are rebuilt whenever raw values or the grade_item changes.

Note that the finalgrade for a scale-based item may be non-integer! It needs to be rounded on display.

Field Type Default Info
id int(10) autoincrementing
itemid int(10) The item this grade belongs to
userid int(10) The user who this grade is for
rawgrade float(11,10)
The raw grade that came into the system
rawgrademax float(11,10)
The maximum allowable grade when this was created
rawgrademin float(11,10)
The minimum allowable grade when this was created
rawscaleid int(10)
If this grade is based on a scale, which one was it?
usermodified int(10)
the userid of the person who last modified the raw grade value
finalgrade float(11,10)
The final grade (cached) after all calculations are made. Overriden grades are also stored here.
hidden int(10)
0 is not hidden, 1 is hide always, > 1 is a date to hide until
locked int(10)
0 is not locked, > 0 when was the grade locked
locktime int(10)
0 is never, > 0 is a date to lock the final grade after automatically
exported int(10)
0 is not exported, > 0 is the last exported date
excluded int(10)
grade excluded from aggregation, > 0 is the last exported date
overridden int(10)
0 is not overridden, > 0 is the last overridden date
feedback text
Manual feedback from the teacher. Could be a code like 'mi'.
feedbackformat int(10)
Text format for feedback
information text
not sued yet (Further information like forum rating distribution 4/5/7/0/1 ?)
informationformat int(10)
Text format for information
timecreated int(10) temporary hack - the date of submission in activity if any, new field expected in 2.0
timemodified int(10) temporary hack - the date of grading in activity or date of manual grading in gradebook, new field expected in 2.0


This table describes the outcomes used in the system. An outcome is a statement tied to a rubric scale from low to high, such as “Not met, Borderline, Met” (stored as 0,1 or 2). For more info about these see Outcomes.

Field Type Default Info
id int(10) autoincrementing
courseid int(10)
Mostly these are defined site wide ie NULL
shortname varchar(255) The short name or code for this outcome statement
fullname text The full description of the outcome (usually 1 sentence)
scaleid int(10) The recommended scale for this outcome.
description text
The full description of the outcome (usually 1 sentence)
descriptionformat int(2) 0
timecreated int(10) the time this outcome was first created
timemodified int(10) the time this outcome was last updated
usermodified int(10)
the userid of the person who last modified this outcome


An intersection table used to make standard outcomes available to courses.

Field Type Default Info
id int(10) autoincrementing
courseid int(10) The id of the course being assigned the outcome
outcomeid int(10) The id of the outcome being assigned to the course


Field Type Default Info
id int(10) autoincrementing
itemname varchar(255) new grade item name
importcode int(10) import batch code for identification
importer int(10) user importing the data


Field Type Default Info
id int(10) autoincrementing
itemid int(10) NULL if set, this points to existing grade_items id
newgradeitem int(10) NULL *TODO* Document
userid int(10) *TODO* Document
finalgrade float(10,5) NULL raw grade value
feedback text NULL *TODO* Document
importcode int(10) similar to backup_code, a unique batch code for identifying one batch of imports
importer int(10) NULL *TODO* Document

History tables

These table keep track of changes to most of the grade tables. Using these it should be possible to reconstruct the grades at any point in time in the past, or to audit grade changes over time. It should be quicker to use these tables for that, rather than storing this information in the main Moodle log. The following tables are set up for that purpose:

  1. grade_categories_history
  2. grade_grades_history
  3. grade_items_history
  4. grade_outcomes_history

Each of them has the same DB structure as their matching table (e.g. grade_categories), with 4 extra fields:

Field Type Default Info
action int(10) 0 The action that lead to the change being recorded (insert, update, delete)
oldid int(10) The id of the record being changed or inserted (PK of the main table, not the history table)
source varchar(255) NULL The module from which the action originated
loggeduser int(10) NULL The userid of the person who performed the action.


Field Type Default Info
id int(10) autoincrementing
contextid int(10) What contextid does this letter apply to (from levels CONTEXT_SYSTEM, CONTEXT_COURSECAT or CONTEXT_COURSE)
lowerboundary float(10,5) The lower boundary of the letter. Its upper boundary is the lower boundary of the next highest letter, unless there is none above, in which case it's grademax for that grade_item.
letter varchar(255) The display value of the letter. Can be any character or string of characters (OK, A, 10% etc..)

Overview of module communication

Modules usually store raw grades internally and pass them into gradebook every time they change. Gradebook may also request activities to resend the grades.

The gradebook is designed to be as separate as possible from the code of activities - modules do not read grade tables or use internal gradebook API.

Originally it was planned to use new events API, but in the end it was decided to use minimal API consisting of several function in lib/gradelib.php and each mod/xxx/lib.php

Backward compatibility with Moodle 1.8 and earlier

Function grade_grab_legacy_grades($courseid) may be used to request transfer of grades from legacy or 3rd party activities which were not yet converted to new grade API. This function is not called automatically.

Modules are responsible to push existing grades into gradebook during upgrade.

API for communication with modules/blocks

Modules may use only functions from lib/gradelib.php which are marked as public. This API may be extended in later 1.9.x release. Activities should access/update only own grades.


grade_get_grades($courseid, $itemtype, $itemmodule, $iteminstance, $userid_or_ids=0)

Returns grading information for given activity - optionally with users grades. Manual, course or category items can not be queried.


grade_get_outcomes($courseid, $itemtype, $itemmodule, $iteminstance,$userid=0)

Returns list of outcomes used in course together with current outcomes for this user.


grade_is_locked($courseid, $itemtype, $itemmodule, $iteminstance, $itemnumber, $userid=NULL)

This function will tell a module whether a grade (or grade_item if $userid is not given) is currently locked or not. If it's locked to the current user then the module can print a nice message or prevent editing in the module. If no $userid is given, the method will always return the grade_item's locked state. If a $userid is given, the method will first check the grade_item's locked state (the column). If it is locked, the method will return true no matter the locked state of the specific grade being checked. If unlocked, it will return the locked state of the specific grade. (info)


grade_update($source, $courseid, $itemtype, $itemmodule, $iteminstance, $itemnumber, $grades=NULL, $itemdetails=NULL)

Submit new or update grade; update/create grade_item definition. Grade must have userid specified, rawgrade and feedback with format are optional. rawgrade NULL means 'Not graded', missing property or key means do not change existing. Only following grade item properties can be changed 'itemname', 'idnumber', 'gradetype', 'grademax', 'grademin', 'scaleid', 'multfactor', 'plusfactor', 'deleted'.




grade_update_outcomes($source, $courseid, $itemtype, $itemmodule, $iteminstance, $userid, $data)

Updates outcomes of a given user. Manual outcomes cannot be updated.

Private gradebook API

Private API is used by gradebook plugins and core Moodle code, it may change in 2.0. Most of the interesting classes and functions are in lib/gradelib.php, grade/lib.php and grade/report/lib.php.

The following 3 functions are all in /lib/gradelib.php


grade_regrade_final_grades($courseid=NULL, $userid=NULL, $updated_item=NULL)

Updates all grade_grades->finalgrade records for each grade_item matching the given attributes. The search is further restricted, so that only grade_items that have needs_update == true or that use calculation are retrieved and used for the update. The function returns the number of grade_items updated (NOT the same as the number of grades_grades updated!).


grade_verify_idnumber($idnumber, $grade_item = null, $cm = null, $gradeitem)

Verify new value of idnumber - checks for uniqueness of new idnubmers, existing are kept intact.


remove_course_grades($courseid, $showfeedback)

Remove all grade related course data - history is kept


grade_update_mod_grades($modinstance, $userid=0)

Force full update of module grades in central gradebook. Invokes $modinstance->modname.'_grade_item_update' and $modinstance->modname.'_update_grades' on mods implementing those methods.

TODO: add description of the other methods and classes + simple usage examples + querylib.php description

Dealing with multiple grades

Modules usually produce only one grade item per activity. Optionally one or more outcomes may be attached to activities.

Some activities may need to aggregate multiple ratings or attempts before sending them into the gradebook. Activities can not send variable number of items.

If the gradebook receives multiple grade items from a module, then they are automatically grouped together in a unique grade category (with the same name as the module instance). See Outcomes for more details.

TODO: this may still be changed

Calculated grade items

Categories or manual items maybe calculated using spreadsheet-like formulas. Formulas may reference other items from the same course only using Id numbers in double square brackets.

eg:  = MEAN([[quiz121]], [[quizend]]) + [[assignmentAXC]] + 20.0

Regrading / updating of final grades

TODO: describe needsupdate flag and incremental updates

Adjustment of raw grades

Grade_item contains optional rules for adjusting the raw grade before it is cached into a final grade. These rules are processed BEFORE the calculation discussed above. Scale is never changed. Multfactor and plusfactor may be used to alter raw grades coming from activities, but it is recommended to use formulas instead.

Displaying the grades to ordinary participants

The module takes responsibility for displaying grades within the module (to a student, say). It is recommended to use the real final grades obtained using grade_get_grades() functionBecause guidebook might force hiding, override grade, etc.

For full display of grades in a whole course say, the student uses the same link as teachers use to access the gradebook. However, due to their different permissions they will only have access to specific reports. By default this is the User report report which only shows their own grades and has very few configuration options.

Locked grades

Both whole columns and individual grades can be locked in the gradebook, via the locked field. Teachers may want to do this to prevent further changes from the modules, or from other teachers. When a grade is locked, any changes that might affect that grade are ignored. When the graded is unlocked, activities are asked to resend the latest grades.

In the main GUIs the lock toggling will be achieved by clicking on a little padlock icon beside each entry or column.

There is also an option to lock grade or item after some specified date.

Overridden grades

Grades can be manually modified (overridden) in the gradebook. When this is done the entered value is always used instead of the aggregated, calculated or activity grade.

Once grades have been overriden in the gradebook they become read only in the original module. The module should provide a visual indication as to why the grade cannot be modified.

The need to improve how the module expresses that a grade has been overridden will be reduced by the new grading interface

Hidden grades and categories

Grades and categories can be hidden in the gradebook or the "categories and items" screen. When a category is hidden all the grade items within it are automatically hidden as well. When a category is un-hidden then all the grade items within it are un-hidden.

The teacher always sees totals calculated from all relevant items (hidden or un-hidden)

(Features below were added in 1.9.8 and 2.0)

When a grade is shown its parent category will also be shown if it was hidden. MDL-21367

The teacher decides what ordinary users can see in the case of totals that include hidden grades (MDL-21218, in 1.9.8 and 2.0). The user and overview report each have a setting to choose between:

  1. Hide any totals that are dependent on a hidden item (show a hyphen there) [DEFAULT]
  2. Display totals excluding the hidden items
  3. Display full totals including the hidden items (may allow students to back-calculate hidden grades)


All grading related changes maybe logged in history tables.

Security Issues

For security an option to force SSL for the gradebook might be good.

Overall grade

Each course has exactly one course grade item. It may be used for this purpose now. Other course completion criteria will be implemented in 2.0.

Report plugins

All the main interface of the gradebook are implemented as report plugins. Each plugin is fully responsible for page layout, there are some handy functions in grade/lib.php. They can even define their own capabilities and extra tables if the core tables are not enough, as they'll have a full /grade/report/xxxx/db directory.

Each report defines one capability to allow people to see that report, so that admins have control over who can see what reports. For example, the participant interface can be a totally separate report plugin.

This allows for the widest flexibility and safety in how grades are presented.

Default teacher interface

This interface will be what teachers see by default, and will subsume everything the current interface (in Moodle 1.8) does.

Some snippets of functionality: Moodle1.9

Overall it's a grid, with participant names down one side and grade items along the top.

Columns will be able to be collapsed together by grouping them into categories. Grades for categories can be calculated via various means.

“Eye-cons” on the columns and checkboxes by every grade (this bit possibly controlled with a switch) allow hiding by category, by column, by individual grade.

Textual notes can be added to each grade for more info. These show up to participants as well.

A groups menu allows the teacher to switch between showing EACH of the groups they have access to, or ALL the groups they have access to.

All grade items will link to modulepath/grade.php?id=44 which will work out what the current person should be allowed to see and either redirect them to the correct page or just show them immediately. This copes with situations like the quiz, say, where we want editing teachers to go to the detailed reports there while participants just see their own grade or whatever the quiz is set to show.

User preference to SWITCH between showing raw grades, percentage grades, or both, or grade letters (A/B/C etc).

Settings for grade letters not only define the transformation from percentage to grades, but also the transformation from letters to grades (in case the teacher edits some of the letter grades).

Categories are shown above the headings for each column. Clicking for more info on a category will just show the category with a summary column showing total/average for just that category (PLUS the summary column for the whole course).

All columns should be sortable up/down.

At the bottom of each column is a row with the mean course score. If in groups mode, then add ANOTHER row with just the group mean. Add the number of grades used in brackets. eg 56% (11). When the report is paged, these means are still for the whole course/group (not the page!)

Moodle 2.0

Teachers can type “straight into” the grid using AJAX or fallback to forms. No popup menus for values.

Later on we can support customisable shorthand codes to make data entry quick (eg type 'ab' for absent, or 'nge' for not good enough).

See the QA testing site for a live demo of this report.

Default participant interface

This interface will be what participants see by default:

Some snippets of functionality:

  • Invert the grid to show one item per row, with the total/average at the bottom.
  • Use second/third columns to show categories.
  • Include ranking score in another column.
  • Show feedback
  • Show percentage
  • No editing functionality.

See the QA testing site for a live demo of this report.

Outcomes report

This simple informational report displays all the outcomes used by the course, with the following information:

  • Outcome name
  • Overall average: If the outcome is used by more than one activity, this shows you the mean across all these activities in the current course
  • Site-wide: Yes or No: A site-wide outcome is automatically made available to all courses.
  • Activities: A list of links to the activities in the current course that use each outcome. One row per activity (table splits here)
  • Average: For each activity using the outcome, the average score is shown.
  • Number of grades: For each activity using the outcome, the number of grades is shown (non-graded participants are ignored)

Overview report

Another basic report, showing a participant's course averages in each of the courses in which s/he has received grades.

Export plugins

The API for these is extremely simple. Each export plugin should occupy a directory under /grade/export/xyz and needs to provide only an index.php file as a the primary interface. This file just accepts a 'courseid' parameter.

Import plugins

Each import plugin should occupy a directory under /grade/import/xyz and needs to provide only an index.php file as a the primary interface. This file just accepts a 'courseid' parameter.

The index.php will show an interface for further options and selections.

Import plugin must validate data before starting the import operation, if some parts of import fail the user must be notified.

Some sample import plugins are:

Import from CSV

Accepts an upload of (or URL to) a CSV file. Multiple options describe how to process the file, which columns to add etc. The imported grades always override current grades.

Import from XML

Accepts an upload of (or URL to) an XML file with this kind of format (from OU).

<results batch="[someuniqueimportnumber]">
        <state>['new' or 'regrade']</state>
            <state>['new' or 'regrade']</state>

Capabilities and Permissions

  • moodle/grade:view - view own grades or grades of other user if used in CONTEXT_USER
  • moodle/grade:viewall - view grades of all users
  • moodle/grade:viewhidden - see grades that are marked as hidden for the owner
  • moodle/grade:hide - be able to hide/unhide cells, items or categories
  • moodle/grade:lock - be able to lock cells, items or categories
  • moodle/grade:unlock - be able to unlock cells, items or categories
  • moodle/grade:manage - manage grade items and categories in gradebook (create, edit, lock, hide, delete, etc.)
  • moodle/grade:import - general import grades, requires separate permission for each plugin
  • moodle/grade:export - export grades, requires separate permission for each plugin
  • gradereport/grader:view - can view the grader report
  • gradeimport/csv:view - can view/use the csv import plugin
  • gradeexport/csv:view - can view/use the csv export plugin
  • moodle:site/accessallgroups

Development Tasks and Tracking

For details of 1.9 development see [ MDL-9137]

For details of 2.0 development see Gradebook_imporovements and [ MDL-19131]

Updating module code

Module authors must implement new gradebook API and add upgrade code for migration of old grades into new gradebook. Fortunately the needed changes are not big.


  • add xxx_update_grades() function into mod/xxx/lib.php
  • add xxx_grade_item_update() function into mod/xxx/lib.php
  • patch xxx_update_instance(), xxx_add_instance() and xxx_delete_instance() to call xxx_grade_item_update()
  • patch all places of code that change grade values to call xxx_update_grades()
  • patch code that displays grades to students to use final grades from the gradebook

There are many examples in official modules, assignment has the most advanced implementation.

Ideas for the future

Moodle 2.1

See Gradebook_improvements and MDL-25423 for details of planned future enhancements

  • option to aggregate including/excluding hidden grades - needs db changes
  • option to rollback all changes during import operation if anything fails
  • performance improvements
  • conditional activities
  • course completion criteria
  • better public API for modules
  • better API for gradebook plugins
  • better state tracking in export plugins
  • ajax reports
  • specialised reports
  • submission and marking date tracking db changes
  • calculation formula improvements
  • historical views
  • individual graph of grades (time vs %). Bar graph, lineal graph. Add (or not) the maximum posible; line of 0 (=minimum), 25, 50 (=median), 75 and 100 (=max) percentils of the group

See also

Personal tools
User docs (English)