Learning Tools Interoperability (LTI)®Submission Review Service - 1EdTech Candidate Final Version 1.0

Learning Tools Interoperability (LTI)® Submission Review Service

IMS Candidate Final Public
Spec Version 1.0
IMS Candidate Final Public
Document Version: 4
Date Issued: April 01, 2022
Status: This document is for review and adoption by the IMS membership.
This version: https://www.imsglobal.org/spec/lti-sr/v1p0/
Latest version: https://www.imsglobal.org/spec/lti-sr/latest/
Errata: https://www.imsglobal.org/spec/lti-sr/v1p0/errata/

IPR and Distribution Notice

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.

IMS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on IMS's procedures with respect to rights in IMS specifications can be found at the IMS Intellectual Property Rights webpage: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf .

The following participating organizations have made explicit license commitments to this specification:

Org name Date election made Necessary claims Type
D2L Corporation January 15, 2020 No RF RAND (Required Elements)

Use of this specification to develop products or services is governed by the license with IMS found on the IMS website: http://www.imsglobal.org/speclicense.html.

Permission is granted to all parties to use excerpts from this document as needed in producing requests for proposals.

The limited permissions granted above are perpetual and will not be revoked by IMS or its successors or assigns.

THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.

Public contributions, comments and questions can be posted here: http://www.imsglobal.org/forums/ims-glc-public-forums-and-resources .

© 2023 IMS Global Learning Consortium, Inc. All Rights Reserved.

Trademark information: http://www.imsglobal.org/copyright.html

Abstract

The Learning Tools Interoperability (LTI)® Submission Review Service provides a standard way for an instructor or student to launch back from a platform's gradebook to the tool where the interaction took place to display the learner's submission for a particular line item.

1. Introduction

Being able to report a score to the platform's gradebook has long been a key feature of the Learning Tools Interoperability (LTI) specifications. It started years ago with the LTI 1.1 basic outcome service, and is being significantly enriched by the newer Assignment and Grade Services. For example, the Assignment and Grade Services allows the tool to notify the platform that an activity has been submitted and now needs grading.

However, once in the gradebook, there is no easy way for the instructor or the student to go back to the tool to see what's 'behind' the grade or the needs grading flag, and eventually grade the learner's work. This is the purpose of this message: launch back from the platform's gradebook to the tool to display the learner's submission for a particular line item.

The term submission in this specification refers to any representation of the learner's work; that representation can greatly vary based on the type of activity. For example, a submission can be your traditional essay the learner wrote for a writing assignment, or some statistics about the user's engagement in a group online game session that took place earlier.

This specification builds on the Assignment and Grade Services [LTI-AGS-20] and the [LTI-13] core specifications.

2. LtiSubmissionReviewRequest claims

The launch must contain enough information for the tool to display the learner's submission, and optionally, being able to pass back an updated score back to the platform's gradebook. It also needs a way to return the user back to the platform.

Depending on whether the line item is associated with a resource link or not, the launch will slightly differ.

2.2 A variation of LtiResourceLinkRequest

The LtiSubmissionReviewRequest is based on the LtiResourceLinkRequest defined in [LTI-13] core specifications.

All claims defined in the LtiResourceLinkRequest apply unless specified otherwise in this specification.

2.3 Message Type

Message type MUST be LtiSubmissionReviewRequest.

2.5 Assignment and Grade Services Claim

The https://purl.imsglobal.org/spec/lti-ags/claim/endpoint claim is required. As it identifies for which line item the LtiSubmissionReviewRequest message is made, it must contain the lineitem property referring to the line item from where the launch originates.

2.6 User's identity is the user making the launch

All user related claims of the message must relate to the launching user and not the result's owner unless they are the same. For example when an instructor launches from the gradebook a LtiSubmissionReviewRequest to review a student's work, the sub claim is the identifier of the instructor, not the identifier of the student.

2.7 For User claim

The https://purl.imsglobal.org/spec/lti/claim/for_user claim identifies the user who made the submission that is to be displayed (the user to which the result is attached); it MUST be included in the message payload regardless if the result's owner is the same user or not as the launching user.

It contains the following properties:

user_id (Required): id of the graded user, as identified by sub claim for launches done by that user.

person_sourcedid: LIS sourced id of the graded user.

given_name: Per OIDC specifications, given name(s) or first name(s) of the graded user. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.

family_name: Per OIDC specifications, surname(s) or last name(s) of the graded user. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.

name: Per OIDC specifications, graded user's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the graded user's locale and preferences.

email: Per OIDC specifications, graded user's preferred e-mail address.

roles: Roles in the context as defined in LTI 1.3 Core specifications.

2.8 Return URL

The return_url is included in the https://purl.imsglobal.org/spec/lti/claim/launch_presentation as defined in the [LTI-13] core specifications and functions the same way.

Return url should return to the grading interface where the LtiSubmissionReviewRequest was initiated.

2.10 Custom parameters

If the line item is associated with a resource link, all custom parameters from that resource link must be included in addition to any custom parameters defined explicitly for the LtiSubmissionReviewRequest message.

In case of conflict, the same parameter key being defined in the LtiSubmissionReviewRequest and in the Resource Link, the LtiSubmissionReviewRequest takes precedence.

3. Availability and Placement of Submission Review Request Message

3.1 Placement

The actual placement will depend on the platform, but the link should logically be present about the same location where the result is displayed. This may be in multiple locations in the platform's interface.

3.2 Timing Of Availability Use Cases

While the tool can indicate that an LTI resource's line item can support Submission Review Request messages, it does not really indicate to the platform when that support should and should not be offered to users in the platform's user experience. The following use-cases can help platforms decide on which timing scenario works best for them. Tools should always gracefully handle submission review message launches from the moment they declare that a line-item can support them, even if that user experience amounts to little more than "nothing has yet occurred here".

3.2.1 Score Available For Review

When the tool has provided a score value for a line-item, instructors (and possibly learners) want to use the Submission Review message to navigate to the tool for further context or explanation about the score value written to the platform.

In this case, the platform should support Submission Review messages from a line-item after a scoreGiven has been written (or updated) by the tool.

3.2.2 Manual Assistance Required To Determine A Score

When the tool expects an instructor or other grading user to manually mark an assessment associated with an LTI resource's line item, grading users want to use Submission Review messages to navigate to the tool to perform this assessment so that a score can be set and then later returned to the platform by the tool.

In this case, the platform should support Submission Review messages from a line-item after the tool uses the Score Service to provide a gradingProgress of PendingManual for the line-item (indicating that manual scoring must take place).

3.2.3 Something Notable Has Happened In The Tool

When the tool expects to provide useful value to instructors and learners about a line-item at various stages throughout the life-cycle of the line-item, instructors and learners want to use Submission Review messages to navigate to the tool whenever the tool has "something new" or notable to present to them.

In this case, the platform should support Submission Review messages from a line-item after the tool makes any status or scoring update on the line-item.

3.3 Line Item Definition Indicates Submission Review Support

Each line item definition will explicitly indicate if its results can be launched for review by including a submissionReview property to the line item definition. The absence of that property indicates the tool does not support submission review launches for results of that line item.

Platforms must ignore unknown properties in JSON payloads, allowing a tool to include the submissionReview property regardless of the platform's current support.

If submission review is to be enabled but there are no options to be specified, then an empty object {} should be passed.

The submissionReview value is a JSON object with the following properties:

label: (optional) if present, the platform may use this label to decorate the link.

url: (optional) if present, the platform must use that value as the target_link_uri. Otherwise, the platform uses the resource link target_link_uri if the line item is coupled with an actual resource link, or the tool base url otherwise.

custom: (optional) a JSON Object where all values are strings. Those custom parameters, if present, must be included in the https://purl.imsglobal.org/spec/lti/claim/custom claim in the submission review message.

The submissionReview can be added to the line item definition included in the LTI Resource Link definition in a Deep Linking Response, or as part of the Assignment and Grade Services call to add or update a line item.

Platforms must include the submissionReview as part of the line item definition when queried through the Assignment and Grade Services call if the submission review message is enable for that line item.

3.3.1 Line Item Defined Via Line Item Service

Here are two example line items that support Submission Review created via the Line Item service.

This first line item depends on the resource's original launch URL endpoint to handle the Submission Review message as well:


{
  "scoreMaximum": 100,
  "label": "Chapter 5 Progress",
  "resourceId": "a-9334df-33",
  "tag": "originality",
  "submissionReview": {
    "label": "Chapter 5"
  }
}

This second line item provides a specific URL endpoint to receive the Submission Review message:


{
  "scoreMaximum": 100,
  "label": "Chapter 5 Progress",
  "resourceId": "a-9334df-33",
  "tag": "originality",
  "submissionReview": {
    "label": "Open My Tool Viewer",
    "url": "https://platform.example.com/act/849023/sub",
    "custom": {
      "action": "review",
      "a_id": "23942"
    }
  }
}

3.3.2 Line Item Defined Via Deep Linking Response

Here is are two example line items that support Submission Review created as part of a Deep Linking Response.

This first line item provides a specific URL endpoint to receive Submission Review messages for the included defined LTI resource.


{
  "type": "ltiResourceLink",
  "title": "A title",
  "text": "This is a link to an activity that will be graded",
  "url": "https://lti.example.com/launchMe",
  "icon": {
    "url": "https://lti.example.com/image.jpg",
    "width": 100,
    "height": 100
  },
  "lineItem": {
    "scoreMaximum": 87,
    "label": "Chapter 12 quiz",
    "resourceId": "xyzpdq1234",
    "tag": "originality",
    "submissionReview": {
      "url": "https://platform.example.com/act/849023/sub"
    }
  }
}

This second line item only signals support for Submission Review messages with no further configuration options defined; the same endpoint used to launch to the LTI resource will also handle Submission Review messages for the resource:


{
  "type": "ltiResourceLink",
  "title": "A title",
  "text": "This is a link to an activity that will be graded",
  "url": "https://lti.example.com/launchMe",
  "icon": {
    "url": "https://lti.example.com/image.jpg",
    "width": 100,
    "height": 100
  },
  "lineItem": {
    "scoreMaximum": 87,
    "label": "Chapter 12 quiz",
    "resourceId": "xyzpdq1234",
    "tag": "originality",
    "submissionReview": {}
  }
}

3.4 Submission Review message examples

This section demonstrates several submission review message payloads.

3.4.1 Coupled Line Item

In this example, the line item is associated with a Resource Link; therefore, the resource link claim and resource link specific custom parameters are included in the message:


{
  "iss": "https://platform.example.org",
  "sub": "a6d5c443-1f51-4783-ba1a-7686ffe3b54a",
  "aud": ["962fa4d8-bcbf-49a0-94b2-2de05ad274af"],
  "exp": 1510185728,
  "iat": 1510185228,
  "azp": "962fa4d8-bcbf-49a0-94b2-2de05ad274af",
  "nonce": "fc5fdc6d-5dd6-47f4-b2c9-5d1216e9b771",
  "name": "Ms Jane Marie Doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "email": "jane@example.org",
  "https://purl.imsglobal.org/spec/lti/claim/deployment_id":
    "07940580-b309-415e-a37c-914d387c1150",
  "https://purl.imsglobal.org/spec/lti/claim/message_type":
    "LtiSubmissionReviewRequest",
  "https://purl.imsglobal.org/spec/lti/claim/version": "1.3.0",
  "https://purl.imsglobal.org/spec/lti/claim/roles": [
    "http://purl.imsglobal.org/vocab/lis/v2/membership#Instructor"
  ],
  "https://purl.imsglobal.org/spec/lti/claim/context": {
    "id": "c1d887f0-a1a3-4bca-ae25-c375edcc131a",
    "label": "ECON 1010",
    "title": "Economics as a Social Science",
    "type": ["CourseOffering"]
  },
  "https://purl.imsglobal.org/spec/lti-ags/claim/endpoint": {
    "scope": [
      "https://purl.imsglobal.org/spec/lti-ags/scope/lineitem",
      "https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly",
      "https://purl.imsglobal.org/spec/lti-ags/scope/score"
    ],
    "lineitems": "https://www.myuniv.edu/2344/lineitems/",
    "lineitem": "https://www.myuniv.edu/2344/lineitems/1234/lineitem"
  },
  "https://purl.imsglobal.org/spec/lti/claim/for_user": {
    "user_id": "1239a-ilt",
    "person_sourcedid": "example.edu:71ee7e42-f6d2-414a-80db-b69ac2defd4",
    "given_name": "Jude",
    "family_name": "Wilbert",
    "email": "jwilbert@example.org",
    "roles": ["http://purl.imsglobal.org/vocab/lis/v2/membership#Learner"]
  },
  "https://purl.imsglobal.org/spec/lti/claim/resource_link": {
    "id": "200d101f-2c14-434a-a0f3-57c2a42369fd",
    "description": "Assignment to introduce who you are",
    "title": "Introduction Assignment"
  },
  "https://purl.imsglobal.org/spec/lti/claim/launch_presentation": {
    "return_url": "http://example.org/returnToGradebook"
  },
  "https://purl.imsglobal.org/spec/lti/claim/custom": {
    "activity_id": "123"
  },
  "https://purl.imsglobal.org/spec/lti/claim/tool_platform": {
    "guid": "89023890238:4327238",
    "product_family_code": "example.org"
  }
}

3.5 Standalone Line item

In this example, the line item is not associated with any Resource Link; therefore, no resource link related data is included in the message:


{
  "iss": "https://platform.example.org",
  "sub": "a6d5c443-1f51-4783-ba1a-7686ffe3b54a",
  "aud": ["962fa4d8-bcbf-49a0-94b2-2de05ad274af"],
  "exp": 1510185728,
  "iat": 1510185228,
  "azp": "962fa4d8-bcbf-49a0-94b2-2de05ad274af",
  "nonce": "fc5fdc6d-5dd6-47f4-b2c9-5d1216e9b771",
  "name": "Ms Jane Marie Doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "email": "jane@example.org",
  "https://purl.imsglobal.org/spec/lti/claim/deployment_id":
    "07940580-b309-415e-a37c-914d387c1150",
  "https://purl.imsglobal.org/spec/lti/claim/message_type":
    "LtiSubmissionReviewRequest",
  "https://purl.imsglobal.org/spec/lti/claim/version": "1.3.0",
  "https://purl.imsglobal.org/spec/lti/claim/roles": [
    "http://purl.imsglobal.org/vocab/lis/v2/membership#Instructor"
  ],
  "https://purl.imsglobal.org/spec/lti/claim/context": {
    "id": "c1d887f0-a1a3-4bca-ae25-c375edcc131a",
    "label": "ECON 1010",
    "title": "Economics as a Social Science",
    "type": ["CourseOffering"]
  },
  "https://purl.imsglobal.org/spec/lti-ags/claim/endpoint": {
    "scope": [
      "https://purl.imsglobal.org/spec/lti-ags/scope/lineitem",
      "https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly",
      "https://purl.imsglobal.org/spec/lti-ags/scope/score"
    ],
    "lineitems": "https://www.myuniv.edu/2344/lineitems/",
    "lineitem": "https://www.myuniv.edu/2344/lineitems/1234/lineitem"
  },
  "https://purl.imsglobal.org/spec/lti/claim/for_user": {
    "user_id": "1239a-ilt",
    "person_sourcedid": "example.edu:71ee7e42-f6d2-414a-80db-b69ac2defd4",
    "given_name": "Jude",
    "family_name": "Wilbert",
    "email": "jwilbert@example.org",
    "roles": ["http://purl.imsglobal.org/vocab/lis/v2/membership#Learner"]
  },
  "https://purl.imsglobal.org/spec/lti/claim/launch_presentation": {
    "return_url": "http://example.org/returnToGradebook"
  },
  "https://purl.imsglobal.org/spec/lti/claim/tool_platform": {
    "guid": "89023890238:4327238",
    "product_family_code": "example.org"
  }
}

3.5.1 Conformance Statements

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHALL, SHALL NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in [RFC2119].

An implementation of this specification that fails to implement a MUST/REQUIRED/SHALL requirement or fails to abide by a MUST NOT/SHALL NOT prohibition is considered nonconformant. SHOULD/SHOULD NOT/RECOMMENDED statements constitute a best practice. Ignoring a best practice does not violate conformance but a decision to disregard such guidance should be carefully considered. MAY/OPTIONAL statements indicate that implementers are entirely free to choose whether or not to implement the option.

A. Revision History

This section is non-normative.

Spec Version Document Version Release Date Comments
1.0 draft 1 September 10, 2019 First release of draft document.
1.0 draft 2 April 1, 2022 Removed reviewableStatus attribute
1.0 draft 3 24 January 2023 Add example of empty submission review key (docs)
1.0 Candidate Final Public 4 21 July 2023 Updated status to Candidate Final Public

B. References

B.1 Normative references

[LTI-13]
IMS Global Learning Tools Interoperability (LTI)® Core Specification v1.3. C. Vervoort; N. Mills. IMS Global Learning Consortium. April 2019. IMS Final Release. URL: https://www.imsglobal.org/spec/lti/v1p3/
[LTI-AGS-20]
IMS Global Learning Tools Interoperability (LTI)® Assignment and Grade Services. C. Vervoort; E. Preston; M. McKell; J. Rissler. IMS Global Learning Consortium. April 2019. IMS Final Release. URL: https://www.imsglobal.org/spec/lti-ags/v2p0/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119

C. List of Contributors

The following individuals contributed to the development of this document:

Name Organization Role
Martin LenordTurnitin
Bracken MosbackerIMS Global
Marc PhillipsInstructure
Jesse PoulosInstructure
Eric PrestonBlackboard
Claude VervoortCengageEditor

IMS Global Learning Consortium, Inc. ("IMS Global") is publishing the information contained in this document ("Specification") for purposes of scientific, experimental, and scholarly collaboration only.

IMS Global makes no warranty or representation regarding the accuracy or completeness of the Specification.

This material is provided on an "As Is" and "As Available" basis.

The Specification is at all times subject to change and revision without notice.

It is your sole responsibility to evaluate the usefulness, accuracy, and completeness of the Specification as it relates to you.

IMS Global would appreciate receiving your comments and suggestions.

Please contact IMS Global through our website at http://www.imsglobal.org.

Please refer to Document Name: Learning Tools Interoperability (LTI)® Submission Review Service 1.0

Date: April 01, 2022