Learning Tools Interoperability Basic Outcomes Version 1.1
Version 1.1
Date Issued: | 7 May 2019 |
Status: | This document is made available for adoption by the public community at large. |
This version: | https://www.imsglobal.org/spec/lti-bo/v1p1/ |
Latest version: | https://www.imsglobal.org/spec/lti-bo/latest/ |
Errata: | https://www.imsglobal.org/spec/lti-bo/v1p1/errata/ |
IPR and Distribution Notices
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.
1EdTech takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the 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 1EdTech's procedures with respect to rights in 1EdTech specifications can be found at the 1EdTech Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.
Copyright © 2019 1EdTech Consortium. All Rights Reserved.
Use of this specification to develop products or services is governed by the license with 1EdTech found on the 1EdTech 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 1EdTech 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.
© 2019 1EdTech Consortium, Inc. All Rights Reserved.
Trademark information: http://www.imsglobal.org/copyright.html
Abstract
This document provides an update to the original LTI Outcomes Management v1.0 specification [LTI-OUT]. Now called LTI Basic Outcome v1.1, this updated document adds a section that defines a way to migrate from the LTI v1.1 Outcomes Management service to the latest LTI v1.3 [LTI-13] and Assignment and Grade Services [LTI-AGS-20].
1. Overview
1.1 Scope
Outcomes Management is based on 1EdTech Learning Information Services [LIS-20]. Within the Learning Tools Interoperability (LTI) specification a Tool Consumer (TC) may optionally provide support for Outcomes to a Tool Provider (TP). The TC need not be the system which delivers the service to the TP; the LIS services could be provided by a third system such as a Student Information System.
1.2 Deprecation notice
This specification is deprecated in favor of [LTI-AGS-20].
See the Migrating from basic outcome section in the Assignment and Grade Services specification [LTI-AGS-20] for more details.
1.3 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.
2. Launch Parameters for Outcomes Management
In order to support grade return from the TP to the TC using the Basic Outcomes service described in this document, the following launch parameters are defined:
2.1 The lis_result_sourcedid
parameter
lis_result_sourcedid=83873872987329873264783687634
This parameter contains an identifier that indicates the LIS Result Identifier (if any) associated with this launch. It identifies a unique row and column within the TC gradebook. This identifier is unique for every combination of resource_link_id / user_id but its value may change from one launch to the next. The TP should only retain the most recent value for this field for a particular resource_link_id / user_id. This parameter is optional.
2.2 The lis_outcome_service_url
parameter
lis_outcome_service_url=https://mylms.com/outcome
This parameter should be no more than 1023 characters long. This value should not change from one launch to the next and in general, the TP can expect that there is a one-to-one mapping between the lis_outcome_service_url
and a particular oauth_consumer_key
. This value might change if there was a significant re-configuration of the TC system or if the TC moved from one domain to another. The TP can assume that this URL generally does not change from one launch to the next but should be able to deal with cases where this value rarely changes. The service URL may support various operations / actions. The Basic Outcomes Service Provider will respond with a response of 'unimplemented' for actions it does not support. This field is required if the TC is accepting outcomes for any launches associated with the resource_link_id.
A typical implementation pattern is for the Outcomes Service Provider to only accept outcomes for launches with a role of "Learner". If this were the case, the TC would only provide lis_result_sourcedid values on launches with a "Learner" role. If the TC is configured to accept outcomes on a particular launch, the TC is required to include lis_outcome_service_url regardless of the role in the launch and regardless of whether or not a lis_result_sourcedid
is included in the launch.
These services are based on server-to-server trust and as such do not need to be called synchronously in the context of a particular user's launch and session. The TP may retain the lis_outcome_service_url
and lis_result_sourcedid
from a launch and then call the service long after the user's session has ended. This allows the TP to collect grades and upload them to the TC in batches or perhaps collect grades and upload them to the TP when an instructor clicks a button within the TP.
3. Basic outcome service
The endpoint for this service receives "Plain Old XML" (POX) messages signed using OAuth body signing [LTI-11]. The service supports setting, retrieving and deleting LIS results associated with a particular user/resource combination.
The only type of grade supported by this service is a decimal numeric grade in the range from 0.0 - 1.0. Additional types of outcomes and the ability for the TP to perform more detailed outcomes operations may be added at a later date.
See Section 3 in the "1EdTech Outcomes Management Service Information Model" [LIS-OMS] for details on the parameters and return values for the operations described in this section.
The service endpoint must accept any well-formed request with properly formed headers that pass security checks (e.g., signature is valid) and return a well-formed "unsupported" response.
See “Table A1.2 Interpretation of the ‘CodeMajor/severity’ matrix” from 1EdTech General Web Services WSDL Binding Guidelines [GWS-10] for further details on header values for 'unsupported' or 'failure' responses.
Since these services use OAuth signing, in order to avoid revealing the key and secret, the best practice is for these services to be called as server-to-server web services. It is not possible to provide the browser with the key and secret to sign these messages without risking the loss of the key and secret. As a best practice, in production situations, these services should be accessed using secure http (i.e., https) to avoid man-in-the-middle and other security attacks.
3.1 replaceResult
The replaceResultRequest
sets a numeric grade (0.0 - 1.0) for a particular result sourcedId.
It is up to the TC as to whether this operation actually replaces the grade, or if the TC maintains a history of all grade values. If the TC is maintaining grade history, the TP is generally only operating on the "most recent" grade. The TP has no knowledge of the TC approach to grade history and should treats the grades as though there is only a single grade for each lis_result_sourcedid.
The sourcedId
element is the value from the lis_result_sourcedid
parameter for a particular user_id / resource_link_id combination. The TP records these values as they are sent on launches and can then later make services calls providing the sourcedId as way to pick the particular cell in the TC grade book.
For this particular service, all of the values for textString are decimal values numeric in the range 0.0 - 1.0. Regardless of the language of the TP or TC user interface, the number format is to use a period as the decimal point. Regardless of the language of the TP or TC user interface, the language field in the service call is to be “en” indicating the format of the number. While the TP is required to include “en” as the language, the TC will likely ignore the language field in this request and always assume that the number is formatted using “en” formatting.
The replaceResultResponse
indicates the success/failure of the operation in the header area of the response and as such the body area is empty.
The TC must check the incoming grade for validity and must fail when a grade is outside the range 0.0-1.0 or if the grade is not a valid number. The TC must respond to these replaceResult operations with a imsx_codeMajor of "failure".
3.2 readResult
The readResultRequest
returns the current grade for a particular result lis_result_sourcedid
.
It is up to the TC as to whether it maintains a history of all grade values. If the TC is maintaining grade history, the TP will see the "most recent" grade. The TP has no knowledge of the TC approach to grade history and should treat the grades as though there is only a single grade for each lis_result_sourcedid.
If the grade has not yet been set via a replaceResult operation or an existing grade has been deleted via a deleteResult operation, the TC should return a valid response with a present but empty textString element. The TC should not return 0.0 to indicate a non-existent grade and the TC should not return a failure status when a grade does not exist. It should simply return an "empty" grade.
The readResultResponse
returns the current score in the body area of the returned message.
The format of the text string is a decimal value in the range 0.0 - 1.0 with a period character as the decimal point. The TC will always return “en” as the language regardless of the value for language provided by the TP in any previous replaceResult operation. The language field indicates the language to be used in the interpretation of the numeric format, not the language of the TC or TP user interface.
3.3 deleteResult
The deleteResultRequest
deletes the grade for a particular result lis_result_sourcedid
.
It is up to the TC as to whether it maintains a history of all grade values. If the TC is maintaining grade history, it is up to the TC to define its internal meaning of the deleteResult operation. The TC may delete the most recent grade reverting to a prior grade, or it may actually completely erase the grade, or it may simply retain the previous value for a grade and mark the grade as "soft deleted". Since the TP will be expecting that its grade will have been deleted, it would be best if the TC also reflected that in its gradebook view of the "current grades".
The TP should treat its grade as being a single item without any history and accept the fact that TCs may vary on how they alter their internal structures upon response to this request.
Regardless of how the TC decides to handle deletes internally, it should provide a view for the TP that reflects that there is no longer any grade associated with the given lis_result_sourcedid
. So a readResult after a deleteResult would normally return an empty grade as if replaceResult had never been called unless the grade was manipulated in the TC user interface because of another service call.
The deleteResultResponse
indicates the success / failure of the operation in the header area of the response and as such the body area is empty.
3.4 Declaring the basic outcome service in tool consumer Profile
The Basic Outcomes service may be declared in the service_offered section of a Tool Consumer Profile as follows:
The values of the @id
and endpoint elements are illustrative only.
3.5 Integration with LTI 1.3
3.5.1 Claim for inclusion in messages
The claim to include basic outcome parameters in LTI 1.3 messages is:
https://purl.imsglobal.org/spec/lti-bo/claim/basicoutcome
.
It contains two properties: lis_outcome_service_url
and lis_result_sourcedid
as
defined above.
3.5.2 Service access and Scope
To access this service, an Authorization header with a properly scoped token must be included in the request as defined in LTI Security Framework [SEC-10].
The scope to be requested for this service is:
Scope | Description | Allowed HTTP Methods |
---|---|---|
https://purl.imsglobal.org/spec/lti-bo/scope/basicoutcome |
Tool can read/write results | lis_outcome_service_url : POST, any POX command |
A. Revision History
This section is non-normative.
A.1 Version History
Version No. | Release Date | Comments |
---|---|---|
Outcomes Management v1.0 | 5 January 2015 | The first version of the Outcomes Management specification, including the Basic Outcomes service model. |
Basic Outcomes v1.1 | 7 May 2019 | Replaces Basic Outcomes defined in the LTI v1.1 specifications. |
A.2 Changes in this version
Changes in this version of Basic Outcomes Specification are detailed below.
- Added Integration with LTI 1.3 section.
B. References
B.1 Normative references
- [GWS-10]
- 1EdTech General Web Services WSDL Binding Guidelines v1.0. C. Schroeder; J. Simon; C. Smythe. 1EdTech Consortium. January 2006. URL: https://www.imsglobal.org/gws/
- [LIS-20]
- 1EdTech Learning Information Services v2.0. L. Feng; W. Lee; C. Smythe. 1EdTech Consortium. June 2011. URL: https://www.imsglobal.org/lis/
- [LIS-OMS]
- 1EdTech Outcomes Management Service Information Model v1.0. L. Feng; W. Lee; C. Smythe. 1EdTech Consortium. March 2010. URL: https://www.imsglobal.org/lis/
- [LTI-11]
- 1EdTech Learning Tools Interoperability® Implementation Guide. G. McFall; M. McKell; L. Neumann; C. Severance. 1EdTech Consortium. March 13, 2012. URL: https://www.imsglobal.org/specs/ltiv1p1
- [LTI-13]
- 1EdTech Learning Tools Interoperability (LTI)® Core Specification v1.3. C. Vervoort; N. Mills. 1EdTech Consortium. April 2019. 1EdTech Final Release. URL: https://www.imsglobal.org/spec/lti/v1p3/
- [LTI-AGS-20]
- 1EdTech Learning Tools Interoperability (LTI)® Assignment and Grade Services. C. Vervoort; E. Preston; M. McKell; J. Rissler. 1EdTech Consortium. April 2019. 1EdTech Final Release. URL: https://www.imsglobal.org/spec/lti-ags/v2p0/
- [LTI-OUT]
- 1EdTech Learning Tools Interoperability (LTI)® Outcomes Management. S. Vickers. 1EdTech Consortium. January 2015. URL: https://www.imsglobal.org/specs/ltiomv1p0/specification
- [RFC2119]
- Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
- [SEC-10]
- 1EdTech Security Framework v1.0. C. Smythe; C. Vervoort; M. McKell; N. Mills. 1EdTech Consortium. April 2019. 1EdTech Final Release. URL: https://www.imsglobal.org/spec/security/v1p0/
C. List of Contributors
The following individuals contributed to the development of this document:
Name | Organization | Role |
---|---|---|
Paul Gray | Learning Objects | |
Viktor Haag | D2L | |
Dereck Haskins | 1EdTech | |
Martin Lenord | Turnitin | |
Karl Lloyd | Instructure | |
Mark McKell | 1EdTech | |
Nathan Mills | Instructure | |
Bracken Mosbacker | Lumen Learning | |
Padraig O'hiceadha | HMH | |
Marc Phillips | Instructure | |
Eric Preston | Blackboard | |
James Rissler | 1EdTech | |
Charles Severance | University of Michigan | |
Tom Small | Schoology | |
Colin Smythe | 1EdTech | |
Nick Thompson | UCLA | |
Claude Vervoort | Cengage | Editor |
Jim Walkoski | D2L |