LTI Gradebook Services

LTI Gradebook Services
Project state	Testing
Tracker issue	MDL-59403
Discussion	Support for Gradebook services
Assignee	Stephen Vickers

Project goal

The goal of this project is to add support for the LTI Gradebook Services as per the specification available from the IMS website. LTI Gradebook Services allow Tool Providers more control over gradebook columns and scores than currently possible with Basic Outcome.

Given the importance of the gradebook feature within Moodle and the sensitive nature of gradebook data the guiding principles of this project will be to minimize the impact on the existing gradebook and to ensure best practices with regard to security. In particular, a Tool is sandboxed to only accessing its own line items and scores (i.e. line items either explicitly created by the Tool or attached to links to that tool).

The Gradebook Services allow much more versatility around Grades reporting allowing use cases not achievable under the Basic Outcome model; for example:

• Posting a score for a student no longer requires the student to actually launch the activity
• There is no longer a requirement to have a Resource Link for each gradebook column; for example, a single link could launch a complex piece of content containing many different assignments, and the instructor can decide which one of those would be reported in the gradebook, without having to also create distinct Resource Links for those.
• On course copy, the resourceId attached to each line item allows the Tool to re-bind to the copied Line Items.

The following diagram presents the 2 interaction models this service makes possible, the programmatic uncoupled one being the new one introduced.

This work is being undertaken with the support of Cengage.

Plugin Repository and Installation

The service is packaged as an LTI Service subplugin. The latest code and installation instructions can be found on: https://github.com/CengageEng/moodle-ltiservice_gradebookservices

Introduction

LTI Gradebook Services defines three services: LineItem, Result and Score. At a high level, these services provide CRUD operations on gradebook columns (line items) and cells (results). The specifications expose 3 types of resources:

LineItem Service

Line Item is a gradebook column. Those can be either directly created by Moodle when a link is added (Result.autocreate capability) or programmatically by the Tool POSTing a new line item definition the line items URL.

Score service

Score Service is a write only service used by the Tool Provider to sync scores to Moodle installation. When a score update is received, the Gradebook Service will update the grades in the gradebook accordingly.

Result service

The Result service specification defines an API for the retrieval of a single result. The Result is to represent the actual value shown in the gradebook.

Variables and Capabilities

The various services are complemented by variables to inject the resource end points in messages:

• LineItems.url allows access to the collections of line items for the current context and tool. It is the main entry point in the gradebook service, allowing the Tool to create new line items or discover pre-existing items (for example in a copied course)
• In the case there is a single direct association between a resource link and a gradebook column, the Score.url, Scores.url, LineItems.url can also be passed as parameters. The Score.url allows update operation on the score, acting as a direct replacement for the (lis_outcome_service_url, lis_result_sourcedid) tuple from Basic Outcome.

A representation of the REST API for this service is detailed here: [1]

Security

The services are secured in the same way as other LTI services, using the same consumer key and shared secret as used for LTI launch messages. The key is used to prevent the Tool accessing line items or scores that it does not own.

A service is only available if the Tool Proxy accepts the capability.

Result.autocreate

A Tool Proxy may only be granted access to Score services, therefore preventing the programmatic creation of line items; in that case, the Tool has to rely on the automatically created line item and thus require the Result.autocreate capability. A Line Item will then be automatically created for each link. This is a limitation of the current moodle implementation. Ideally the creation of a line item should be conditional to the presence of a line item definition in the Content Item payload (see https://docs.moodle.org/dev/LTI_ContentItem_Enhancements) and not an always or never proposition.

This issue is referenced in this ticket: (MDL-60187)

Implementation as a subplugin

The service to be offered as an LTI subplugin. This comes a bit under tension with the overall architecture of the mod_lti plugin where the root of the LTI subsystem is the presence of Link (Activity backed by an LTI activity). As the LTI ecosystem outgrows the sheer concept of link to an external tool, it may have to be revamped a bit. In the meantime, it seems we have found a workable compromise:

• a gradebookservices table will hold the entry to the Line Items created through the API
• a gradebookservices table has a nullable Foreign Key dependency to lti
  • creating a line item with a resourceLinkId would:
    • create a gradebook services line item entry with a Foreign Key to the LTI (or fail if no LTI entry is found to match in the course)
    • create a GradeItem record with iteminstance = lti.id, itemnumber = gradebook services id
  • creating a line item without a resourceLinkId would:
    • create a gradebook services line item entry with null as foreign key to LTI
    • create a GradeItem record with iteminstance = null, itemnumber = gradebook services id

Backup and Restore

As backup is only called in the context of activity backup, the subplugin backup will have minimal limitations:

• for backup to function it will require at least one link for that tool proxy to exist in the course
• each backup for LTI will contain
  • all the gradebook services line items associated to the link
  • all the decoupled line items (this data will be duplicated on each link). The duplication has no functional impact, it just makes the backup slightly larger.
• Restore will need to handle the duplicate decoupled line items as they are found on each link archive (i.e. ignore the duplicates)

UPDATE (fixed in Moodle 3.3+) Due to the unresolved issue around backup and restore of LTI content (MDL-34161), the restored links will depend on URL matching to associate to the proper Tool Proxy in the restored course. If such a match is not possible (for example if there is an explicit URL on the link that may be matched), the link will not function.