1EdTech 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.
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 © 2014 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/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 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.
Join the discussion and post comments on the LTI Public Forum: http://www.imsglobal.org/community/forum/categories.cfm?catid=44
© 2014 1EdTech Consortium, Inc.
All Rights Reserved.
The 1EdTech Logo and Learning Tools Interoperability (LTI) are trademarks of the 1EdTech
Learning Consortium, Inc. in the United States and/or other countries.
Document Name: 1EdTech 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, 1EdTech Learning Tools Interoperability Implementation Guide v2.0 Final, 1EdTech Consortium, January 2014. http://www.imsglobal.org/lti/index.html.
[LTI, 14 SEC] G.McFall, L.Neumann, S.Vickers, 1EdTech Learning Tools Interoperability Security v2.0 Final, 1EdTech 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:
- Tool Proxy – these settings are system-wide and apply to all launches using this Tool Proxy;
- 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;
- 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:
- ToolProxy.custom.url – the endpoint URI for accessing system-wide tool settings
- ToolProxyBinding.custom.url – the endpoint URI for accessing context-level tool settings
- 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:
{
|
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: 1EdTech Learning Tools Interoperability Tool Settings Service
Co-chairs: Greg McFall (Pearson) and Lance Neumann (Blackboard)
Editors: Greg McFall (Pearson), Lance Neumann (Blackboard), Stephen Vickers (1EdTech)
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 |
1EdTech |
Mark McKell |
1EdTech |
John Tibbetts |
VitalSource |
Lance Neumann |
Blackboard |
Stephen Vickers |
1EdTech |
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 1EdTech 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 1EdTech 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. |
1EdTech Consortium, Inc. ("1EdTech") is publishing the information contained in this 1EdTech LTI Tool Settings Service ("Specification") for purposes of scientific, experimental, and scholarly collaboration only.
1EdTech 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.
1EdTech would appreciate receiving your comments and suggestions.
Please contact 1EdTech through our website at http://www.imsglobal.org
Please refer to Document Name: 1EdTech LTI Tool Settings Service v1.0 Final Revision: 6 January 2014