Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

LTI Gradebook Services: Difference between revisions

From MoodleDocs
 
(16 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Infobox Project
{{Infobox Project
|name = LTI Gradebook Services
|name = LTI Gradebook Services
|state = Planning
|state = Testing
|tracker = TBA
|tracker = MDL-59403
|discussion =TBA
|discussion =[https://moodle.org/mod/forum/discuss.php?d=354378 Support for Gradebook services]
|assignee = Stephen Vickers
|assignee = Stephen Vickers
}}
}}
Line 10: Line 10:
== Project goal ==
== Project goal ==


The goal of this project is to add support for the LTI Gradebook 2 services as per the specification available from the IMS website.  LTI Gradebook 2 services extend the Basic Outcomes to allow Tool Providers more control over gradebook columns and scores. LTI Gradebook 2 services are in candidate final draft at the time of writing.
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.
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.
 
[[{{ns:file}}:CoupledVsDecoupled.png|400px]]


This work is being undertaken with the support of [https://www.cengage.com/ Cengage].
This work is being undertaken with the support of [https://www.cengage.com/ 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 ==
== Introduction ==


LTI Gradebook 2 defines three services: LineItem, Result and Score. At a high level, these services provide CRUD operations on gradebook columns (line items) and cells (scores). The specification also defines an API that allows for management of collections of line items within a given context (e.g., a course section), collections of scores for a given line item, as well as for managing individual line items, results and scores (the distinction between results and scores is that scores represent the value as received from the tool provider and are considered immutable by the tool consumer).
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:


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. All web service payloads use JSON-LD.
'''LineItem Service'''


'''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.
 
Allows line items (gradebook columns) in the Moodle gradebook to be managed by an LTI Tool Provider. Only line items created by (or for) the Tool Provider can be read/updated/deleted by it. Each line item will be owned by the Tool Provider and associated with a specific context (e.g., course section). The specification does not impose any limits on the number of line items which can be created by a Tool Provider. Of course, a Moodle administrator does not have to make these services available to a Tool Provider. The LineItem service specification defines an API for CRUD operations on a single line item as well as collections of line items.


'''Score service'''
'''Score service'''


Allows scores (gradebook cells) in the Moodle gradebook to be managed by an LTI Tool Provider. In addition to the literal score the score service also allows for the passing of a comment about the grade. The Score service is conceptually similar to the Result service. However, as mentioned above, Score resources should be considered immutable by the tool consumer. The Score service specification defines an API for CRUD operations on a single score as well as a collection of scores.
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'''
'''Result service'''
The Result service specification defines an API for the retrieval of a single result.
 
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:
[http://claudeonthe.net/ims/swaggerui/#/]
 
 
== 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+) <s>Due to the unresolved issue around backup and restore of LTI content (MDL-34161)</s>, 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.
 
[[{{ns:file}}:moodlegbsmodel.png|620px]]

Latest revision as of 09:44, 21 July 2018

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.

CoupledVsDecoupled.png

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.

moodlegbsmodel.png