Learning Tools Interoperability Basic Outcomes Version 1.1

Learning Tools Interoperability Basic Outcomes

IMS Final Release
Version 1.1
IMS Final Release
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.

IMS 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 IMS's procedures with respect to rights in IMS specifications can be found at the IMS Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.

Copyright © 2019 IMS Global Learning Consortium. All Rights Reserved.

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.

© 2019 IMS Global Learning 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 IMS 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.

The Tool taking advantage of LIS services.
Figure 1 The Tool taking advantage of LIS services.

  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 "IMS 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.

<?xml version="1.0" encoding="UTF-8"?>
<imsx_POXEnvelopeResponse xmlns="http://www.imsglobal.org/services/ltiv1p1/xsd/imsoms_v1p0">
<imsx_POXHeader>
  <imsx_POXResponseHeaderInfo>
    <imsx_version>V1.0</imsx_version>
    <imsx_messageIdentifier>4560</imsx_messageIdentifier>
    <imsx_statusInfo>
      <imsx_codeMajor>unsupported</imsx_codeMajor>
      <imsx_severity>status</imsx_severity>
      <imsx_description>readPerson is not supported</imsx_description>
      <imsx_messageRefIdentifier>999999123</imsx_messageRefIdentifier>
      <imsx_operationRefIdentifier>readPerson</imsx_operationRefIdentifier>
    </imsx_statusInfo>
  </imsx_POXResponseHeaderInfo>
</imsx_POXHeader>
<imsx_POXBody/>
</imsx_POXEnvelopeResponse>
Figure 2

See “Table A1.2 Interpretation of the ‘CodeMajor/severity’ matrix” from IMS 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.

<?xml version="1.0" encoding="UTF-8"?>
<imsx_POXEnvelopeRequest xmlns="http://www.imsglobal.org/services/ltiv1p1/xsd/imsoms_v1p0">
<imsx_POXHeader>
  <imsx_POXRequestHeaderInfo>
    <imsx_version>V1.0</imsx_version>
    <imsx_messageIdentifier>999999123</imsx_messageIdentifier>
  </imsx_POXRequestHeaderInfo>
</imsx_POXHeader>
<imsx_POXBody>
  <replaceResultRequest>
    <resultRecord>
      <sourcedGUID>
        <sourcedId>3124567</sourcedId>
      </sourcedGUID>
      <result>
        <resultScore>
          <language>en</language>
          <textString>0.92</textString>
        </resultScore>
      </result>
    </resultRecord>
  </replaceResultRequest>
</imsx_POXBody>
</imsx_POXEnvelopeRequest>
Figure 3

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".

<?xml version="1.0" encoding="UTF-8"?>
<imsx_POXEnvelopeResponse xmlns="http://www.imsglobal.org/services/ltiv1p1/xsd/imsoms_v1p0">
<imsx_POXHeader>
  <imsx_POXResponseHeaderInfo>
    <imsx_version>V1.0</imsx_version>
    <imsx_messageIdentifier>4560</imsx_messageIdentifier>
    <imsx_statusInfo>
      <imsx_codeMajor>success</imsx_codeMajor>
      <imsx_severity>status</imsx_severity>
      <imsx_description>Score for 3124567 is now 0.92</imsx_description>
      <imsx_messageRefIdentifier>999999123</imsx_messageRefIdentifier>
      <imsx_operationRefIdentifier>replaceResult</imsx_operationRefIdentifier>
    </imsx_statusInfo>
  </imsx_POXResponseHeaderInfo>
</imsx_POXHeader>
<imsx_POXBody>
  <replaceResultResponse />
</imsx_POXBody>
</imsx_POXEnvelopeResponse>
Figure 4

  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.

<?xml version="1.0" encoding="UTF-8"?>
<imsx_POXEnvelopeRequest xmlns="http://www.imsglobal.org/services/ltiv1p1/xsd/imsoms_v1p0">  <imsx_POXHeader>
<imsx_POXRequestHeaderInfo>
  <imsx_version>V1.0</imsx_version>
  <imsx_messageIdentifier>999999123</imsx_messageIdentifier>
</imsx_POXRequestHeaderInfo>
</imsx_POXHeader>
<imsx_POXBody>
<readResultRequest>
  <resultRecord>
    <sourcedGUID>
      <sourcedId>3124567</sourcedId>
    </sourcedGUID>
  </resultRecord>
</readResultRequest>
</imsx_POXBody>
</imsx_POXEnvelopeRequest>
Figure 5

The readResultResponse returns the current score in the body area of the returned message.

<?xml version="1.0" encoding="UTF-8"?>
<imsx_POXEnvelopeResponse xmlns="http://www.imsglobal.org/services/ltiv1p1/xsd/imsoms_v1p0">
<imsx_POXHeader>
  <imsx_POXResponseHeaderInfo>
    <imsx_version>V1.0</imsx_version>
    <imsx_messageIdentifier>1313355158804</imsx_messageIdentifier>
    <imsx_statusInfo>
      <imsx_codeMajor>success</imsx_codeMajor>
      <imsx_severity>status</imsx_severity>
      <imsx_description>Result read</imsx_description>
      <imsx_messageRefIdentifier>999999123</imsx_messageRefIdentifier>
      <imsx_operationRefIdentifier>readResult</imsx_operationRefIdentifier>
    </imsx_statusInfo>
  </imsx_POXResponseHeaderInfo>
</imsx_POXHeader>
<imsx_POXBody>
  <readResultResponse>
    <result>
      <resultScore>
        <language>en</language>
        <textString>0.91</textString>
      </resultScore>
    </result>
  </readResultResponse>
</imsx_POXBody>
</imsx_POXEnvelopeResponse>
Figure 6

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.

<?xml version="1.0" encoding="UTF-8"?>
<imsx_POXEnvelopeRequest xmlns="http://www.imsglobal.org/services/ltiv1p1/xsd/imsoms_v1p0">
<imsx_POXHeader>
  <imsx_POXRequestHeaderInfo>
    <imsx_version>V1.0</imsx_version>
    <imsx_messageIdentifier>999999123</imsx_messageIdentifier>
  </imsx_POXRequestHeaderInfo>
</imsx_POXHeader>
<imsx_POXBody>
  <deleteResultRequest>
    <resultRecord>
      <sourcedGUID>
        <sourcedId>3124567</sourcedId>
      </sourcedGUID>
    </resultRecord>
  </deleteResultRequest>
</imsx_POXBody>
</imsx_POXEnvelopeRequest>
Figure 7

The deleteResultResponse indicates the success / failure of the operation in the header area of the response and as such the body area is empty.

<?xml version="1.0" encoding="UTF-8"?>
<imsx_POXEnvelopeResponse xmlns = "http://www.imsglobal.org/services/ltiv1p1/xsd/imsoms_v1p0">
<imsx_POXHeader>
  <imsx_POXResponseHeaderInfo>
    <imsx_version>V1.0</imsx_version>
    <imsx_messageIdentifier>4560</imsx_messageIdentifier>
    <imsx_statusInfo>
      <imsx_codeMajor>success</imsx_codeMajor>
      <imsx_severity>status</imsx_severity>
      <imsx_messageRefIdentifier>999999123</imsx_messageRefIdentifier>
      <imsx_operationRefIdentifier>deleteResult</imsx_operationRefIdentifier>
    </imsx_statusInfo>
  </imsx_POXResponseHeaderInfo>
</imsx_POXHeader>
<imsx_POXBody>
  <deleteResultResponse />
</imsx_POXBody>
</imsx_POXEnvelopeResponse>
Figure 8

  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:

{
"@type": "RestService",
"@id": "tcp:Outcomes.LTI1",
"endpoint": "https://lms.example.com/lti/outcomev1",
"format": ["application/vnd.ims.lti.v1.outcome+xml"],
"action": ["POST"]
}
Figure 9

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.

{
"lis_result_sourcedid": "82098-21uhd",
"lis_outcome_service_url": "https://www.myuniv.example.com/2344"
}
Figure 10

  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 DateComments
Outcomes Management v1.05 January 2015The first version of the Outcomes Management specification, including the Basic Outcomes service model.
Basic Outcomes v1.17 May 2019Replaces 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.

  B. References

  B.1 Normative references

[GWS-10]
IMS Global General Web Services WSDL Binding Guidelines v1.0. C. Schroeder; J. Simon; C. Smythe. IMS Global Learning Consortium. January 2006. URL: https://www.imsglobal.org/gws/
[LIS-20]
IMS Global Learning Information Services v2.0. L. Feng; W. Lee; C. Smythe. IMS Global Learning Consortium. June 2011. URL: https://www.imsglobal.org/lis/
[LIS-OMS]
IMS Outcomes Management Service Information Model v1.0. L. Feng; W. Lee; C. Smythe. IMS Global Learning Consortium. March 2010. URL: https://www.imsglobal.org/lis/
[LTI-11]
IMS Global Learning Tools Interoperability® Implementation Guide. G. McFall; M. McKell; L. Neumann; C. Severance. IMS Global Learning Consortium. March 13, 2012. URL: https://www.imsglobal.org/specs/ltiv1p1
[LTI-13]
IMS Global Learning Tools Interoperability® 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® 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/
[LTI-OUT]
IMS Global Learning Tools Interoperability® Outcomes Management. S. Vickers. IMS Global Learning 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]
IMS Global Security Framework v1.0. C. Smythe; C. Vervoort; M. McKell; N. Mills. IMS Global Learning Consortium. April 2019. IMS 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 GrayLearning Objects
Viktor HaagD2L
Dereck HaskinsIMS Global
Martin LenordTurnitin
Karl LloydInstructure
Mark McKellIMS Global
Nathan MillsInstructure
Bracken MosbackerLumen Learning
Padraig O'hiceadhaHMH
Marc PhillipsInstructure
Eric PrestonBlackboard
James RisslerIMS Global
Charles SeveranceUniversity of Michigan
Tom SmallSchoology
Colin SmytheIMS Global
Nick ThompsonUCLA
Claude VervoortCengageEditor
Jim WalkoskiD2L

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 Basic Outcomes 1.1

Date: 7 May 2019