IMS Public Draft

IMS Global Learning Tools Interoperability™ Outcomes Management

Public Draft Version 1.0

Date Issued: 7 April 2014

Latest version: http://www.imsglobal.org/lti

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 © 2014 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/license.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.

Join the discussion and post comments on the LTI Public Forum: http://www.imsglobal.org/community/forum/categories.cfm?catid=44

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

The IMS Logo and Learning Tools Interoperability (LTI) are trademarks of the IMS Global Learning Consortium, Inc. in the United States and/or other countries.
Document Name: IMS Global Learning Tools Interoperability Outcomes Management
v1.0 Public Draft – Revision: 7 April 2014

# Table of Contents

1 Introduction.. 3

1.1 Scope.. 3

1.2 References. 3

2 Launch Parameters for Outcomes Management.. 4

3 Basic Outcomes Service.. 5

3.1 replaceResult.. 5

3.2 readResult.. 6

3.3 deleteResult.. 7

3.4 Declaring the Basic Outcomes Service.. 8

About This Document.. 9

List of Contributors. 9

Revision History.. 10

# 1 Introduction

## 1.1 Scope

Outcomes Management is based on IMS Learning Information Services (LIS) [LIS, 11]. 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.

Figure 1.1 The TP taking advantage of LIS services

This document describes how a TC declares its support for Outcomes Management to a TP and describes the services made available to a TP. The Basic Outcomes service described in this document provide a mechanism for a TP to set, retrieve and delete LIS results for users in the TC gradebook.

## 1.2 References

[GWS, 06] IMS Global General Web Services WSDL Binding Guidelines v1.0, C. Schroeder, J. Simon and C. Smythe, IMS Global Learning Consortium, January 2006. http://www.imsglobal.org/gws/.

[LIS, 11] IMS Global Learning Information Services v2.0, L. Feng, W. Lee and C. Smythe, IMS Global Learning Consortium, June 2011. http://www.imsglobal.org/lis/.

[LIS, 11 OMS] IMS Outcomes Management Service Information Model v1.0, L. Feng and C. Smythe, IMS Global Learning Consortium, March 2010, http://www.imsglobal.org/lis/.

[LTI, 14] IMS Global Learning Tools Interoperability Implementation Guide v1.2, Public Draft, IMS Global Learning Consortium, G. McFall, M. McKell, L. Neumann and S. Vickers, April 2014. http://www.imsglobal.org/lti/.

# 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:

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.

lis_outcome_service_url=
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 Outcomes Service

The endpoint for this service receives "Plain Old XML" (POX) messages signed using OAuth body signing [LTI, 14]. 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, 11 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>

See “Table A1.2 Interpretation of the ‘CodeMajor/severity’ matrix” from IMS General Web Services WSDL Binding Guidelines [GWS, 06] 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>

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>

## 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>

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>

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>

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>

## 3.4 Declaring the Basic Outcomes Service

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"]
}

The values of the @id and endpoint elements are illustrative only.

# About This Document

Title: IMS Global

Editor: Stephen Vickers (IMS Global)

Version: 1.0

Version Date: 7 April 2014

Release: Public Draft

Purpose: This document is made available for comment by the public community at large.

Document Location: http://www.imsglobal.org/lti

## List of Contributors

The following individuals contributed to the development of this document:

Greg McFall Pearson | Matthew Stoelting Cengage
Mark McKell IMS Global | John Tibbetts VitalSource
Lance Neumann Blackboard | Stephen Vickers IMS Global
Charles Severance IMS Global | Alan Zaitchik Jenzabar
Colin Smythe IMS Global |

# Revision History

Version No. | Release Date | Comments
Public Draft v1.0 | 7 April 2014 | The first release of this document to accompany the LTI v1.2 specification.

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: IMS Global Learning Tools Interoperability Outcomes Management

Date: 7 April 2014