- 1 Executive Summary
- 2 Glossary
- 3 Database structures
- 4 Overview of module communication
- 5 API for communication with modules/blocks
- 6 Private gradebook API
- 7 Dealing with multiple grades
- 8 Calculated grade items
- 9 Regrading / updating of final grades
- 10 Adjustment of raw grades
- 11 Displaying the grades to ordinary participants
- 12 Locked grades
- 13 Overridden grades
- 14 Hidden grades and categories
- 15 Logging
- 16 Security Issues
- 17 Overall grade
- 18 Report plugins
- 19 Export plugins
- 20 Import plugins
- 21 Capabilities and Permissions
- 22 Development Tasks and Tracking
- 23 Updating module code
- 24 Ideas for the future
- 25 See also
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:
- 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.
- 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.
- 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.
- 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.
- 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.
|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 %)|
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.
|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.
|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|
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.
|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 excluded 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.
|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)|
|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.
|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|
|itemname||varchar(255)||new grade item name|
|importcode||int(10)||import batch code for identification|
|importer||int(10)||user importing the data|
|itemid||int(10)||NULL||if set, this points to existing grade_items id|
|finalgrade||float(10,5)||NULL||raw grade value|
|importcode||int(10)||similar to backup_code, a unique batch code for identifying one batch of imports|
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:
Each of them has the same DB structure as their matching table (e.g. grade_categories), with 4 extra fields:
|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.|
|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_OK = 0
- GRADE_UPDATE_FAILED = 1
- GRADE_UPDATE_MULTIPLE = 2
- GRADE_UPDATE_ITEM_LOCKED = 4
- GRADE_UPDATE_ITEM_DELETED = GRADE_UPDATE_ITEM_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 all grade related course data - history is kept
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.
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.
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:
- Hide any totals that are dependent on a hidden item (show a hyphen there) [DEFAULT]
- Display totals excluding the hidden items
- Display full totals including the hidden items (may allow students to back-calculate hidden grades)
All grading related changes maybe logged in history tables.
For security an option to force SSL for the gradebook might be good.
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.
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!)
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.
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)
Another basic report, showing a participant's course averages in each of the courses in which s/he has received grades.
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.
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]"> <result> <state>['new' or 'regrade']</state> <assignment>[idnumber]</assignment> <student>[studentid]</student> <score>[score]</score> </result> <result> <state>['new' or 'regrade']</state> <assignment>[idnumber]</assignment> <student>[studentid]</student> <score>[score]</score> </result> [...] </results>
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
Development Tasks and Tracking
For details of 1.9 development see [http://tracker.moodle.org/browse/MDL-9137 MDL-9137]
For details of 2.0 development see Gradebook_imporovements and [http://tracker.moodle.org/browse/MDL-19131 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
- 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