IMS Final Release

IMS Global Learning Tools Interoperability™ Tool Settings Service

 

 

Version 1.0 Final Specification

 

Date Issued:            6 January 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 Tool Settings Service
v1.0 Final – Revision: 6 January 2014


1                  Introduction

This document describes the Tool Settings Management web service that Tool Consumers implement. This service allows the Tool Provider to read and write settings for a Tool Proxy instance. A given Tool may have settings attached to different resources within a Tool Consumer.  For example, it may have global settings that are defined system-wide; it may have context-specific settings that are defined at the level of, for example, a course; and, finally it may have settings that are defined for each link to the Tool. The LTI Tool Settings Service is a web service that allows applications within the Tool Provider to manage those settings in the Tool Consumer.  This specification provides an information model for the LTI Tool Settings Service.

There are many use cases for the Tool Settings service.  For example, to allow a Tool Provider to receive a licence reference in each basic-lti-launch-request message, or for a publisher to associate a course with the ISBN number of the recommended text.

1.1              Nomenclature

A list of and definitions for commonly used terms in the LTI specification are contained in the LTI Implementation Guide document [LTI, 14 IMG].

1.2              References

 [LTI, 14 IMG]             G.McFall, L.Neumann, S Vickers, IMS Global Learning Tools Interoperability Implementation Guide v2.0 Final, IMS Global Learning Consortium, January 2014. http://www.imsglobal.org/lti/index.html.

[LTI, 14 SEC]               G.McFall, L.Neumann, S.Vickers, IMS Global Learning Tools Interoperability Security v2.0 Final, IMS Global Learning Consortium, January 2014. http://www.imsglobal.org/lti/

 

 

2                  Behavioral Model

2.1       LTIToolSettingsService Interface

This service allows the Tool Provider to read and write settings for a Tool Proxy instance.  A Tool Consumer implementing this service must include all applicable settings in each message sent to the Tool Provider.  The settings should also be maintained by the Tool Consumer with operations performed on the resource to which they are attached (see below); for example, when a course is copied, archived or restored.

All operations on this service will access only settings within the scope of one particular tool specified by the toolProxyGUID parameter. Implementations must ensure that these settings are accessed only by authorized clients. Typically, the only authorized client will be the Tool Provider identified by the Tool Proxy GUID.  However, there may be special cases where the client is some other system (such as an orchestration engine acting on behalf of the Tool Provider).  The mechanism by which authorization is granted to systems other than the Tool Provider is outside the scope of this specification.

 

Figure 2.1 LTIToolSettingsService interface definition.

Settings must be associated with one of the following resources:

  1. Tool Proxy – these settings are system-wide and apply to all launches using this Tool Proxy;
  2. Context – these settings apply to all launches using the Tool Proxy from within the same context; this context would normally be a course (context type of CourseSection) but would be identified by the unique context_id parameter;
  3. LTI link – these settings apply to launches for the Tool Proxy from a specific LTI link created within a context.

The Tool Consumer must provide an endpoint for each of the three different resources via the following LTI custom parameter substitution variables:

  1. ToolProxy.custom.url – the endpoint URI for accessing system-wide tool settings
  2. ToolProxyBinding.custom.url – the endpoint URI for accessing context-level tool settings
  3. LtiLink.custom.url – the endpoint URI for accessing link-level tool settings

Each of these endpoints should support GET and PUT requests.  GET requests should also support an optional query parameter named bubble which should have a valiue of either all or distinct to specify that settings from parent resource containers should be included in the response and whether all settings with the same name should be returned or just the one from the lowest resource level. Only the setting from the lowest resource level will be included in an LTI launch request when a name conflict occurs. Further details can be found in the ToolSettingsContainer Service section of the HTML documentation.

 

3                  Information Model

The tool settings service operates on the collection of settingsfor particular resources and not on individual settings..  The settingsmay be represented using either of the following media types which are defined in the accompanying HTML documentation:

  • application/vnd.ims.lti.v2.toolsettings+json
  • application/vnd.ims.lti.v2.toolsettings.simple+json

For example, the following request might be used to obtain details of settings assigned to an LTI link:

GET /resources/LtiLink/17001/custom
Host: tc.example.com
Accept: application/vnd.ims.lti.v2.toolsettings.simple+json

for which the  response might be:

HTTP/1.0 200 OK
Date: Thu, 10 March 2013 11:09:42 GMT
Content-Type: application/vnd.ims.lti.v2.toolsettings.simple+json
Content-Length: 117

{
  "chapter" : "3",
  "section" : "1",
  "isbn" : "978-0321558145",
  "style" : "jazzy",
  "customerId" : "394892759526"
}

To change the value of the style setting and add a new setting named format use a request of the following form:

PUT /resources/LtiLink/17001/custom
Host: tc.example.com
Content-Type: application/vnd.ims.lti.v2.toolsettings.simple+json
Content-Length: 143

{
  "chapter" : "3",
  "section" : "1",
  "isbn" : "978-0321558145",
  "style" : "plain",
  "format" : "continuous",
  "customerId" : "394892759526"
}

to which the expected response would be:

HTTP/1.0 200 OK
Date: Thu, 10 March 2013 11:09:42 GMT

A request for settings from all resource levels above the LTI link (that is including those from the Proxy Tool binding and Proxy Tool containers) would take the following form:

GET /resources/LtiLink/17001/custom?bubble=all
Host: tc.example.com
Accept: application/vnd.ims.lti.v2.toolsettings+json

Use the application/vnd.ims.lti.v2.toolsettings+json media type to include the level at which a setting has been defined in the response.  For example:

 

{
  "@context" : "http://purl.imsglobal.org/ctx/lti/v2/ToolSettings",
  "@graph" : [
    { "@type" : "LtiLink",
      "@id" : "http://tc.example.com/resources/LtiLink/17001",
      "custom_uri" : "http://tc.example.com/resources/LtiLink/17001/custom",
      "custom" : {
         "chapter" : "3",
         "section" : "1"
      }
    },
    { "@type" : "ToolProxyBinding",
      "@id" : "http://tc.example.com/courses/0294823738/bindings/tp.example.com/ebook",
      "custom_uri" : "http://tc.example.com/courses/0294823738/bindings/tp.example.com/ebook/custom",
      "custom" : {
        "isbn" : "978-0321558145",
        "style" : "jazzy"
      }
    },
    { "@type" : "ToolProxy",
      "@id" : "http://tc.example.com/resources/ToolProxy/79833",
      "custom_uri" : "http://tc.example.com/resources/ToolProxy/79833/custom",
      "custom" : {
        "customerId" : "394892759526"
      }
    }
  ]
}

 

 

Figure 3.1  Example of level setting defined in the response

Note that all service requests should be secured by signing them using the lti_oauth_body_hash_ws_security Web Services Security Profile as described in the Security document [LTI 14, SEC].

 

About This Document

 

Title: IMS Global Learning Tools Interoperability Tool Settings Service

Co-chairs:                                            Greg McFall (Pearson) and Lance Neumann (Blackboard)

Editors: Greg McFall (Pearson), Lance Neumann (Blackboard), Stephen Vickers (IMS Global)

Version: 1.0

Version Date:                                      6 January 2014

Status: Final Specification

Summary:                                            This document describes the Tool Settings Service that allows a Tool Provider to manage settings in the Tool Consumer.

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

Document Location:                          Join the discussion and post comments in the LTI Forum: http://www.imsglobal.org/community/forum/categories.cfm?catid=115

 

 

 

 

List of Contributors

The following individuals contributed to the development of this document:
 

Shawn Eastley

Cengage

Charles Severance

University of Michigan

Greg McFall

Pearson

Colin Smythe

IMS Global

Mark McKell

IMS Global

John Tibbetts

VitalSource

Lance Neumann

Blackboard

Stephen Vickers

IMS Global

 

 

 

Revision History

 

Version No.

Release Date

Comments

v1.0 Base Document

29 January 2009

The first formal release of the Base Document.  This document is released for review by the IMS LTI Project Group.

v1.0 Internal Draft

 June 2010

The first formal release of the Internal Draft. This document is released for interoperability implementation by IMS Contributing and Affiliate Members.

v1.0 Public Draft

15 July 2013

The first public release of this document.

v1.0 Final

6 January 2014

Final release of this document as part of the LTI v2 Final specification.

  14 December 2016 Corrected media type named to all lowercase.

 

 

 

IMS Global Learning Consortium, Inc. ("IMS Global") is publishing the information contained in this IMS Global LTI Tool Settings Service ("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 LTI Tool Settings Service v1.0 Final Revision: 6 January 2014