1EdTech Final Release

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.

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

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

Move to top

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

Move to top

[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

Move to top

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:

{
"@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: 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

Move to top

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