IMS Learning Tools Interoperability™ (LTI) Implementation Guide
Version 2.0 Public Draft
Date
Issued: 1 November 2012
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 © 2012 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
Table of Contents
1.1 History of this Specification
1.2 Structure of this Document
2 Structure of this Specification
3.15 Learning Information Services
4.5 Tool Proxy Registration Request
4.6 Tool Proxy Reregistration Request
5.1 Common Elements in a Product Profile
5.4.1 Singleton message handlers
6.1 Establishing an Integration Contract
6.1.1 Request Access to a Tool
6.1.2 Fetch Tool Consumer Profile
6.1.4 Make the Tool Proxy Available
6.2 Enabling Tools within a Learning Context
6.3 Administrator / Instructor User Interfaces / Custom Parameters
6.3.1 Instructor Creates New Tools
6.3.2 Admin Creates New Tools, Instructor Only Places Tools
6.4 Other Tool Management Use Cases
7.1 Authoring Links with Link-Level Credentials
7.2 Authoring links associated with a Resource Type
8.2 OAuth Message Signing for x-www-form-encoded Messages
8.3 OAuth Message Body Signing for HTTP Requests
9 Representing Basic LTI Links in a Cartridge
10.2.1 The JSON-LD Representation of a Result object
Appendix A – LTI Standard Vocabularies
A.1.1 LIS vocabulary for ContextType
A.2.1 LIS vocabulary for System Role
A.2.2 LIS vocabulary for Institution Role
A.2.3 LIS vocabulary for Context Role
Appendix B – Implementation Practice
B.1 Security Policy / SandBoxing Launch Requests
Appendix C – Custom Parameter Subsitution
C.3 LIS Course Template Variables
C.4 LIS Course Offering Variables
C.5 LIS Course Section Variables
Appendix D – Deprecated Parameter Names
Appendix E – Developer Cookbooks
E.1 Outcomes Reporting Cookbook
E.1.1 Tool Consumer Requirements for Outcomes Reporting
E.1.2 Tool Provider Requirements for Outcomes Reporting
1 Introduction
IMS is developing the Learning Tools Interoperability™ (LTI) specification to allow remote tools and content to be integrated into a Learning Management System (LMS). This document brings a subset of those specifications together in an implementation guide that defines a profile of LTI.
1.1 History of this Specification
LTI has its origins in the IMS Tools Interoperability specifications released in 2006. This was then developed into what is now referred to as Learning Tools Interoperability, or LTI. In May 2010 a version named Basic LTI was released which provided a simple mechanism for launching tools and content from within an LMS. This provided a small but useful subset of the functionality which underlies LTI 2.0 and future releases. When a simple outcomes service was added in March 2011, Basic LTI was effectively renamed as LTI 1.0, with the new release being LTI 1.1. Whilst the goals of LTI 1 are the same as LTI 2, the technology used is quite different. LTI 2 provides a much stronger, more extensible platform on which to provide relevant functionality and services. Whilst LTI 1 demonstrated the demand for this specification by its rapid and widespread take-up, LTI 2 will deliver the flexible solution needed to deliver the more fully-featured integrations demanded by modern-day educational systems.
Whilst Version 2 introduces a new architecture for implementing LTI, it continues to support all of the functionality included in Version 1, i.e., it is fully backwards compatible and any Tool Consumer or Tool Provider which supports LTI 2 will be able to connect to an LTI v1 Tool Provider or Tool Consumer.
1.2 Structure of this Document
The structure of this document is:
|
2 Structure of the Specification |
A listing of the documents which form the specification |
|
3. Key Concepts and Elements |
Description of the key concepts and elements used by LTI |
|
4. LTI Messages |
Description of LTI message types |
|
5. Tool Proxy |
Structure of a tool proxy |
|
6. Tool Management |
Process of establishing an integration contract |
|
7. Link Authoring |
Types of links created to Tool Providers |
|
8. Security Model |
Methods used to secure LTI communications |
|
9. Representing Basic LTI Links in a Cartridge |
A description of the Basic LTI link for inclusion in an IMS Common Cartridge |
|
10. Using Services |
A description of how to use LTI with IMS Learning Information Services |
|
Appendix A LTI Standard Vocabularies |
A reference to the LTI specification’s
standard vocabularies |
|
Appendix B Implementation Practice |
A non-normative discussion and recommendations to help guide implementations |
|
Appendix C – Custom Parameter Substitution |
Optional functionality to perform substitutions of custom parameter values on launch |
|
Appendix D – Deprecated Parameter Names |
Launch parameters which are now deprecated |
|
Appendix E – Developer Cookbooks |
Additional guidance for developers |
|
Appendix F – JSON-LD |
Overview of JSON-LD used to represent LTI resources |
1.3 References
[CC, 08a] K. Riley, IMS Common Cartridge v1.0, IMS Global Learning Consortium, October 2008. http://www.imsglobal.org/cc/
[GWS, 06] C.Schroeder, J. Simon and C. Smythe, IMS General Web Services WSDL Binding Guidelines v1.0, IMS Global Learning Consortium, January 2006. http://www.imsglobal.org/gws/
[JSON, 12] JSON-LD Syntax 1.0 - A Context-based JSON Serialization for Linking Data, W3C, October 2012, http://json-ld.org/spec/latest/json-ld-syntax/
[LIS, 11] L. Feng, W. Lee and C. Smythe, IMS Global Learning Information Services v2.0, IMS Global Learning Consortium, June 2011. http://www.imsglobal.org/lis/
[LTI, 12 MSF] G.McFall, L.Neumann, S.Vickers, IMS Global Learning Tools Interoperability Messaging Framework v2.0 Public Draft, IMS Global Learning Consortium, November 2012. http://www.imsglobal.org/lti/
[LTI, 12 REST] G.McFall, L.Neumann, S.Vickers, IMS Global Learning Tools Interoperability Media Types REST APIs v2.0 Public Draft, IMS Global Learning Consortium, November 2012. http://www.imsglobal.org/lti/
[LTI, 12 SEC] G.McFall, L.Neumann, S.Vickers, IMS Global Learning Tools Interoperability Security v2.0 Public Draft, IMS Global Learning Consortium, 2012. http://www.imsglobal.org/lti/
[LTI, 12 TMT] G.McFall, L.Neumann, S.Vickers, IMS Global Learning Tools Interoperability Tool Management v2.0 Public Draft, IMS Global Learning Consortium, November 2012. http://www.imsglobal.org/lti/
[OAuth, 10] E. Hammer-Lahav. The OAuth 1.0 Protocol, Retrieved 22 November 2011 from http://tools.ietf.org/html/rfc5849
[OBH, 11] B. Eaton, E. Hammer-Lahav. OAuth Request Body Hash, Retrieved 22 November 2011 from http://oauth.googlecode.com/svn/spec/ext/body_hash/1.0/oauth-bodyhash.html
2 Structure of this Specification
The specification is fully described by the following documents:
- Implementation Guide (this document) – a description of how the main elements of LTI 2 operate.
- REST services [LTI, 12 REST] – REST APIs for services supporting resources for results, Tool Consumer profiles, and Tool Proxy.
- Media Types [LTI, 12 REST] – Resource definitions for LTI media types.
- Tool Management [LTI, 12 TMT] – describes the main use cases applicable to tools.
- Messaging Framework [LTI, 12 MSF] – explains how messages are sent from the Tool Consumer to resource handlers within the Tool.
- Security [LTI, 12 SEC] – describes the security model applied to each type of interaction between users, Tool Consumers and Tools.
3 Key Concepts and Elements
LTI is essentially provided a means of connecting two systems together: a “Tool Consumer” which “consumes” the tool, and a “Tool Provider” which “provides” the Tool to be used in the Tool Consumer. A Tool Consumer would typically be an LMS. Examples of Tool Providers include an externally hosted testing system and servers containing externally hosted premium content.[1]
Figure 3.1 Overview of Learning Tools Interoperability.
The nature of the relationship established between a Tool Consumer and a Tool Provider via LTI is that the Tool Provider delegates responsibility for the authentication and authorization of users to the Tool Consumer. The Tool Consumer will provide the Tool Provider with data about the user, the user’s current context and the user’s role within that context. This data is provided in a secure manner so that the Tool Consumer may trust its authenticity.
There are two types of connection defined between the Tool Consumer and the Tool Provider:
- message-based
- service-based
A message-based connection involves the user with data being transferred as a signed HTTP POST request via their browser. For example, this is used when the Tool Consumer wishes to launch the external tool for a user.
A service-based connection involves direct connections between the Tool Consumer and Tool Provider servers using an HTTP request and response web service pattern to a service URL. For example, a Tool Consumer may provide an Outcomes service which allows a Tool to update the values of grades in the Tool Consumer. Data being exchanged between the servers is formatted using JSON-LD.
A common framework for describing messages and services is defined for the LTI specifications to enable new types to be added in a consistent manner with each new release.
The following subsections provide a more detailed definition of the key concepts used by LTI.
3.1 Tool Consumer
The learning application into which links to external tools are to be embedded. The Tool Consumer is the primary focus for a user’s learning activity and is the system which they would log into in the first instance. Typically a Tool Consumer would be an LMS. The functionality provided by a Tool Consumer may be extended by connecting to external tools using LTI. A user may not realize that these additional tools are not part of the Tool Consumer; the implementation of LTI is designed to be as transparent as possible for users.
3.2 Tool Provider
The system providing access to one or more Tools. The Tool Provider may be hosted by a third party or by the same organization as the Tool Consumer; the LTI specification is agnostic as to the relative location of the Tool Consumer and Tool Provider. A distinction between the Tool Provider and the Tool has been introduced in LTI 2 to recognize that whilst a Tool Consumer might connect directly with a Tool, it is also possible to add LTI support to Tools by adding an interface between them to handle the LTI connection. This interface is what is referred to as the Tool Provider. It means, for example, that a pre-existing Tool could be made LTI-compliant simply by developing a Tool Provider wrapper without the need to make significant changes to the Tool itself.
3.3 Tool Proxy Runtime
The Tool Proxy Runtime is an aggregation of all the Tool Consumer capabilities. This may include:
- Administrative presentation logic supporting:
-
- Installation via Tool profiles (URL resolved or ‘pasted’), configuration and un-installation.
- Security configuration.
- Business and Persistence logic supporting tool proxy creation and management, e.g., tool launch.
- Rendering links associated with Tool Proxies.
- Generating HTML POST page in response to links associated with Tool Proxies.
- Optionally generating event notifications as registered by Tool Proxies (specific events generated are defined by the capabilities that are declared in the Tool Consumer Profile).
3.4 Tool
The learning application which provides users with access to new functionality or content or other protected resources. The Tool uses a trust relationship to accept data about the user, their context and their role within that context from the Tool Consumer. A Tool defines resource handlers for processing messages received from the Tool Consumer. Technically these messages are handled by the Tool Provider, though the Tool Provider and Tool may be implemented as a single entity.
3.5 Tool Proxy
The Tool Proxy represents a specific interface contract between a Tool and Tool Consumer. A Tool Consumer may contain multiple connections to the same Tool but each connection will be represented by a separate Tool Proxy. The Tool Proxy contains details of the agreement negotiated between the Tool Consumer and Tool when the deployment process occurs. This agreement contains:
- details of the Tool (Tool profile); and
- the capabilities to be made available through this connection.
3.6 User
An object representing a person logged into a Tool Consumer. The Tool Consumer may delegate the authentication process to another system (e.g. an LDAP server). A user will have a unique ID and typically have properties such as first name, last name and email address.
3.7 Context
The context is one of the three main data items which is passed from the Tool Consumer when a user launches a Tool (the other two items are user and role). The context represents the place within the Tool Consumer from which the user launched the Tool. Typically this would be a course in an LMS. Other kinds of contexts might be ‘group’ or ‘project’.
3.8 Role
The role is one of the three main data items which is passed from the Tool Consumer when a user launches a Tool (the other two items are context and user). The role represents the level of privilege a user has been given within a context in a Tool Consumer. Typical roles are learner, instructor and administrator. A Tool may use the role to determine the level of access to give a user.
3.9 Authentication
Authentication is the process of confirming the identity of a user. LTI itself plays no role in the authentication process other than reliably carrying the user’s identity along to the Tool Provider. The learning system will use standard authentication mechanisms to verify identity, such as requesting a username and password; alternatively it may further delegate authentication to some identity provider service such as CAS or Shibboleth.. A tool relies on the Tool Consumer to authenticate a user and trusts the user credentials which are passed to it on launch.
3.10 Authorization
Authorization is the process of identifying a user’s access rights. LTI serves the overall authorization requirements between Tool Consumer and Tool Provider at two different levels. Firstly, within the LTI layers themselves LTI authorizes the behavior (services or methods) a tool is allowed to use. Secondly, LTI supports the authorization work of the tool itself by reliably conveying contextually rich data to the tool. For example, for some tool to authorize a particular user to read an eBook might require the user’s identity and a role within the particular course.
3.11 Capability
A capability is a formal definition for some pattern of behavior. LTI 1.2 defines three broad kinds of capabilities:
- variable expansion;
- messaging;
- outcomes.
The Tool Consumer advertises the capabilities that it supports, and the Tool specifies the capabilities it wishes to use. As part of the Tool deployment process the Tool Proxy records the capabilities that are to be enabled.
3.12 Resource Handler
A Tool may expose many different kinds of resources that can be launched from the Tool Consumer. For example, a given Tool might expose tutorials, homework assignments, quizzes, simulators, etc. Each type of resource may potentially have a different endpoint in the Tool Provider. Furthermore, each type of resource may require a different set of parameters when it is launched. The Tool Profile introduces the concept of a resource handler to capture these variations. Note that a single resource handler may provide support for more than one resource.
3.13 Profile
Profiles are used to describe the nature of a Tool Consumer or a Tool.
3.13.1 Tool Consumer Profile
A Tool Consumer exposes its functionality via the Tool Consumer profile, including:
- supported LTI version;
- supported capabilities;
- web services provided.
3.13.2 Tool Profile
A Tool Provider exposes the functionality of one or more tools via individual Tool Profiles which include the following information:
- supported LTI version;
- supported capabilities i.e., which LTI functionality is supported by the Tool Provider;
3.14 LTI Message
LTI uses two kinds of message flows. When the Tool Consumer is communicating with the Tool Provider, the messages are signed POST messages transmitted through the user's browser. This "message through the browser" pattern is common, for example, when an application is using Twitter or Google for its sign on.
The second kind of message is where the Tool provider is calling a service within the Tool Consumer using an HTTP request and response web service pattern to a service URL.
The OAuth 1.0a protocol [OAuth, 10] is used to secure message interactions between the Tool Consumer and Tool Provider. OAuth requires a key and shared secret to sign messages. The key is transmitted with each message, as well as an OAuth-generated signature based on the key. The Tool Provider looks up the secret based on the provided key, recomputes the signature, and compares the recomputed signature with the transmitted signature to verify the sender's credentials.
As a best practice, the Tool Provider should isolate data based on the key. The Tool Provider must decide exactly how the key is used to isolate data. For example, the Tool Provider might maintain a table that maps multiple keys into a single data silo. Or, the Tool Provider might arrange to use the same key repeatedly in all cases where data are to belong to the same data silo.
3.15 Learning Information Services
LTI has support for the Tool Provider to call IMS Learning Information Services (LIS) when those services can be made available to the Tool Provider. LTI does not require LIS services, but the Tool Consumer can send LIS key information to the Tool Provider using values in the Basic LTI Launch Request.
4 LTI Messages
A Message is an HTTP request that passes from a Tool Consumer to a handler within the Tool Provider system. LTI 2.0 defines three different types of messages:
· Basic LTI Launch Request
· Tool Proxy Registration Request
· Tool Proxy Reregistration Request
Each message type specifies a set of required and optional parameters.
Section 4.1 describes the parameters that are common to all of the message types. Section 2.2 explains how custom parameters can be included in a message
Sections 4.3, 4.5 and 4.6 discuss parameters that are specific to the individual message types, and Section 4.7 discusses the mechanics of sending a message.
4.1 Common Parameters
lti_message_type=basic-lti-launch-request
| ToolProxyRegistrationRequest |
ToolProxyReregistrationRequest
(Required)
This indicates the type of the
message. This allows a Tool Provider to accept a number of
different LTI message types at the same endpoint.
lti_version=LTI-1p0 |
LTI-2p0
(Required)
This indicates which version
of the specification is being used for this particular message.
This parameter is required in all messages.
user_id=0ae836b9-7fc9-4060-006f-27b2066ac545
(Optional)
Uniquely identifies the user.
This should not contain any identifying information for the
user. Best practice is that this field should be a Tool
Consumer-generated long-term “primary key” to the
user record – not the “logical key".
roles=Instructor
(Optional)
A comma-separated list of URN
values for roles. If this list is non-empty, it should contain
at least one role from the LIS System Role, LIS Institution Role,
or LIS Context Role vocabularies (See Appendix A). The assumed
namespace of these URNs is the LIS vocabulary of LIS Context
Roles so Tool Consumers can use the handles when the intent is to
refer to an LIS context role. If the Tool Consumer wants to
include a role from another namespace, a fully-qualified URN
should be used. Usage of roles from non-LIS vocabularies is
discouraged as it may limit interoperability.
launch_presentation_locale=en-US
(Optional)
Language, country and variant
as represented using the IETF Best Practices for Tags for
Identifying Languages (BCP-47) available at
http://www.rfc-editor.org/rfc/bcp/bcp47.txt
launch_presentation_document_target=iframe
(Recommended)
The value should be either
‘frame’, ‘iframe’ or
‘window’. This field communicates the kind of
browser window/frame where the Tool Consumer has launched the
tool.
launch_presentation_css_url=
(Optional)
This is a URL to an LMS-specific CSS URL. There are no standards
that describe exactly what CSS classes, etc. should be in this
CSS. The Tool Provider should send its standard CSS URL that it
would apply to its local tools. The Tool Consumer should include
styling for HTML tags to set font, color, etc and also include
its proprietary tags used to style its internal tools.
In the absence of a cross-LMS standard for CSS classes to allow a tool to look "built-in" with only one set of markup, the launch_presentation_css_url gives Tool Providers a chance to adapt their look and feel across LMS systems to some degree.
launch_presentation_width=320
(Recommended)
The width of the window or
frame where the content from the tool will be displayed.
launch_presentation_height=240
(Recommended)
The height of the window or
frame where the content from the tool will be displayed.
4.2 Custom Parameters
In addition to standard parameters, like the ones described in the previous section, a Message may contain custom parameters that come from two possible sources:
- The Tool Profile (see Section 5.4).
- The creator of a link (see Section 6.3)
Section 9 explains how custom parameters are represented when a link is stored in a Common Cartridge.
When a message is rendered as an HTTP POST request, each custom parameter is mapped to a POST parameter where the name of the POST parameter is formed by prepending the string “custom_” as a prefix to the original name of the parameter. Suppose, for example, that the creator of a link added a custom parameter named “Chapter”. This parameter would be rendered as a POST parameter named “custom_Chapter”.
As a best practice, custom parameter names should consist of nothing but underscores and alphanumeric characters. LTI specifies that POST requests must be submitted using a content-type of application/x-www-form-urlencoded.
|
|
Note: In earlier versions of LTI, custom parameter names had to be converted to lower case, and all punctuation or special characters in the name had to be replaced with underscores (before adding the “custom_” prefix). This naming rule has been removed in LTI 2.0. To preserve backward compatibility with launches from LTI 1 Tool Providers, it is recommended that when Tool Consumers are sending a basic-lti-launch-request message, they check to see if the LTI 1.x rule would result in a different POST parameter name. In this case, the Tool Consumer should, as a best practice, render the parameter twice – once using the LTI 1 convention and a second time using the LTI 2.0 convention.; for example, both as “custom_chapter ” and as “custom_Chapter ”. |
Tool Consumer implementations may have the ability to make value substitutions for custom parameters as described in Appendix C. For example, if a custom parameter was:
xstart=$CourseSection.timeFrame.begin
the parameter would be
custom_xstart=2012-04-21T01:00:00Z
Note that a DateTime data type in IMS LIS represents a combined date and time in the format of ISO 8601 i.e. ‘YYYY-MM-DDThh:mm:ssTZD’. The time is denoted in Coordinated Universal Time (UTC) with TZD denoting the time zone offset in hours and minutes with respect to UTC.
It is important for a Tool Provider not to depend on the Tool Consumer supporting any particular parameter substitution. If a Tool Consumer that did not support parameter substitution were to see the above custom parameter, it would simply send
custom_xstart=$CourseSection.timeFrame.begin
as the parameter (i.e. send the parameter unsubstituted). It the responsibility of the Tool Provider to deal with both kinds of launches from Tool Consumers (i.e. with and without substitution available). The Tool Consumer Profile contains a list of all variables that the Tool Consumer understands. If the Tool Provider registers a Tool Proxy with the Tool Consumer, there will be no ambiguity about which variables are supported and which are not. See Section 5 for more details.
4.3 Extension Parameters
A Tool Consumer may extend the information model for any message type and inject additional parameters into an HTTP POST request. In this case, the POST parameter name must begin with the string “ext_” as a prefix. At its own discretion, a conforming Tool Provider may ignore any parameter that begins with the “ext_” prefix.
Tool Consumers should avoid injecting too many extension parameters into LTI messages. As an alternative, the Tool Consumer may define custom variables as described in Appendix C.10. In this case, the Tool Provider or link creator must explicitly request the value by including a custom parameter that references the variable.
4.4 Basic LTI Launch Request
The Basic LTI Launch Request is used to launch a Tool from the Tool Consumer. In addition to the common parameters described in Section 4.1, the Basic LTI Launch Request information model includes the following additional parameters.
context_id=8213060-006f-27b2066ac545
(Recommended)
This is an
opaque identifier that uniquely identifies the context that
contains the link being launched.
context_type=CourseSection
(Optional)
This
string is a comma-separated list of URN values that identify the
type of context. At a minimum, the list MUST include a URN value
drawn from the LIS vocabulary (see Appendix A). The assumed
namespace of these URNs is the LIS vocabulary so TCs can use the
handles when the intent is to refer to an LIS context type. If
the Tool Consumer wants to include a context type from another
namespace, a fully qualified URN should be used.
launch_presentation_return_url=http://lmsng.school.edu/portal/123/page/988/
(Recommended)
Fully qualified URL where
the Tool Provider can redirect the user back to the Tool Consumer
interface. This URL can be used once the Tool Provider is
finished, or if the Tool Provider cannot start, or has some
technical difficulty. In the case of an error, the Tool Provider
may add a parameter called lti_errormsg that includes some
detail as to the nature of the error. The lti_errormsg
value should make sense if displayed to the user. If the tool
has displayed a message to the end user and only wants to give
the Tool Consumer a message to log, use the parameter
lti_errorlog instead of lti_errormsg. If the tool
is terminating normally, and wants a message displayed to the
user it can include a text message as the lti_msg
parameter to the return URL. If the tool is terminating normally
and wants to give the Tool Consumer a message to log, use the
parameter lti_log. This data should be sent on the URL as
an HTTP GET request – so the Tool Provider should take care
to keep the overall length of the parameters small enough to fit
within the limitations of a GET request.
resource_link_id=88391-e1919-bb3456
(Required)
This
is an opaque unique identifier that the Tool Consumer guarantees
will be unique within the Tool Consumer for every placement of
the link. If the tool / activity is placed multiple times in
the same context, each of those placements will be distinct. This
value will also change if the item is exported from one system or
context and imported into another system or context.
role_scope_mentor=
f5b2cc6c-8c5c-24e8-75cc-fac5,dc19e42c-b0fe-68b8-167e-4b1a
(Optional)
A
comma separated list of the user_id values which the current user
can access as a mentor. The typical use case for this parameter
is where the Mentor role represents a parent, guardian or
auditor. It may be used in different ways by each Tool, but the
general expectation is that the mentor will be provided with
access to tracking and summary information, but not necessarily
the user’s personal content or assignment submissions. In
order to accommodate user_id values which contain a comma, each
user_id should be url-encoded. This also means that each user_id
from the comma separated list should url-decoded before a Tool
uses it. This parameter is optional and should only be used when
one of the roles passed for the current user is for http://www.imsglobal.org/imspurl/lis/v1/vocab/membership#Mentor
(urn:lti:role:ims/lis/Mentor).
tool_consumer_instance_guid=lmsng.school.edu
(Recommended)
This is a
unique identifier for the Tool Consumer. A common practice is to
use the DNS of the organization or the DNS of the Tool Consumer
instance. If the organization has multiple Tool Consumer
instances, then the best practice is to prefix the domain name
with a locally unique identifier for the Tool Consumer
instance.
user_image=http://....
(Optional)
This
attribute specifies the URI for an image of the user who launches
this request. This image is suitable for use as a "profile
picture" or an avatar representing the user. It is expected to
be a relatively small graphic image file using a widely supported
image format (i.e., PNG, JPG, or GIF) with a square aspect
ratio.
|
Message Type |
basic-lti-launch-request |
|
Required Parameters |
lti_message_type, lti_version, resource_link_id |
|
Recommended Parameters |
context_id, launch_presentation_document_target, launch_presentation_height, launch_presentation_return_url, launch_presentation_width, roles, tool_consumer_instance_guid, user_id |
|
Optional Parameters |
context_type, launch_presentation_locale, launch_presentation_css_url, role_scope_mentor, user_image |
|
Deprecated Parameters |
context_title, context_label, resource_link_title, resource_link_description, lis_person_name_given, lis_person_name_family, lis_person_name_full, lis_person_contact_email_primary, user_image, lis_person_sourcedid, lis_course_offering_sourcedid, lis_course_section_sourcedid, tool_consumer_info_product_family_code, tool_consumer_info_product_family_version, tool_consumer_instance_name, tool_consumer_instance_description, tool_consumer_instance_url, tool_consumer_instance_contact_email, |
See Appendix D for a discussion about the deprecated parameters.
4.5 Tool Proxy Registration Request
This message initiates the Tool Proxy Deployment workflow within the Tool Provider as described in Section 6.1. In addition to the common parameters described in Section 4.1, the Tool Proxy Registration Request includes the following additional parameters.
reg_key=869e5ce5-214c-4e85-86c6-b99e8458a592 (Required)
reg_password=918283799228bbejsdh999288 (Required)
The Tool Consumer generates a set of credentials (key and password) that the Tool Provider uses to register a new Tool Proxy within the Tool Consumer. These credentials are valid for one use only, and they expire after a short time, typically about one hour. When the Tool Provider posts a new Tool Proxy to the Tool Consumer, these parameters are used as the oauth_consumer_key and oauth_consumer_secret respectively to digitally sign the HTTP request in accordance with the OAuth protocol. The Tool Consumer may use the reg_key as the GUID for the new Tool Proxy, but there is no requirement to do so. The reg_password is valid for one use only. Any attempt to use the key and password again after a successful submission should result in a failure with a 401 (Unauthorized) status code.
tc_profile_url= https:// lmsng.school.edu /ToolProxy/869e5ce5-214c-4e85-86c6-b99e8458a592 (Required)
This URL specifies the address where the Tool Provider can retrieve the Tool Consumer Profile. This URL must be retrievable by a GET request by the Tool Provider. If the URL is protected from retrieval in general, the Tool Consumer must append the necessary parameters to allow the Tool Provider to retrieve the URL with nothing more than a GET request. It is legal for this URL to contain a security token that is changed for each ToolProxyRegistrationRequest so the Tool Provider must retrieve the tc_profile_url on each request.
launch_presentation_return_url=http://lmsng.school.edu/admin/continue_proxy.php (Required)
The Tool Provider redirects the user's browser back to this URL when it has completed its part of the tool deployment process. The Tool Provider should redirect to this URL regardless of whether the deployment process succeeds or fails. In addition to the log and message parameters (described above for the Basic LTI Launch Request message type) the Tool Provider appends the following HTTP query parameters
status=success | failure
tool_guid=<globally unique identifier for the Tool Proxy>
where the value for the tool_guid parameter is given by the return value from the Tool Proxy creation request if the operation was successful. Typically, this action redirects the administrator’s browser to the Tool Console within the Tool Consumer system where the Tool Proxy can be made available.
|
Message Type |
ToolProxyRegistrationRequest |
|
Required Parameters |
lti_message_type, reg_key, reg_password, tc_profile_url, launch_presentation_return_url |
|
Recommended Parameters |
launch_presentation_document_target, launch_presentation_height, launch_presentation_width, user_id, roles |
|
Optional Parameters |
launch_presentation_css_url, launch_presentation_locale |
4.6 Tool Proxy Reregistration Request
The Tool Proxy Reregistration Request triggers the process to update a Tool Proxy that was previously deployed. This workflow is described in Section 3.
4.7 Sending Messages
The Tool Consumer must implement a Tool Launch Service. This service takes an LTI Link as input and produces an LTI Message encoded as an HTML Form. The typical workflow for launching a Tool can be summarized by the following sequence of events:
- An end user (typically an Instructor or Learner) clicks on an LTI Link within the Tool Consumer web site.
- The browser sends an HTTP request to the Tool Launch Service within the Tool Consumer. This request identifies the LTI Link that was clicked.
- The Tool Launch Service constructs an HTML Form that represents the message that should be sent to the Tool Provider.
- The HTML Form is loaded into the browser and auto-submitted to the appropriate Message Handler within the Tool Provider system.
For a more complete discussion of this use case, see [LTI, 12 MSF].
Figure 4.1 Sample Launch Request
When creating the HTML Form at Step 3 in the workflow, custom parameters must be rendered in accordance with the rules discussed in Section 4.2.
If the LTI Link is associated with a Resource Type, the Tool Launch Service must implement the following business rules:
- Discover Message Handler endpoint. The Tool Launch Service discovers the endpoint URL for the Message Handler by inspecting the relevant Tool Profile. See Sections 5.1 and 3.4.5 for more details.
- Apply Capabilities. If the Message Handler has enabled any capabilities, the business rules for those capabilities must be applied. For example, if the Result.autocreate capability is enabled, the Tool Consumer must create an LIS Result (and possibly a LineItem) prior to launching the Tool. (See Section 5.3.3 for a discussion of this particular capability.)
If the LTI Link is not associated with a Resource Type, then the link must define the Message Handler URL explicitly.
In all cases, the Message Handler URL is set as the action attribute of the HTML form.
Note that the launch request is digitally signed in accordance with the OAuth 1.0a protocol. Section 8.2 contains more information about this security protocol. The Tool Consumer receives the oauth_consumer_secret which is used to sign the launch request in the Tool Proxy, which is discussed in the next section.
5 Tool Proxy
The two parties in an LTI integration (Tool and Tool Consumer) may exchange information about themselves in the form of Product Profiles. These profiles, together with security details, are aggregated to create an integration contract known as a Tool Proxy. Figure 5.1 illustrates the top-level structure of a Tool Proxy.
|
{ "@context" : "http://www.imsglobal.org/imspurl/lti/v1/ctx/Profile" ,
"@type" : "ToolProxy", "lti_version" : "LTI-2p0", "tool_proxy_guid" : "e8359010-009f-11e1-be50-0800200c9a66" , "tool_consumer_profile" : { }, "tool_profile" : { }, "security_contract" : { } }
|
Figure 5.1 Tool Proxy synopsis
We’ll have more to say about the security contract later, but for now we focus on the Tool Profile and the Tool Consumer Profile.
5.1 Common Elements in a Product Profile
The Tool Profile and Tool Consumer Profile have several elements in common including:
- product_instance
-
- product_info
- support
- service_provider
- service_offered
Much of this information is optional. The contents of these common elements are described below.
5.1.1 product_instance
|
{ "guid" : "f188d950-dd73-11e0-9572-0800200c9a66" , "product_info" : { }, "support" : { }, "service_provider" : { } }
|
Figure 5.2 Synopsis of product_instance
The product_instance element represents a deployed instance of a given product (Tool or Tool Consumer). This element contains general information about the product (see product_info), plus optional contact information for support and optional details about the service provider that hosts the deployed application.
The deployed instance is identified by a guid. Typically, this will be a UUID, but it can be any globally unique string.
5.1.2 product_info
The product_info element contains generic information about a given product (Tool or Tool Consumer) such as the product name and description. Two products that belong to the same product family are regarded as different versions of the same product, and the version field within the product_info specifies exactly which version is being used for the current integration. The product family is identified by a code that is unique within the namespace of some vendor. In Figure 5.3, the product family is identified by the code “omega”, and the vendor is identified by the code “lms.example.com”. The vendor code must be globally unique. As a best practice, this value should match an Internet domain name registered to the vendor.
Notice that the JSON snippet contains additional information about the vendor including the vendor’s name, description, website, and contact information. It also contains a timestamp. It is possible for multiple product profiles to encapsulate information about the same vendor. The timestamp allows you to determine which vendor record is most current.
|
{ "product_name" : { "default_value" : "Omega LMS" }, "product_version" : "2.3" , "description" : { "default_value" : "Omega LMS is a fictitious Learning Management System" }, "product_family" : { "@id" : "http://toolprovider.example.com/vendor/lms.example.com/product/omega", "code" : "omega" , "vendor" : { "code" : "lms.example.com" , "timestamp" : "2011-12-31T12:00:00" , "name" : { "default_value" : "LMS Corporation" }, "description" : { "default_value" : "LMS Corporation is a fictitious vendor of a Learning Management System" }, "website" : "http://lms.example.com/sales" , "contact" : { "email" : "support@lms.example.com" } } } }
|
Figure 5.3 Example of product_info
5.1.3 support
|
{ "email" : "techsupport@university.edu" }
|
Figure 5.4 Example of support
The product_instance element may contain contact information for support, as shown in Figure 5.4. In LTI 2.0, email is the only means of contact.
5.1.4 service_provider
|
{ "guid" : "yasp.example.com" , "timestamp" : "2001-12-31T12:00:00-05:00" , "provider_name" : { "default_value" : "Your Application Service Provider" }, "description" : { "default_value" : "YASP is a fictitious application service provider" }, "support" { "email" : "support@yasp.example.com" } } |
Figure 5.5 Example of service_provider
A service provider is responsible for hosting one or more product instances. The service provider is not necessarily a commercial entity. For example, if a Tool or Tool Consumer is locally hosted at a university, the service provider may be identified with the given university, a department within the university, etc. Notice that the service provider also contains an optional email address for support. Since the service provider may host multiple product instances, customers should use the more specific support email address (see Section 5.1.3) if one is defined.
Information about the service provider is entirely optional.
5.1.5 service_offered
|
{ "@type" : "RestService", "@id" : "http://alpha.university.edu/resource/ToolConsumerProfile/12434 #Result.item", "endpoint" : "http://lms.example.com/resources/Result/{sourcedId}", "format" : ["application/vnd.ims.lis.v2.Result+json"], "action" : ["GET", "PUT"] }
|
Figure 5.6 Example of service_offered
A given product (Tool or Tool Consumer) may offer a set of services to its integration partner. In this case, the product profile contains one or more service_offered elements like the one shown in Figure 5.6.
Every type of service has a URI which identifies the contract for that service. In the example above, the contract URI is http://www.imsglobal.org/imspurl/lti/v1/service/ResultService. This example corresponds to the service that is described in Section 10.2.
A service contract specifies a number of methods on the service interface. A given party may wish to offer only a subset of those methods to its integration partner. For example, a Tool Consumer might expose read methods for user data, but it might not allow the Tool Provider to create or update user records within the Tool Consumer system. The service methods that are available to the integration partner are listed explicitly within the service_offered element.
Notice that the service_offered element also defines the URL for the service endpoint.
5.2 Tool Consumer Profile
|
{ "@context" : "http://www.imsglobal.org/imspurl/lti/v1/ctx/Profile" ,\ "@type" : "ToolConsumerProfile", "lti_version" : "LTI-2p0", " @id" : " http://alpha.university.edu/resource/ToolConsumerProfile/12434 " "guid" : "b6ffa601-ce1d-4549-9ccf-145670a964d4", "product_instance" : { }, "service_offered" : [ ], "capability_offered" : [ ] }
|
Figure 5.7 Tool Consumer Profile synopsis
A Tool Consumer Profile contains information about one particular instance of a Tool Consumer product. In addition to the common elements discussed in Section 5.1, the Tool Consumer Profile announces the set of capabilities offered to the Tool Provider.
Each Tool Consumer Profile is identified by the REST endpoint URI for the object.
The @context parameter is required only if the Tool Consumer Profile is the first object in the serialized data. If the Tool Consumer Profile appears as a property of some other object, then the @context may be omitted because it will be defined by the parent entity. For example, a serialized Tool Proxy may reference a Tool Consumer Profile as shown in Figure 5.8. In this case, the details of the Tool Consumer Profile are omitted. Only its URN is provided.
|
{ "@context" : "http://www.imsglobal.org/imspurl/lti/v1/ctx/Profile" , "tool_consumer_profile" : "http://tc.example.com/resources/ToolConsumerProfile/alpha.university.edu", "tool_profile" : { }, "security_contract" : { } }
|
Figure 5.8 Reference to Tool Consumer Profile by a Tool Proxy
5.3 Capabilities
A “capability” is a formal definition for some pattern of behavior. Each capability is identified by a URI. Ideally, the URI should point to a resource that provides a description of the capability. Those descriptive resources are not published yet. Consequently, the URI for a capability should be regarded as an opaque identifier. LTI 2.0 defines three broad kinds of capabilities:
- Variable Expansion Capabilities
- Messaging Capabilities
- Outcomes Capabilities
The Tool Consumer advertises the capabilities that it supports, and the Tool Provider chooses the capabilities that it wishes to enable. These decisions are recorded in the Tool Proxy.
|
{ . . .. "capability_offered" : [ "Person.name.given" , "Person.name.family" , "Person.email.primary" , "User.image" , "Result.sourcedId" , "basic-lti-launch-request" , "ToolProxyReregistrationRequest" , "Result.autocreate" ] }
|
Figure 5.9 Capabilities declared in a Tool Consumer Profile
Figure 5.9 shows how the Tool Consumer declares the capabilities that it supports by listing them within the Tool Consumer Profile. Technically, each capability is identified by a fully-qualified URI, but in the JSON-LD binding they are identified by simple names (without a namespace prefix). The JSON-LD context (specified by the @context property) defines a mapping from the simple names to the fully qualified URI.
5.3.1 Variable Expansion
For each variable named in Appendix C, there is a corresponding formal capability which signifies that the Tool Consumer has the ability to expand the specified variable. For example, the variable $Person.name.given has a corresponding capability identified by the URI http://www.imsglobal.org/imspurl/lti/v1/variable#Person.name.given .
The URI for all the other variables follows a similar pattern. To form the capability URI, simply append the name of the variable minus the dollar sign to the namespace http://www.imsglobal.org/imspurl/lti/v1/variable#.
Capabilities for variable expansion do not need to be enabled explicitly within the Tool Proxy. The mere use of a variable implies that the Tool Provider wishes to enable the capability.
5.3.2 Messaging Capabilities
Each message type in the LTI specification has a simple name and a fully qualified URI. To construct the full URI, simply append the simple name to the namespace http://www.imsglobal.org/imspurl/lti/v1/message# . For example, the fully qualified URI for the basic-lti-launch-request is http://www.imsglobal.org/imspurl/lti/v1/message#basic-lti-launch-request.
Formally, each message type is also a capability. The Tool Consumer announces that it has the ability to send messages of a given type by listing the simple name of the message type within the capability set. Figure 5.9 illustrates an example of one such capability. Messaging capabilities do not need to be enabled explicitly within the Tool Proxy. The existence of a handler in the Tool Profile for a given message type implies that the Tool Provider wishes to enable the capability.
5.3.3 Outcomes Capabilities
Suppose that a Tool implements an assessment instrument such as a test, quiz, or homework assignment. The Tool may want to send results from the assessment activity back to the Tool Consumer. This exchange can be accomplished through the use of the Result Service described in Section 10.2. However, to use the Result Service the Tool needs an identifier for a Result object.
A Tool Consumer may have the ability to auto-create a Result object and pass its identifier in a message that launches the Tool. The Tool Consumer announces this capability in the Tool Consumer Profile as shown in Figure 5.10.
The Tool Provider enables this capability within the scope of one or more specific Message Handlers that appear in the Tool Profile. See Section 5.4.4 for more information about enabling capabilities.
|
{ . . . "resource_handler" : [ { "name" : { "default_value" : "Acme Assessment", "key" : "assessment.resource.name" }, "description" : { "default_value" : "An interactive assessment using the Acme scale.", "key" : "assessment.resource.description" }, "message" : { "message_type" : "basic-lti-launch-request", "path" : "/handler/launchRequest", "enabled_capability" : [ "Result.autocreate", "Result.sourcedId" ] } . . . } ] }
|
Figure 5.10 The Result.autocreate Capability
When the Result.autocreate capability is enabled by a given Message Handler, the following rules apply:
1. The Tool Consumer agrees to associate the LTI Link with a LineItem, where
a. By default, the title of the new LineItem shall match the title of the LTI Link.
b. The dataSource GUID of the LineItem shall be set equal to the product_family URI declared in the Tool Profile.
c. The LineItem shall have a ResultValue whose ValueRange constrains scores to decimal values between 0 and 1.
2. Suppose the link is activated by a Learner.
a. Prior to launching the Tool, the Tool Consumer agrees to create a new Result object associated with both the LineItem and the Learner (provided that the Learner does not already have a Result defined for the LineItem). The new Result object shall be initialized with an unset resultScore, and the dataSource GUID shall match the product_family URI declared in the Tool Profile.
b. If the Learner already has a Result and the resultScore is set, the Tool Consumer will not allow the Learner to navigate into the Tool via the LTI Link. Thus, in LTI 2.0, each Learner is permitted at most one attempt for each link. However, as a best practice, the Tool Consumer should allow the Instructor to override this constraint, perhaps by unsetting the previous score.
c. The Tool Consumer will include the Result URI as a custom parameter in the launch request in accordance with the parameter template defined by the Resource Handler.
5.4 Tool Profile
|
{ "lti_version" : "LTI-2p0", "product_instance" : { }, "service_offered" : [ ], "base_url_choice" : [ ], "message" : [ ], "resource_handler" : [ ] }
|
Figure 5.11 Tool Profile synopsis
A Tool Profile contains information about one particular instance of a Tool product. In addition to the common elements discussed in Section 5.1, the Tool Profile defines handlers for receiving messages from the Tool Consumer.
Certain message types can have at most one handler. The handlers for such messages are called singletons. Other message types can have multiple handlers which are nested within a so-called Resource Handler.
5.4.1 Singleton message handlers
The example in Figure 5.12 shows a singleton handler for two different types of messages:
- ToolProxyRegistrationRequest
- ToolProxyReregistrationRequest
As this example illustrates, a Tool Provider may choose to expose a single endpoint to handle multiple message types. In the example, the Tool Profile declares a single handler for two message types at the same endpoint – https://acme.example.com/lti/registration. This handler can receive either a ToolProxyRegistatrationRequest or a ToolProxyReregistrationRequest.
|
{ "product_instance" : { }, "service_offered" : [ ], "base_url_choice" : [ ], "message" : [ { "message_type" : "ToolProxyReregistrationRequest" , "path" : "https://acme.example.com/lti/registration" "parameter" : [ { "name" : "lis_person_name_given" , "variable" : "$Person.name.given" } ] } ], "resource_handler" : [ ] } |
Figure 5.12 Singleton message handlers
A message handler may define a template for the custom parameters that are expected for all messages delivered to that handler. Parameter templates are discussed in Section 5.4.3. In the case of a reregistation request (as in the above example), the path property may be an absolute URL. By contrast path properties for messages defined within a resource handler are always relative to a base URL as discussed in the next section.
5.4.2 Resource Handlers
A Tool may expose many different kinds of resources that can be launched from the Tool Consumer. For example, a given Tool might expose tutorials, homework assignments, quizzes, simulators, etc. Each type of resource may potentially have a different endpoint in the Tool Provider. Furthermore, each type of resource may require a different set of parameters when it is launched. The Tool Profile introduces the concept of a Resource Handler to capture these variations.
For each type of resource, the Tool Profile may declare a distinct Resource Handler, as illustrated by the example in Figure 5.13. The Resource Handler has a code that identifies the type of resource that is being made available through the LTI integration. This code must be unique within the associated product_family (see Section 5.1.2).
The Resource Handler has a name that is suitable for display to end users. The Tool Consumer MAY choose to display this name to content builders who are authoring links within the Tool Consumer user interface. The Resource Handler also has an optional description which the Tool Consumer might display as well.
When designing a Tool Profile, the Tool Provider must decide how it wants to expose its resources. It may choose to use a single Resource Handler for all resources. However, if different resources are accessed through different endpoints, then multiple Resource Handlers will be necessary. Each Resource Handler defines its own Message Handler for the basic-lti-launch-request message.
Furthermore, if different resources require different sets of parameters, then it may be useful to define separate Resource Handlers – even if they all have the same endpoint – because each Resource Handler can specify its own template for parameters. Parameter templates are discussed in the next section.
Finally, each Resource Handler may enable a different set of capabilities, as discussed in Section 5.4.4.
|
{ "resource_type" : "urn:lti:ResourceType:acme.example.com/nitrolab/homework" , "name" : { "default_value" : "Acme Homework Assignment" }, "description" : { "default_value" : "A homework assignment related to a chapter in your textbook" }, "message" : [ { "message_type" : "basic-lti-launch-request" , "path" : "resource/homework" , "parameter" : [ { "name" : "discipline" , "fixed" : "chemistry" }, { "name" : "lis_person_name_given" , "variable" : "$Person.name.given" }, { "name" : "textbook_isbn" }, { "name" : "chapter" } { "name" : "result_id" , "value" : "$Result.id", } ], "enabled_capability : ["Result.autocreate"] } ] } |
Figure 5.13 Example Resource Handler
5.4.3 Parameter templates
Each Message Handler within a Tool Profile may declare a parameter template that specifies the custom parameters that should be included in all messages sent to that handler. Figure 5.13 shows an example of a template that contains five custom parameters.
Each parameter within the template has a name. When a custom parameter is rendered in a basic-lti-launch-request, the HTTP POST binding of the parameter includes the prefix “custom_” as discussed in Section 4.2. Thus, the parameters listed in Figure 5.13 will have the following names in the HTTP POST binding:
- custom_discipline
- custom_lis_person_name_given
- custom_textbook_isbn
- custom_chapter
- custom_result_id
Each parameter in the template may have a fixed value, a variable value, or no value specified. If the value is fixed, then every message sent to the Message Handler must include the specified parameter with the exact literal value that is defined in the Tool Profile. If the value is a variable, the Tool Consumer SHOULD substitute the variable with the appropriate value at runtime when it constructs a message. If the Tool Consumer is unable to expand the variable, then it MUST supply the name of the variable as the parameter value in the message. If no value is specified in the Tool Profile, then a content builder needs to specify a value when authoring the link.
The use of parameter templates is optional. However, if the parameter template is empty, the content builder is responsible for defining all parameters without any guidance.
5.4.4 Enabled Capabilities
A Message Handler may declare a set of capabilities that it wishes to enable for messages sent to the given endpoint. In LTI 2.0, there is only one relevant capability, namely the Result.autocreate capability, which was discussed in Section 5.3.3. The Message Handler enables a capability merely by listing it as shown in Figure 5.13.
5.4.5 Base URLs
Within a Tool Profile, the endpoint for a basic-lti-launch-request is defined relative to a certain base URL.
Figure 5.14 Base URL Choice
The base_url_choice object defines two options for the base URL: (1) a default base URL and (2) a secure base URL.
The Tool Consumer applies the following rules to choose the correct base URL:
- If the Tool is being launched from a secure web page in the Tool Consumer system (i.e. protected by SSL) and the secure_base_url is defined, then use that value for the base URL.
- Otherwise, use the default_base_url.
These rules ensure that end users won’t see the “mixed content” warning in circumstances where the Tool resource is embedded in an iframe within the Tool Consumer user interface.
The secure_base_url is optional; it is omitted if the Tool Provider does not support SSL. By contrast, the default_base_url is a required element.
If the Tool Provider wants all of its resources to be protected by SSL, it should use the https protocol in the default_base_url and leave the secure_base_url undefined.
5.5 The Security Contract
Figure 5.15 Example Security Contract
The security contract contains two key pieces of information:
- A shared secret
- The subset of services offered by the Tool Consumer which the Tool intends to use.
The example in Figure 5.11 shows that the Tool intends to use just one service offered by the Tool Consumer, namely the Result Service. In general, the Tool may use as many services as the Tool Consumer offers. The contract element within the tool_service must match exactly the contract for a service that is offered in the Tool Consumer Profile. The Tool also declares exactly which methods on the service it intends to use; the set of methods declared here must be a subset of the method offered in the Tool Consumer Profile.
The shared secret is used to digitally sign launch requests in accordance with the OAuth.
When launching a Tool via the Tool Proxy, the value of the oauth_consumer_key is given by the GUID for the Tool Consumer instance, and the oauth_consumer_secret is given by the shared_secret element within the security_contract.
6 Tool Management
6.1 Establishing an Integration Contract
The process of establishing an integration contract involves three key steps.
- Request access to a Tool. A Tool Consumer administrator requests access to a Tool.
- Fetch Tool Consumer Profile. The Tool fetches a Tool Consumer Profile from the Tool Consumer system and confirms that the Tool Consumer satisfies the minimum requirements for a successful integration.
- Register a Tool Proxy. The Tool Provider creates a so-called Tool Proxy and registers it with the Tool Consumer system.
- Make the Tool Proxy Available.
The Tool Proxy effectively defines the integration contract between the Tool Consumer and the Tool.
Let’s examine these steps in more detail.
6.1.1 Request Access to a Tool
To register a new Tool within a Tool Consumer system, the Tool Consumer administrator submits a so-called Tool Proxy Registration Request. The Tool Consumer administrator must know the web address (URL) to which this request should be submitted within the Tool Provider system. The LTI specification does not say how the Tool Consumer administrator discovers this URL. Typically, the URL will be published somewhere, or the administrator might receive it in an email from the Tool’s vendor or a service provider.
The Tool Consumer administrator enters this URL into a user interface exposed by the Tool Consumer application. In response, the Tool Consumer constructs a Tool Proxy Registration Request which is returned to the user’s browser as a collection of hidden HTML form parameters, and the form is auto-submitted to the specified URL.
Figure 6.1 illustrates a sample Tool Proxy RegistrationRequest generated by the Tool Consumer application after the Tool Consumer administrator enters the URL “https://acme.example.com/lti/registration”.
Figure 6.1 Sample Tool Proxy Registration Request
See Section 4.5 for a description of the fields in the Tool Proxy Registration Request.
Upon receiving a Tool Proxy Registration Request, the Tool Provider may optionally require the user to authenticate himself or herself. LTI does not prescribe any particular authentication procedure.
6.1.2 Fetch Tool Consumer Profile
The Tool Provider retrieves the Tool Consumer Profile by issuing an HTTP GET request to the URL specified by the tc_profile_url parameter. The Tool Provider specifies the version of LTI that it intends to use for the integration contract by adding an lti_version query parameter to the URL. For example, suppose the Tool Consumer Profile URL is declared as
tc_profile_url = http://coyote.example.biz/lti/ToolConsumerProfile/72942860da8611e095720800200c9a66
Then, to establish a contract based on LTI version 2.0, the Tool Provider would issue a GET request to the URL
http://coyote.example.biz/lti/ToolConsumerProfile/72942860da8611e095720800200c9a66?lti_version=LTI-2p0
The Tool Provider examines the Tool Consumer Profile and confirms that the capabilities and services offered by the Tool Consumer are compatible with the needs of the Tool.
The Tool Provider may optionally interact with the Tool Consumer administrator who submitted the Tool Proxy Registration Request. For example, if the Tool Consumer Profile offers a Result Service for receiving outcomes, the Tool Provider may give the user an opportunity to enable grade data exchange so that scores on assessments taken in the Tool will be reported back to the Tool Consumer.
6.1.3 Register a Tool Proxy
As discussed above, Tool Consumer advertises in the Tool Consumer Profile those services and capabilities that it is offering to the Tool Provider, and the Tool Provider chooses a subset of those services and capabilities that it wishes to enable. Once the Tool Provider has determined the services and capabilities that will be used within the context of the integration contract, it constructs a Tool Proxy as described in Section 5 and submits it to the Tool Consumer via an HTTP request posted to the Tool Proxy REST service. For more information about this service, see Section 10.1.
At this point, the Tool Proxy is registered with the Tool Consumer, but it is not yet available for use.
6.1.4 Make the Tool Proxy Available
Before the Tool Proxy can be used within the Tool Consumer, it must be placed into the “available” state. The Tool Provider will not have access to any Tool Consumer services until such access has been authorized by the Tool Consumer administrator.
Once the Tool Proxy has been registered, the Tool Provider redirects the user’s browser back to the Tool Consumer system at the URL specified by the launch_presentation_return_url parameter of the Tool Proxy Registration Request. To this URL, the Tool Provider appends the following HTTP query parameters:
status = success
tool_proxy_guid = <globally unique identifier for the Tool Proxy>
where the value for the tool_proxy_guid parameter is obtained from the response returned by the Tool Proxy REST service. Typically, this action redirects the browser to a page within the Tool Consumer system where the Tool Proxy can be made available.
At this point, the Tool Consumer should display a warning about the security implications of making the Tool Proxy available. For each data type (personal information, course information, grades, etc.) the Tool Consumer should disclose the access permissions being requested by the Tool Provider. As a general rule, the Tool Consumer should not merely report the specific web service operations and that the Tool Provider will be authorized to access since this information may not be meaningful to the typical administrator. Instead, for each data type, the Tool Consumer should disclose whether or not the Tool Provider will be able to create, read, update or delete that kind of data.
These details are derived from the security contract and the variables that are referenced in the Tool Proxy. For example, suppose the Tool Proxy reveals that the Tool Provider intends to utilize the $Person.name.given variable. In this case, the Tool Consumer should disclose that the Tool will be granted permission to read personally identifiable information. Similarly, if the Tool Proxy reveals that the Tool Provider intends to use the Result Service, the Tool Consumer should disclose that the Tool will be granted read/write permissions for scores in the online grade book. This disclosure step is a best practice. It is not required for LTI compliance.
Once the Tool Consumer administrator has reviewed the disclosures, he or she should perform an action to make the Tool Proxy available within the Tool Consumer system – typically by clicking a button on the web page.
6.2 Enabling Tools within a Learning Context
Typically, Tools that are available within a Tool Consumer are not automatically enabled for use within every course section or learning context managed by the Tool Consumer. Instead, Tools must be enabled within each individual learning context. The practice of enabling Tools within a learning context serves several purposes:
- Allows users to choose which version of a Tool is appropriate for a given learning context (assuming that the Tool Consumer supports multiple, side-by-side versions of a Tool).
- Allows the Tool Consumer to track Tool usage.
- Allows users to choose the right set of Tools for the learning context so that they are not overwhelmed by options for Tools that are completely irrelevant.
The Tool Consumer’s user interface should provide some way for Instructors and Course Builders to view a list of all available Tools and then enable or disable the ones that are of interest to them in any given learning context. The Tool Consumer may choose to automatically enable certain Tools in every learning context by default.
The association of a Tool Proxy with a learning context is called a Tool Proxy Binding. LTI 2.0 does not define an explicit representation for a Tool Proxy Binding, but conceptually it contains the following attributes:
- Identifier for a learning context
- Identifier for a Tool Proxy
- Status of the Tool Proxy within the learning context (enabled or disabled).
6.3 Administrator / Instructor User Interfaces / Custom Parameters
While the user interface is completely up to the Tool Consumer, there are several user interface patterns that have evolved to be quite effective in practice. There are two primary use case patterns:
6.3.1 Instructor Creates New Tools
If the Tool Consumer decides to allow the instructor to place tools without administrator action by getting a URL, key, and secret from a Tool Provider and plugging them into a course structure. In this case, it is a good practice to allow the instructor to enter custom parameters without requiring administrator assistance. Some TPs will need custom parameters to function properly. Also if the instructor is using a Tool Consumer to produce an IMS Common Cartridge with Basic LTI links in the cartridge, often setting custom parameters for a tool placement is an essential part of authoring a cartridge.
6.3.2 Admin Creates New Tools, Instructor Only Places Tools
Another common case is to only allow the administrator to create new tools (i.e. key/secret/url) and then let the instructor place those pre-configured tools in their courses. In this use case, instructors never handle url/key/secret values. Even in this use case it is important to allow the instructor to be able to set or augment custom parameters for each placement. These parameters may be necessary for the Tool Provider to function and/or may be necessary if the instructor is building a course in the Tool Consumer to be exported into an IMS Common Cartridge. It is not necessary to always give the instructor the option to configure custom parameters but it should be possible for the administrator to make a choice to reveal a user interface to set custom parameters.
6.4 Other Tool Management Use Cases
The LTI Tool Management specification [LTI, 12 TMT] describes a number of other use cases including:
- Updating a Tool Proxy within a Tool Consumer
- Setting Tool Provider Domain Credentials
- Setting Link Level Credentials
- Launching an Authored Basic LTI Link from a Context
- Launching Basic LTI Imported from a Cartridge (with secret)
- Launching Basic LTI Imported from a Cartridge (no secret)
- Returning a decimal score from the Tool Provider to the Tool Consumer (deprecated)
7 Link Authoring
When an LTI link is created it may be associated with one of four possible entities:
- Link Level Security Credentials
- Tool Consumer Wide Domain Security Credentials
- Tool Consumer Wide URL Security Credentials
- An LTI Resource Type
For more information about the relationship between an LTI link and Security credentials, see Section 8.
7.1 Authoring Links with Link-Level Credentials
If the Tool Consumer chooses to support link-level credentials, they are supporting the ability for the Instructor to author Basic LTI links inside of the Tool Consumer. The minimal authoring screen is very simple.
Figure 7.1 Authoring screen for LTI links inside of the Tool Consumer.
.
Another possible authoring interface might be to allow the pasting of the XML basic_lti_link descriptor into an input field.
Figure 7.2 Sample pasting of an LTI link in XML
As a best practice, Tool Consumer systems should support both the URL/Key/Secret and XML/Key/Secret of authoring a Basic LTI link. The user interface for these options and how and where these options are shown to the user is up to the Tool Consumer.
The Tool Consumer might add other features like frame height, "open in new window" or add a title field to the link entry.
Figure 7.3 Sample interface for including various options inside the Tool Consumer
These screens will be available in the Tool Consumer where the Instructor is creating the course organization and adding a new link. A typical approach is to make creating a Basic LTI launch just one more type of Tool Consumer link in the course structure.
7.2 Authoring links associated with a Resource Type
Once a collection of Tool Proxies have been registered, the Tool Consumer should expose an interface for creating links associated with the Resource Handlers defined in those Tool Proxies. The LTI standard does not prescribe a user experience for creating links, but a typical implementation might present the user with a list box like the one illustrated schematically in Figure 7.4. In this example, the labels in the list box correspond to the name attributes of the various Resource Handlers. The Tool Consumer might display the Resource Handler description as a tooltip when the user’s mouse hovers over a selection.
When an LTI Link is created in this way, the Tool Consumer must associate the new link with the selected Resource Type.
Each Resource Type is uniquely identified by three values:
- Vendor Code
- Product Code
- Resource Code
|
Link To |
|
Acme Chemlab Homework |
|
Acme Chemlab Redox Simulator |
|
Beta Quiz |
|
Gamma Lesson Plan |
|
eBook from Delta Publishing |
Figure 7.4 List Box for creating links
The vendor code is globally unique, the product code is unique within the namespace of the vendor, and the resource code is unique within the namespace of the product family.
The internal representation of an LTI link must somehow associate each link with a Resource Type. Typically, this association is established by attaching the three properties listed above (vendor code, product code, and resource code) to the link.Thus, given an LTI Link, it is possible to discover the corresponding Resource Handler by applying the following algorithm:
- From the set of Tool Proxies enabled within the learning context, find the Tool Proxy whose Tool Profile contains the given vendor code and product code.
- Within the Tool Profile, find the Resource Handler for the Resource Type identified by the resource code.
When launching a Tool via an LTI Link that is associated with a Resource Type, the Tool Consumer must construct the appropriate endpoint URL from the Resource Handler as discussed in Section 5.4.5.
8 LTI Security Model
8.1 LTI Credential Management
For an LTI link that is set up via the tool registration request, the launch URL, key, and secret are set in the registration request sent from the Tool Provider to the Tool Consumer. The security environment for basic LTI launch requests must be set up using out-of-band interactions between the Tool Provider administrator and either the Tool Consumer administrator or an instructor who will be authoring an LTI link.
There are three possible credentials (keys and secrets) associated with a particular LTI launch, listed in precedence order where Tool Provider domain credentials have the highest precedence.
• Credentials associated with a Tool Provider domain. These credentials authorize access to all Tool Provider URLs from the Tool Consumer. Once the Tool Provider domain credentials are established for a Tool Provider, all LTI tool launches to the Tool Provider will use this same secret. Using Tool Provider domain credentials gives Tool Providers the option of trusting user information and context information across multiple contexts within a particular Tool Consumer instance as being maintained properly by the Tool Consumer.
In order to select which Tool Provider domain credentials are used for a particular LTI link, the Tool Consumer examines the domain name in the launch URL for the LTI link. The Tool Provider domain credentials are looked up after scanning the domain name of the launch URL. So for example, if the launch URL was:
http://launch.math.vendor.com/launch.php
the Tool Consumer would prefer the following Tool Provider domain credentials in order from specific to general: launch.math.vendor.com, math.vendor.com, and then vendor.com. So when Tool Providers are generating link URLs and giving them to an instructor or embedding those links in a cartridge, it is important to use consistent domain names in those launch URLs so as to be able to match a Tool Provider domain credentials for a particular Tool Provider with the appropriate launches.
• Credentials associated with a Tool Provider URL. These credentials authorize access to a particular Tool Provider URL from the Tool Consumer. These are typically used when the administrator is enabling a remote tool within the Tool Consumer with a preset configuration that can be added to a context by the instructor with little or no further configuration.
• Credentials associated with a particular link. These credentials authorize access to the resource at the URL specified by the link. The instructor typically enters these credentials at the moment that the link is created in the context.
Basic LTI launches can happen from the Tool Consumer with any combination of credentials. When more than one is present, the Tool Consumer uses the highest precedent credentials to sign the request.
If there are no credentials available for this launch and the Tool Consumer wants to perform the launch, the Tool Consumer should not sign the launch data using OAuth. The Tool Consumer can decide if it wants to send unsigned requests and the Tool Provider can decide if it wants to accept unsigned requests. A Tool Consumer may also choose to treat the lack of credentials as an error and refuse to perform the launch.
8.2 OAuth Message Signing for x-www-form-encoded Messages
OAuth is a security mechanism designed to protect HTTP POST and GET requests. This section only applies to protecting launch and other LTI messages that are being serialized and sent using POST and a content type of x-www-form-encoded.
The site http://www.oauth.net contains the specification for OAuth 1.0 and sample source code for implementing OAuth security [OAuth, 10]. OAuth 1.0 specifies how to construct a base message string and then sign that string using the secret. The signature is then sent as part of the POST request and is validated by the Tool Provider using OAuth.
Per the OAuth specification, the signing process produces a number of values that are to be added to the launch request:
oauth_consumer_key=b289378-f88d-2929-lmsng.school.edu
oauth_signature_method=HMAC-SHA1
oauth_timestamp=1244834250
oauth_nonce=1244834250435893000
oauth_version=1.0
oauth_signature=Xddn2A%2BjzwjgBIVYkvigaKxCdcc%3D
The important values for signing a message using OAuth are the oauth_consumer_key and oauth_consumer_secret. The value of the oauth_consumer_key depends on which credentials are being used.
The oauth_consumer_key is passed in the message as plain text and identifies which Tool Consumer is sending the message allowing the Tool Provider to look up the appropriate secret for validation. The oauth_consumer_secret is used to sign the message.
Tool Consumer and Tool Provider must at least support and use the HMAC-SHA1 signing method with OAuth fields coming from POST parameters for launch requests.
Since we are using OAuth in a signing-only scenario (i.e., we are not using OAuth to transfer third-party identity), there is no need for an oauth_token as per OAuth 1.0 documentation section 6.2.3. Since most of the OAuth implementations in the marketplace have upgraded to OAuth 1.0A, Tool Consumers should include oauth_callback and set it to a value such as "about:blank". Note that LTI's launch_presentation_return_url serves a very different purpose than OAuth's oauth_callback.
Upon receipt of the POST, the Tool Provider will perform the OAuth validation utilizing the shared secret it has stored for the oauth_consumer_key. The timestamp should also be validated to be within a specific time interval. This time interval can be Tool Provider defined, but should be small (on the order of a few minutes if you do not record nonces or a few hours if you do).
The Tool Provider should keep a record of nonces received and only allow the use of any nonce a single time. Combined with the timestamp, this means that they only have to keep track of nonces for a period of time equal to their acceptable time interval. Recommended practice would be to have a time interval of 90 minutes so that you keep a record of nonces for 90 minutes.
NOTE that this security profile requires the Tool Consumer and Tool Provider to have synchronized clocks. The use of a configurable time interval can adjust for slightly-off clocks, but setting the interval too large is discouraged.
8.3 OAuth Message Body Signing for HTTP Requests
These services follow a "Plain Old XML" (POX) pattern and the messages are signed using OAuth body signing to insure message integrity and establish the identity of the calling system.
The body of the message is XML that follows the schema for the particular requested service operation requested and the message is signed using the oauth_consumer_key and associated oauth_consumer_secret.
The procedure for signing a body using OAuth [OBH, 11] is described on this web site:
http://oauth.googlecode.com/svn/spec/ext/body_hash/1.0/oauth-bodyhash.html
It is important that all messages using these services must use a content type of application/xml. The services will legitimately regect any other content type. In partcular, the OAuth body signing specification specifically prohibits the combination of oauth_body_hash and x-www-form-encoded data in any request.
Also these services will insist that all of the OAuth parameters are sent as part of the Authorization header. In particular, OAuth parameters from the request URL and POST body will not be processed.
The oauth_body_hash is computed using a SHA-1 hash of the body contents and added to the Authorization header. All of the OAuth parameters, HTTP method, and URL are signed like any other OAuth signed request. Other than in constructing the body hash value, the actual POST data is not involved in the computation of the oauth_signature.
Most OAuth libraries can produce and verify the signatures for these messages as most libraries already support sending OAuth parameters in the Authorization header.
A sample signed request is shown below. The line-breaks in the Authorization header are there to make it easier to read the values. The oauth_signature is not valid for the data below - it is just an example signature.
POST http://www.imsglobal.org/developers/BLTI/service_handle.php HTTP/1.0
Host: 127.0.0.1:80
Content-Length: 615
Authorization: OAuth realm="",oauth_version="1.0",
oauth_nonce="29f90c047a44b2ece73d00a09364d49b",
oauth_timestamp="1313350943",oauth_consumer_key="lmsng.school.edu",
oauth_body_hash="v%2BxFnmDSHV%2Fj29qhxLwkFILrtPo%3D",
oauth_signature_method="HMAC-SHA1",
oauth_signature="8auRpRdPY2KRXUrOyz3HKCs92y8%3D"
Content-type: application/xml
<?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>
9 Representing Basic LTI Links in a Cartridge
A basic LTI link is a simplified and self-contained LTI link. The basic LTI link is defined in the resource section of an IMS Common Cartridge as follows:
<resource identifier="I_00010_R" type="imsbasiclti_xmlv1p0">
<file href="I_00001_R/BasicLTI.xml"/>
</resource>
The href in the resource entry refers to a file path in the cartridge that contains an XML description of the basic LTI link.
<?xml version="1.0" encoding="UTF-8"?>
<cartridge_basiclti_link xmlns="http://www.imsglobal.org/xsd/imslticc_v1p0"
xmlns:blti = "http://www.imsglobal.org/xsd/imsbasiclti_v1p0"
xmlns:lticm ="http://www.imsglobal.org/xsd/imslticm_v1p0"
xmlns:lticp ="http://www.imsglobal.org/xsd/imslticp_v1p0"
xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation = "http://www.imsglobal.org/xsd/imslticc_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticc_v1p0.xsd
http://www.imsglobal.org/xsd/imsbasiclti_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imsbasiclti_v1p0.xsd
http://www.imsglobal.org/xsd/imslticm_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticm_v1p0.xsd
http://www.imsglobal.org/xsd/imslticp_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticp_v1p0.xsd">
<blti:title>Grade Book</blti:title>
<blti:description>Grade Book with many column types</blti:description>
<blti:custom>
<lticm:property name="keyname">value</lticm:property>
</blti:custom>
<blti:extensions platform="my.lms.com">
<lticm:property name="keyname">value</lticm:property>
</blti:extensions>
<blti:launch_url>url to the basiclti launch URL</blti:launch_url>
<blti:secure_launch_url>secure url to the basiclti launch URL</blti:secure_launch_url>
<blti:icon>url to an icon for this tool (optional)</blti:icon>
<blti:secure_icon>secure url to an icon for this tool (optional)></blti:secure_icon>
<blti:vendor>
<lticp:code>vendor.com</lticp:code>
<lticp:name>vendor.name</lticp:name>
<lticp:description>This is a vendor of learning tools.</lticp:description>
<lticp:url>http://www.vendor.com/</lticp:url>
<lticp:contact>
<lticp:email>support@vendor.com</lticp:email>
</lticp:contact>
</blti:vendor>
<cartridge_bundle identifierref="BLTI001_Bundle"/>
<cartridge_icon identifierref="BLTI001_Icon"/>
</cartridge_basiclti_link>
The launch_url contains the URL to which the LTI Launch is to be sent. The secure_launch_url is the URL to use if secure http is required. One of either the launch_url or the secure_launch_url must be specified. It is acceptable to specify both and if both are specified, the Tool Consumer decides which to use. Typically, the Tool Consumer will use a secure_launch_url when embedding the Tool in a secure page and the launch_url when embedding the tool in a non-secure page. So, it’s important that the Tool Provider provides the same functionality whether the launch_url or secure_launch_url is used.
The icon and secure_icon are both optional and indicate a URL to be used for an icon to the tool.
Once the basic LTI link is defined in the resources section of the cartridge manifest, it can be referenced in the organization section of the manifest as needed:
<item identifier="BasicLTI1" identifierref="I_00010_R">
<title>Homework Problems</title>
</item>
The Tool Consumer will generally display the title in the item entry in the user interface rather than title in the basic_lti_link entry.
The optional custom section can contain a set of key value pairs that were placed in the link in the system that originally authored the link. For example if the link were a section in an eTextbook, there might be a setting like:
<parameter key="section ">1.2.7</parameter>
These parameters are sent back to the external tool when the tool is launched. If a basic LTI link is imported and then exported the custom should be maintained across the import/export process unless the intent is to re-author the link.
The extensions section allows the hosting Tool Consumer to add its own key/value pairs to the link. The Tool Consumer may use extensions to store information that the Tool Consumer or authoring environment might use across an export-import cycle. In order to allow multiple sets of extensions to be contained in the same basic LTI descriptor, authoring environments should add the platform attribute and include an identifier that identifies the authoring environment.
It is possible to include the icon for the link in the cartridge instead of including it as a URL using the cartridge_icon entry in the descriptor. The identifierref attribute points to a link that includes the icon image and a dependency is added to the resource section of the basic LTI resource entry in the manifest as shown below.
<resource identifier="I_00010_R" type="imsbasiclti_xmlv1p0">
<file href="I_00001_R/BasicLTI.xml"/>
<dependency identifierref="BLTI001_Icon "/>
</resource>
<resource identifier="BLTI001_Icon"
type="associatedcontent/imscc_xmlv1p0/learning-application-resource">
<file href="BLTI001_Media/learning_icon.gif"/>
</resource>
10 Using Services
A Tool Consumer can offer various services to the Tool Provider through the Tool Consumer Profile. This chapter discusses the services defined in LTI 2.0.
10.1 Tool Proxy Service
In LTI 2.0 it is possible to create and update a Tool Proxy via a REST endpoint. Methods to read or delete a Tool Proxy are defined in LTI 2.0, but a conforming Tool Consumer is not required to support these methods. Interactions with the Tool Proxy REST service are described in Section 6 and also in [LTI, 12 TMT].
To create a new Tool Proxy, the Tool Provider must first receive a Tool Proxy Registration Request which contains the URI for the Tool Consumer Profile (tc_profile_url) and a set of one time credentials (reg_key, reg_password) which entitles the Tool Provider to register one new Tool Proxy within the Tool Consumer. For example, the Tool Provider receives a registration request like the one shown in Figure 10.1.
|
POST /lti/registration Content-Type: application/x-www-form-urlencoded Content-Length: 413
tc_profile_url= http%3A%2F%2Flms.server.com%2Fprofile%2Fb6ffa601-ce1d-4549-9ccf-145670a964d4 & reg_key= 869e5ce5-214c-4e85-86c6-b99e8458a592& reg_password= e9fd6071-0641-4101-b814-9a088c445292& ... |
Figure 10.1 Sample Tool Proxy Registration Request
The Tool Provider issues an HTTP GET request to the URL specified by the tc_profile_url parameter in order to receive the Tool Consumer Profile. The response is a JSON document that conforms to the application/vnd.ims.lti.v2.ToolConsumerProfile+json media type [LTI, 12 REST]. The Tool Consumer Profile includes a list of all the services offered including the Tool Proxy REST service as shown in Figure 10.2.
Figure 10.2 Declaration of Tool Proxy REST Service
To find the REST endpoint for creating a new Tool Proxy, the Tool Provider searches in the Tool Consumer Profile for a service that supports the application/vnd.ims.lti.v2.ToolProxy+json format and the POST action. In the example shown in Figure 10.2, the REST endpoint is http://lms.server.com/resources/ToolProxy.
To register a new Tool Proxy, the Tool Provider issues a POST request to the specified endpoint, using the reg_password value as the oauth_consumer_secret when signing the request. Thus, the Tool Provider submits a request like the one shown in Figure 10.3.
|
POST https://lms.server.com/resources/ToolProxy Content-Type: application/vnd.ims.lti.v2.ToolProxy+json Content-Length: 4618 Authorization: OAuth realm="", oauth_version="1.0", oauth_nonce="29f90c047a44b2ece73d00a09364d49b", oauth_timestamp="1313350943", oauth_consumer_key="869e5ce5-214c-4e85-86c6-b99e8458a592" , oauth_body_hash="v%2BxFnmDSHV%2Fj29qhxLwkFILrtPo%3D", oauth_signature_method="HMAC-SHA1", oauth_signature="8auRpRdPY2KRXUrOyz3HKCs92y8%3D"
{ "@context" : "https://www.imsglobal.org/imspurl/lti/v2/ctx/ToolProxy", ... } |
Figure 10.3 Request to register a new Tool Proxy
There are two important points to note about this request. First, the Tool Proxy representation must conform to the application/vnd.ims.lti.v2.ToolProxy+json media type as specified in [LTI, 12 REST]. Second, the oauth_consumer_key must be given the value of the reg_key parameter from the original registration request. This is a special case because the Tool Provider has not yet established a relationship with the Tool Consumer. In all subsequent service interactions with the Tool Consumer, the Tool Provider will use the Tool Proxy GUID as the oauth_consumer_key together with the shared secret that is encapsulated within the Tool Proxy resource, but clearly those credentials are not available in this case because the Tool Proxy resource has not yet been created.
The HTTP response from the POST request in Figure 10.3 is a small JSON document as shown in Figure 10.4.
|
HTTP/1.0 201 Created Date: Thu, 10 May 2012 11:09:42 GMT Content-Type: application/vnd.ims.lti.v2.ToolProxy.id+json Content-Length: 256 Location: https://lms.server.com/ToolProxy/869e5ce5-214c-4e85-86c6-b99e8458a592
{ "@context" : "http://www.imsglobal.org/imspurl/lti/v2/ctx/ToolProxyId", "@type" : "ToolProxy", "@id" : "https://lms.server.com/ToolProxy/869e5ce5-214c-4e85-86c6-b99e8458a592", "tool_proxy_guid" : "869e5ce5-214c-4e85-86c6-b99e8458a592" }
|
Figure 10.4 Response from Tool Proxy POST
Notice that the response conforms to the application/vnd.ims.lti.v2.ToolProxy.id+json media type [LTI, 12 REST]. The JSON payload specifies the GUID of the newly created Tool Proxy, and also its URI as the @id property. As a best practice, the URI should also be given in the Location header.
Subsequently, the Tool Provider may update the Tool Proxy by issuing an HTTP PUT request to the given URI, as illustrated in Figure 10.5. For more information about the use case for updating a Tool Proxy, see [LTI, 12 TMT]. Notice that the request body contains a JSON document using the same format as the original POST request. However, in this case, the oauth_consumer_key is given by the value of the tool_proxy_guid that was returned from the POST request.
|
PUT https://lms.server.com/resources/ToolProxy/ 869e5ce5-214c-4e85-86c6-b99e8458a592 Content-Type: application/vnd.ims.lti.v2.ToolProxy+json Content-Length: 4618 Authorization: OAuth realm="", oauth_version="1.0", oauth_nonce="10288510250934", oauth_timestamp="1313350943", oauth_consumer_key="869e5ce5-214c-4e85-86c6-b99e8458a592" , oauth_body_hash="Lve95gjOVATpfV8EL5X4nxwjKHE%3D", oauth_signature_method="HMAC-SHA1", oauth_signature="08bUFF%2Fjmp59mWB7cSgCYBUpJ0U%3D"
{ "@context" : "http://www.imsglobal.org/imspurl/lti/v2/ctx/ToolProxy", ... } |
Figure 10.5 Request to update an existing Tool Proxy
As shown in Figure 10.9, the response body from a PUT request is
empty since the Tool Proxy GUID and URI are already known to the
Tool Provider.
|
HTTP/1.0 202 Accepted Date: Thu, 05 Dec 2012 15:28:32 GMT |
Figure 10.6 Response from Tool Proxy PUT request
The Tool Consumer should return a 202 (Accepted) status instead of a 200 (OK) status because the update of the Tool Proxy within the Tool Consumer system must be approved by the Tool Consumer administrator before the update process is complete. See [LTI, 12 TMT] for more details.
10.2 LIS Result Service
This RESTful service supports reading and updating individual LIS Result objects [LIS, 11]. The LTI 2.0 contract for this service presents a narrow “view” of the underlying Result object. This view consists of nothing but the learner’s score on an assignment, which is constrained to be a decimal value in the range [0.0, 1.0]. The LTI 2.0 contract does not support creating or deleting Result objects by a Tool; the Tool Consumer is responsible for creating and deleting Results.
Before a Tool can use the Result service, it must first be granted access to the service by the Tool Consumer administrator. To that end, the following steps must be followed:
- The Tool Consumer Profile advertises the three capabilities shown in Figure 10.7.
- The Tool Consumer Profile advertises support for the Result service (Figure 10.7).
- The Tool declares its intention to use the Result service in a Tool Proxy that it registers with the Tool Consumer ().
- The Tool Consumer administrator activates the Tool Proxy, thereby granting access to the service.
For more information about these steps, see Section 6.1.
|
{ "@context" : "http://www.imsglobal.org/imspurl/lti/v2/ctx/ToolConsumerProfile", "@type" : "ToolConsumerProfile", ... "capability_offered" : [ "basic-lti-launch-request", "Result.autocreate", "Result.uri" ], "service_offered" : [ { "@type" : "RestService", "@id" : "http://lms.server.com/profile/b6ffa601-ce1d-4549-9ccf-145670a964d4#Result.item", "format" : "application/vnd.ims.lis.v2.Result+json", "endpoint" : "http://lms.server.com/resources/result/{sourcedId}", "action" : [ "GET", "PUT" ] } ] ... }
|
Figure 10.7 Descriptor of Result Service advertised in the Tool Consumer Profile
|
{ "@context" : "http://www.imsglobal.org/imspurl/lti/v2/ctx/ToolProxy", "@type" : "ToolProxy",
"security_contract" : { ... "tool_service" : [ { "@type" : "RestService", "service" : "http://lms.server.com/profile/b6ffa601-ce1d-4549-9ccf-145670a964d4#Result.item", "action" : [ "GET", "PUT" ] } ] } } |
Figure 10.8 Tool Provider declares intention to use Result Service
Each Result object is identified by a URI. Following traditional REST practices, one can read or update a Result object by issuing an HTTP GET or PUT request respectively at the object’s URI. The Tool typically receives the URL for a Result object when the learner launches an assignment from within the Tool Consumer. The Tool must explicitly request that the URL for the Result be delivered as a custom parameter, and it must enable the Result.autocreate capability as shown in Figure 10.9.
Figure 10.9 Resource Handler for launching an assessment
Figure 10.9 shows a portion of a ResourceHandler declared within the Tool Profile. The Tool Consumer offers a user interface for link authoring as described in Section 7.2. With the help of this interface, a Content Developer or Instructor may construct links associated with the ResourceHandler illustrated in Figure 10.9. When such a link is constructed, the Tool Consumer must either create a new LineItem to hold Results, or it must associate the link with an existing LineItem. This behavior is triggered by the fact that the Result.autocreate capability is enabled on the associated ResourceHandler. As a best practice, the Tool Consumer should present the link author with the option of creating a new LineItem or associating the link with an existing LineItem. In both cases, the LineItem must have a ResultValue whose ValueRange constrains scores to decimal values between 0 and 1. The dataSource property of the LineItem must be set equal to the value of the @id property of the product family declared in the Tool Profile (see Figure 10.9). This value may be a URN rather than a URL, but in all cases it must be globally unique.
Since the Result.autocreate capability is enabled, the Tool Consumer will automatically create a Result object before launching the assessment instrument offered by the Tool. In the example illustrated by Figure 10.9, the Tool Consumer will send the URI for the Result object as the result_uri parameter. The Tool is free to choose any name for this parameter.
Since the URI for the Result object is delivered to the Tool Provider as an HTTP POST parameter during launch, it is not necessary for the Tool Consumer to specify a URL template for the Result service endpoint in the Tool Consumer Profile (see Figure 10.7).
10.2.1 The JSON-LD Representation of a Result object
The JSON-LD representation of an LIS Result object (in LTI 1.2) is illustrated in Figure 10.10.
|
{ "@context" : "http://www.imsglobal.org/imspurl/lis/v2/ctx/Result" , "@type" : "Result" , "resultScore" : { "@type" : "decimal" , "@value" : 0.83 } } |
Figure 10.10 Example of Result object with a score
The @context property gives the URI for the JSON-LD context which maps terms in the JSON document to IRIs for unambiguous identification.
The service contract requires that the resultScore has a decimal value in the range [0.0, 1.0].
To unset a previous score, the Tool may PUT a Result representation where the resultScore property is omitted, as shown in Figure 10.11. Unsetting the score is useful because it gives the Learner an opportunity to take the same assignment again. As discussed in Section 5.3.3, a Learner is allowed to launch an assignment only if the current score is unset. Thus, a Tool will need to persist the Result URI from an earlier attempt if it wishes to be able to unset the score later.
The LTI 2.0 profile of the LIS Outcomes model stipulates that each Learner has at most one Result object for a given LineItem. If the Tool modifies a previously defined score in a Result, the Tool Consumer may record a history of the previous scores. However, the Tool Consumer must always present the same URI for the Result when launching an assignment associated with a given LineItem and a given Learner. Subsequent versions of LTI will support more robust control of multiple attempts.
|
{ "@context" : " http://www.imsglobal.org/imspurl/lti/v1/ctx/Outcomes" , "@type" : "Result" } |
Figure 10.11 Example of Result object without a score
For more information about the JSON binding of a Result object and the Result REST Service, see [LTI, 12 REST].
Appendix A – LTI Standard Vocabularies
The LTI v1.0 specification uses URI values to identify certain entities. This section defines simple names for various LIS context types and the corresponding fully qualified URI values. LTI 1.x used URN values for these entities. LTI 2.x supports the old URN values for backward compatibility, but they are deprecated and superceded by a URL that points to an entities in an RDF ontology. Conforming implementation must recognize simple names, the old URN values and the new URL values.
A.1 ContextType Vocabularies
A.1.1 LIS vocabulary for ContextType
|
Simple Names |
Full URI |
|
CourseTemplate |
urn:lti:context-type:ims/lis/CourseTemplate (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/course#CourseTemplate |
|
CourseOffering |
urn:lti:context-type:ims/lis/CourseOffering (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/course#CourseOffering |
|
CourseSection |
urn:lti:context-type:ims/lis/CourseSection (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/course#CourseSection |
|
Group |
urn:lti:context-type:ims/lis/Group (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/course#CourseSection |
A.2 Role Vocabularies
A.2.1 LIS vocabulary for System Role
The following table lists URN values for system role as defined by the LIS standard.
|
Simple Name |
Full URI |
|
SysAdmin |
urn:lti:sysrole:ims/lis/SysAdmin (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/person#SysAdmin |
|
SysSupport |
urn:lti:sysrole:ims/lis/SysSupport (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/person#SysSupport |
|
Creator |
urn:lti:sysrole:ims/lis/Creator (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/person#Creator |
|
AccountAdmin |
urn:lti:sysrole:ims/lis/AccountAdmin (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/person#AccountAdmin |
|
User |
urn:lti:sysrole:ims/lis/User (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/person#User |
|
Administrator |
urn:lti:sysrole:ims/lis/Administrator (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/person#Administrator |
|
None |
urn:lti:sysrole:ims/lis/None (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/person#None |
A.2.2 LIS vocabulary for Institution Role
The following table lists URN values for institution roles as defined by the LIS standard.
|
Simple Name |
Full URI |
|
Student |
urn:lti:instrole:ims/lis/Student (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/person#Student |
|
Faculty |
urn:lti:instrole:ims/lis/Faculty (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/person#Faculty |
|
Member |
urn:lti:instrole:ims/lis/Member (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/person#Member |
|
Learner |
urn:lti:instrole:ims/lis/Learner (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/person#Learner |
|
Instructor |
urn:lti:instrole:ims/lis/Instructor (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/person#Instructor |
|
Mentor |
urn:lti:instrole:ims/lis/Mentor (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/person#Mentor |
|
Staff |
urn:lti:instrole:ims/lis/Staff (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/person#Staff |
|
Alumni |
urn:lti:instrole:ims/lis/Alumni (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/person#Alumni |
|
ProspectiveStudent |
urn:lti:instrole:ims/lis/ProspectiveStudent (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/person#ProspectiveStudent |
|
Guest |
urn:lti:instrole:ims/lis/Guest (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/person#Guest |
|
Other |
urn:lti:instrole:ims/lis/Other (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/person#Other |
|
Administrator |
urn:lti:instrole:ims/lis/Administrator (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/person#Administrator |
|
Observer |
urn:lti:instrole:ims/lis/Observer (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/person#Observer |
|
None |
urn:lti:instrole:ims/lis/None (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/person#None |
A.2.3 LIS vocabulary for Context Role
Roles within the LIS standard [LIS, 11] consist of a RoleType and an optional SubRoleType. The simple name for the corresponding URI value contains both elements, separated by a slash.
|
Handle |
Full URN |
|
Learner |
urn:lti:role:ims/lis/Learner (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership#Learner |
|
Learner/Learner |
urn:lti:role:ims/lis/Learner/Learner (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Learner#Learner |
|
Learner/NonCreditLearner |
urn:lti:role:ims/lis/Learner/NonCreditLearner (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Learner#NonCreditLearner |
|
Learner/GuestLearner |
urn:lti:role:ims/lis/Learner/GuestLearner (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Learner#GuestLearner |
|
Learner/ExternalLearner |
urn:lti:role:ims/lis/Learner/ExternalLearner (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/ Learner#ExternalLearner |
|
Learner/Instructor |
urn :lti:role :ims/lis/Learner/Instructor (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Learner#Instructor |
|
Instructor |
urn:lti:role:ims/lis/Instructor (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership#Instructor |
|
Instructor/PrimaryInstructor |
urn:lti:role:ims/lis/Instructor/PrimaryInstructor (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Instructor#PrimaryInstructor |
|
Instructor/Lecturer |
urn:lti:role:ims/lis/Instructor/Lecturer (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Instructor#Lecturer |
|
Instructor/GuestInstructor |
urn:lti:role:ims/lis/Instructor/GuestInstructor (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Instructor#GuestInstructor |
|
Instructor/ExternalInstructor |
urn:lti:role:ims/lis/Instructor/ExternalInstructor (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Instructor#ExternalInstructor |
|
ContentDeveloper |
urn:lti:role:ims/lis/ContentDeveloper (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership# ContentDeveloper |
|
ContentDeveloper/ContentDeveloper |
urn:lti:role:ims/lis/ContentDeveloper/ContentDeveloper (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/ ContentDeveloper#ContentDeveloper |
|
ContentDeveloper/Librarian |
urn:lti:role:ims/lis/ContentDeveloper/Librarian (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/ContentDeveloper#Librarian |
|
ContentDeveloper/ContentExpert |
urn:lti:role:ims/lis/ContentDeveloper/ContentExpert (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/ContentDeveloper#ContentExpert |
|
ContentDeveloper/ExternalContentExpert |
urn:lti:role:ims/lis/ContentDeveloper/ExternalContentExpert (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/ContentDeveloper#ExternalContentExpert |
|
Member |
urn:lti:role:ims/lis/Member (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership#Member |
|
Member/Member |
urn:lti:role:ims/lis/Member/Member (deprecated)` http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Member#Member |
|
Manager |
urn:lti:role:ims/lis/Manager (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership#Manager |
|
Manager/AreaManager |
urn:lti:role:ims/lis/Manager/AreaManager (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Manager#AreaManager |
|
Manager/ CourseCoordinator |
urn:lti:role:ims/lis/Manager/CourseCoordinator (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Manager#CourseCoordinator |
|
Manager/Observer |
urn:lti:role:ims/lis/Manager/Observer (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Manager#Observer |
|
Manager/ ExternalObserver |
urn:lti:role:ims/lis/Manager/ExternalObserver (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Manager#ExternalObserver |
|
Mentor |
urn:lti:role:ims/lis/Mentor (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership#Mentor |
|
Mentor/Mentor |
urn:lti:role:ims/lis/Mentor/Mentor (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Mentor#Mentor |
|
Mentor/Reviewer |
urn:lti:role:ims/lis/Mentor/Reviewer (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Mentor#Reviewer |
|
Mentor/Advisor |
urn:lti:role:ims/lis/Mentor/Advisor (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Mentor#Advisor |
|
Mentor/Auditor |
urn:lti:role:ims/lis/Mentor/Auditor (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Mentor#Auditor |
|
Mentor/Tutor |
urn:lti:role:ims/lis/Mentor/Tutor (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Mentor#Tutor |
|
Mentor/ LearningFacilitator |
urn:lti:role:ims/lis/Mentor/LearningFacilitator (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Mentor#LearningFacilitator |
|
Mentor/ ExternalMentor |
urn:lti:role:ims/lis/Mentor/ExternalMentor (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Mentor#ExternalMentor |
|
Mentor/ ExternalReviewer |
urn:lti:role:ims/lis/Mentor/ExternalReviewer (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Mentor#ExternalReviewer |
|
Mentor/ ExternalAdvisor |
urn:lti:role:ims/lis/Mentor/ExternalAdvisor (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Mentor#ExternalAdvisor |
|
Mentor/ ExternalAuditor |
urn:lti:role:ims/lis/Mentor/ExternalAuditor (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Mentor#ExternalAuditor |
|
Mentor/ExternalTutor |
urn:lti:role:ims/lis/Mentor/ExternalTutor (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Mentor#ExternalTutor |
|
Mentor/ExternalLearningFacilitator |
urn:lti:role:ims/lis/Mentor/ http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Mentor/ExternalLearningFacilitator |
|
Administrator |
urn:lti:role:ims/lis/Administrator (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership#Administrator |
|
Administrator/ Administrator |
urn:lti:role:ims/lis/Administrator/Administrator (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Administrator#Administrator |
|
Administrator/ Support |
urn:lti:role:ims/lis/Administrator/Support (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Administrator#Support |
|
Administrator/ Developer |
urn:lti:role:ims/lis/Administrator/Developer (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Administrator#Developer |
|
Administrator/ SystemAdministrator |
urn:lti:role:ims/lis/Administrator/SystemAdministrator (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Administrator#SystemAdministrator |
|
Administrator/ExternalSystemAdministrator |
urn:lti:role:ims/lis/Administrator/ http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Administrator#ExternalSystemAdministrator |
|
Administrator/ ExternalDeveloper |
urn:lti:role:ims/lis/Administrator/ExternalDeveloper (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Administrator#ExternalDeveloper |
|
Administrator/ ExternalSupport |
urn:lti:role:ims/lis/Administrator/ExternalSupport (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/Administrator#ExternalSupport |
|
TeachingAssistant |
urn:lti:role:ims/lis/TeachingAssistant (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership# TeachingAssistant |
|
TeachingAssistant/ TeachingAssistant |
urn:lti:role:ims/lis/TeachingAssistant/TeachingAssistant (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/TeachingAssistant# TeachingAssistant |
|
TeachingAssistant/TeachingAssistantSection |
urn:lti:role:ims/lis/TeachingAssistant/TeachingAssistantSection (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/TeachingAssistant#TeachingAssistantSection |
|
TeachingAssistant/ |
urn:lti:role:ims/lis/TeachingAssistant/TeachingAssistantSectionAssociation (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/TeachingAssistant#TeachingAssistantSectionAssociation |
|
TeachingAssistant/ |
urn:lti:role:ims/lis/TeachingAssistant/ http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/TeachingAssistant#TeachingAssistantOffering |
|
TeachingAssistant/ |
urn:lti:role:ims/lis/TeachingAssistant/ http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/TeachingAssistant# TeachingAssistantTemplate |
|
TeachingAssistant/TeachingAssistantGroup |
urn:lti:role:ims/lis/TeachingAssistant/ http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/TeachingAssistant#TeachingAssistantGroup |
|
TeachingAssistant/Grader |
urn:lti:role:ims/lis/TeachingAssistant/Grader (deprecated) http://www.imsglobal.org/imspurl/lis/v1/vocab/membership/TeachingAssistant#Grader |
Appendix B – Implementation Practice
This section includes non-normative discussion and recommendations to help guide implementations.
B.1 Security Policy / SandBoxing Launch Requests
Tool Consumer systems will likely implement a number of security policy related features that can be controlled by both the Tool Consumer administrator and the Instructor. These are some considerations:
- Tool Consumer systems will likely limit the transmission of identifying information for users such as name and E-Mail to a trusted set of TPs.
- Tool Consumer Administrators may want to allow only certain approved/trusted Instructors to be allowed to author their own Basic LTI links.
- The Tool Consumer system may want the ability of an Instructor to further reduce/sandbox the data items transmitted to a Tool Provider.
It is out of the scope of this document to specify how the Tool Consumer system controls which instructors can author LTI links or which URLs can be launched using LTI or which data is shared with particular TPs.
B.2 Roles
Some of the commonly used roles from LIS include Learner, Instructor, Administrator, TeachingAssistant, ContentDeveloper, and Mentor. Multiple roles can be included, separated by commas. Tool Consumer systems should include as many roles as appropriate for the user (i.e., more roles are better). Tool Consumer systems should be aware that simple TPs will key off the presence or absence of the Instructor role and group users into those with the Instructor role (read-write-configure) and those without the Instructor role (read).
B.3 Non-Context LTI Launches
While the typical use of a LTI link is in a context, it is also possible to use LTI to launch a link that is not part of a context. One example of a non-context launch might be a menu item that is part of the portal or part of a global menu in the Tool Consumer.
Supporting non-context launches is optional for both the Tool Provider and Tool Consumer.
If a LTI launch is coming from a non-context placement, the context information is simply omitted and the launch will contain the user and organization information but no context information.
B.4 LTI Sample Launch
The LTI launch protocol is a POST to the launch URL with the LTI parameters described above, properly signed using OAuth.
The most common launch approach will be for the Tool Consumer to emit a form to the browser and then include code to automatically submit the form to the launch URL. The Tool Provider will assume that it is in a browser, process the input parameters, setting session information if necessary and optionally redirecting.
Here is a sample of an HTML form using a password of "secret" and oauth_consumer_key of "12345".
<form
action=http://www.imsglobal.org/developers/LTI/test/v1p1/tool.php
name="ltiLaunchForm" method="post"
encType="application/x-www-form-urlencoded">
<input type="hidden" name="context_id" value="456434513"/>
<input type="hidden" name="context_label" value="SI182"/>
<input type="hidden" name="context_title" value="Design of Personal Environments"/>
<input type="hidden" name="launch_presentation_css_url" value="http://www.imsglobal.org/developers/LTI/test/v1p1/lms.css"/>
<input type="hidden" name="launch_presentation_document_target" value="frame"/>
<input type="hidden" name="launch_presentation_locale" value="en-US"/>
<input type="hidden" name="launch_presentation_return_url" value="http://www.imsglobal.org/developers/LTI/test/v1p1/lms_return.php"/>
<input
type="hidden" name="lis_outcome_service_url"
value="http://www.imsglobal.org/developers/LTI/test/v1p1/common/
tool_consumer_outcome.php?b64=MTIzNDU6OjpzZWNyZXQ="/>
<input type="hidden" name="lis_person_contact_email_primary" value="user@school.edu"/>
<input type="hidden" name="lis_person_name_family" value="Public"/>
<input type="hidden" name="lis_person_name_full" value="Jane Q. Public"/>
<input type="hidden" name="lis_person_name_given" value="Given"/>
<input type="hidden" name="lis_person_sourcedid" value="school.edu:user"/>
<input type="hidden" name="lis_result_sourcedid" value="feb-123-456-2929::28883"/>
<input type="hidden" name="lti_message_type" value="basic-lti-launch-request"/>
<input type="hidden" name="lti_version" value="LTI-1p0"/>
<input type="hidden" name="oauth_callback" value="about:blank"/>
<input type="hidden" name="oauth_consumer_key" value="12345"/>
<input type="hidden" name="oauth_nonce" value="93ac608e18a7d41dec8f7219e1bf6a17"/>
<input type="hidden" name="oauth_signature" value="QWgJfKpJNDrpncgO9oXxJb8vHiE="/>
<input type="hidden" name="oauth_signature_method" value="HMAC-SHA1"/>
<input type="hidden" name="oauth_timestamp" value="1348093590"/>
<input type="hidden" name="oauth_version" value="1.0"/>
<input type="hidden" name="resource_link_description" value="A weekly blog."/>
<input type="hidden" name="resource_link_id" value="120988f929-274612"/>
<input type="hidden" name="resource_link_title" value="Weekly Blog"/>
<input type="hidden" name="roles" value="Instructor"/>
<input type="hidden" name="tool_consumer_info_product_family_code" value="ims"/>
<input type="hidden" name="tool_consumer_info_version" value="1.1"/>
<input
type="hidden" name="tool_consumer_instance_description"
value="University of School (LMSng)"/>
<input type="hidden" name="tool_consumer_instance_guid" value="lmsng.school.edu"/>
<input type="hidden" name="user_id" value="292832126"/>
<input type="submit" value="Press to continue to external tool"/>
</form>
<script language="javascript">
document.ltiLaunchForm.submit();
</script>
This form is designed to work even if JavaScript is turned off in the browser – the user simply presses the submit button. If JavaScript is on, the button is quickly hidden and the form is automatically submitted.
The following is the base string prior to the OAuth signature computation:
POST&http%3A%2F%2Fwww.imsglobal.org%2Fdevelopers%2FLTI%2Ftest%2Fv1p1%2Ftool.php&context_id
%3D456434513%26context_label%3DSI182%26context_title%3DDesign%2520of%2520Personal%2520Envi
ronments%26launch_presentation_css_url%3Dhttp%253A%252F%252Fwww.imsglobal.org%252Fdevelope
rs%252FLTI%252Ftest%252Fv1p1%252Flms.css%26launch_presentation_document_target%3Dframe%26l
aunch_presentation_locale%3Den-US%26launch_presentation_return_url%3Dhttp%253A%252F%252Fww
w.imsglobal.org%252Fdevelopers%252FLTI%252Ftest%252Fv1p1%252Flms_return.php%26lis_outcome_
service_url%3Dhttp%253A%252F%252Fwww.imsglobal.org%252Fdevelopers%252FLTI%252Ftest%252Fv1p
1%252Fcommon%252Ftool_consumer_outcome.php%253Fb64%253DMTIzNDU6OjpzZWNyZXQ%253D%26lis_pers
on_contact_email_primary%3Duser%2540school.edu%26lis_person_name_family%3DPublic%26lis_per
son_name_full%3DJane%2520Q.%2520Public%26lis_person_name_given%3DGiven%26lis_person_source
did%3Dschool.edu%253Auser%26lis_result_sourcedid%3Dfeb-123-456-2929%253A%253A28883%26lti_m
essage_type%3Dbasic-lti-launch-request%26lti_version%3DLTI-1p0%26oauth_callback%3Dabout%25
3Ablank%26oauth_consumer_key%3D12345%26oauth_nonce%3D93ac608e18a7d41dec8f7219e1bf6a17%26oa
uth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1348093590%26oauth_version%3D1.0%26re
source_link_description%3DA%2520weekly%2520blog.%26resource_link_id%3D120988f929-274612%26
resource_link_title%3DWeekly%2520Blog%26roles%3DInstructor%26tool_consumer_info_product_fa
mily_code%3Dims%26tool_consumer_info_version%3D1.1%26tool_consumer_instance_description%3D
University%2520of%2520School%2520%2528LMSng%2529%26tool_consumer_instance_guid%3Dlmsng.sch
ool.edu%26user_id%3D292832126
In the above string, all line wrapping
should be removed. Notice that all of the POST values are
included in the base string (i.e., the string signed by
OAuth).
B.5 Conformance
Conformance for Basic LTI is granted through the IMS CC-LTI Alliance and consists of certification testing for Tool Consumer and Tool Provider implementations. For additional information about conformance, visit the CC-LTI Alliance here: http://www.imsglobal.org/cc/alliance.html.
Appendix C – Custom Parameter Subsitution
Support for substitutable custom parameters is optional and the Tool Provider should anticipate that these parameters may come from the Tool Consumer in their unsubstituted form.
C.1 LTI User Variables
|
Message Variable Name |
Corresponding LTI value |
|
$User.id |
LaunchMixin.user_id (This is the local identifier for the user within the Tool Consumer.) |
|
$User.image |
The URL that contains an image of the user suitable for use as a profile picture or avatar. |
C.2 LIS Person Variables
|
Message Variable Name |
XPath for value from LIS Database |
|
$Person.sourcedId |
personRecord/sourcedId |
|
$Person.name.full |
personRecord/person/formname/[formnameType/instanceValue/text="Full"] /formattedName/text |
|
$Person.name.family |
personRecord/person/name/partName[instanceName/text="Family”]/instanceValue/text |
|
$Person.name.given |
personRecord/person/name/partName[instanceName/text="Given”]/instanceValue/text |
|
$Person.name.middle |
personRecord/person/name/partName[instanceName/text="Middle”]/instanceValue/text |
|
$Person.name.prefix |
personRecord/person/name/partName[instanceName/text="Prefix”]/instanceValue/text |
|
$Person.name.suffix |
personRecord/person/name/partName[instanceName/text="Suffix”]/instanceValue/text |
|
$Person.address.street1 |
personRecord/person/address/[addressType/instanceValue/text="Preferred"]addressPart /nameValuePair /[instanceName/text="NonFieldedStreetAddress1"]/instanceValue /text[2]
|
|
$Person.address.street2 |
personRecord/person/address/[addressType/instanceValue/text="Preferred"] addressPart /nameValuePair[instanceName/text="NonFieldedStreetAddress2"] /instanceValue/text
|
|
$Person.address.street3 |
personRecord/person/address/[addressType/instanceValue/text="Preferred"]addressPart /nameValuePair /[instanceName/text="NonFieldedStreetAddress3"] /instanceValue/text
|
|
$Person.address.street4 |
personRecord/person/address/[addressType/instanceValue/text="Preferred"]addressPart /nameValuePair /[instanceName/text="NonFieldedStreetAddress3"] /instanceValue/ |
|
$Person.address.locality |
personRecord/person/address/[addressType/instanceValue/text="Preferred"]addressPart /nameValuePair /[instanceName/text="Locality"]/instanceValue/text |
|
$Person.address.statepr |
personRecord/person/address/[addressType/instanceValue/text="Preferred "]addressPart /nameValuePair /[instanceName/text="Statepr"]/instanceValue/text |
|
$Person.address.country |
personRecord/person/address/[addressType/instanceValue/text="Preferred"]addressPart /nameValuePair /[instanceName/text="Country"]/instanceValue/text |
|
$Person.address.postcode |
personRecord/person/address/[addressType/instanceValue/text="Preferred"]addressPart /nameValuePair /[instanceName/text="Postcode"]/instanceValue/text |
|
$Person.address.timezone |
personRecord/person/address/[addressType/instanceValue/text="Preferred"]addressPart /nameValuePair /[instanceName/text="Timezone"]/instanceValue/text |
|
$Person.phone.mobile |
personRecord/person/contactinfo[contactinfoType/instanceValue/text="Mobile"] /contactInfoValue/text |
|
$Person.phone.primary |
personRecord/person/contactinfo [contactinfoType/instanceValue/text="Telephone_Primary"]/contactinfoValue /text |
|
$Person.phone.home |
personRecord/person/contactinfo [contactinfoType/instanceValue/text="Telephone_Home"]/contactinfoValue /text |
|
$Person.phone.work |
personRecord/person/contactinfo [contactinfoType/instanceValue/text="Telephone_Work"]/contactinfoValue /text |
|
$Person.email.primary |
personRecord/person/contactinfo [contactinfoType/instanceValue/text="Email_Primary"] /contactinfoValue /text |
|
$Person.email.personal |
person/contactinfo[contactinfoType/instanceValue/text="Email_Personal"] /contactinfoValue /text |
|
$Person.webaddress |
personRecord/person/contactinfo[contactinfoType/instanceValue/text="Web‑Address"] /contactinfoValue/text |
|
$Person.sms |
personRecord/person/contactinfo[contactinfoType/instanceValue/text="SMS"] /contactinfoValue/text |
C.3 LIS Course Template Variables
|
Message Variable Name |
XPath for value from LIS Database |
|
$CourseTemplate.sourcedId |
courseTemplateRecord/sourcedId |
|
$CourseTemplate.label |
courseTemplateRecord/courseTemplate/label/textString |
|
$CourseTemplate.title |
courseTemplateRecord/courseTemplate/title/textString |
|
$CourseTemplate.shortDescription |
courseTemplateRecord/courseTemplate/catalogDescription/shortDescription |
|
$CourseTemplate.longDescription |
courseTemplateRecord/courseTemplate/catalogDescription/longDescription |
|
$CourseTemplate.courseNumber |
courseTemplateRecord/courseTemplate/courseNumber/textString |
|
$CourseTemplate.credits |
courseTemplateRecord/courseTemplate/defaultCredits/textString |
C.4 LIS Course Offering Variables
|
Message Variable Name |
XPath for value from LIS Database |
|
$CourseOffering.sourcedId |
courseOfferingRecord/sourcedId |
|
$CourseOffering.label |
courseOfferingRecord/courseOffering/label |
|
$CourseOffering.title |
courseOfferingRecord/courseOffering/title |
|
$CourseOffering.shortDescription |
courseOfferingRecord/courseOffering/catalogDescription/shortDescription |
|
$CourseOffering.longDescription |
courseOfferingRecord/courseOffering/catalogDescription/longDescription |
|
$CourseOffering.courseNumber |
courseOfferingRecord/courseOffering/courseNumber/textString |
|
$CourseOffering.credits |
courseOfferingRecord/courseOffering/defaultCredits/textString |
|
$CourseOffering.academicSession |
courseOfferingRecord/courseOffering/defaultCredits/textString |
C.5 LIS Course Section Variables
|
Message Variable Name |
XPath for value from LIS Database |
|
$CourseSection.sourcedId |
courseSection/sourcedId |
|
$CourseSection.label |
courseSectionRecord/courseSection/label |
|
$CourseSection.title |
courseSectionRecord/courseSection/title |
|
$CourseSection.shortDescription |
courseSectionRecord/courseSection/catalogDescription/shortDescription |
|
$CourseSection.longDescription |
courseSectionRecord/courseSection/catalogDescription/longDescription |
|
$CourseSection.courseNumber |
courseSectionRecord/courseSection/courseNumber/textString |
|
$CourseSection.credits |
courseSectionRecord/courseSection/defaultCredits/textString |
|
$CourseSection.maxNumberofStudents |
courseSectionRecord/courseSection/maxNumberofStudents |
|
$CourseSection.numberofStudents |
courseSectionRecord/courseSection/numberofStudents |
|
$CourseSection.dept |
courseSectionRecord/courseSection/org[type/textString="Dept"] /orgName/textString |
|
$CourseSection.timeFrame.begin |
courseSectionRecord/courseSection/timeFrame/begin |
|
$CourseSection.timeFrame.end |
courseSectionRecord/courseSection/timeFrame/end |
|
$CourseSection.enrollControl.accept |
courseSectionRecord/courseSection/enrollControl/enrollAccept |
|
$CourseSection.enrollControl.allowed |
courseSectionRecord/courseSection/enrollControl/enrollAllowed |
|
$CourseSection.dataSource |
courseSectionRecord/courseSection/dataSource |
|
$CourseSection.sourceSectionId |
createCourseSectionFromCourseSectionRequest/sourcedId |
C.6 LIS Group Variables
|
Message Variable Name |
XPath for value from LIS Database |
|
$Group.sourcedId |
groupRecord/sourcedId |
|
$Group.grouptype.scheme |
groupRecord/group/groupType/scheme/textString |
|
$Group.grouptype.typevalue |
groupRecord/group/groupType/typevalue/textString |
|
$Group.grouptype.level |
groupRecord/group/groupType/typevalue/level/textString |
|
$Group.email |
groupRecord/group/email |
|
$Group.url |
groupRecord/group/url |
|
$Group.timeFrame.begin |
groupRecord/group/timeframe/begin |
|
$Group.timeFrame.end |
groupRecord/group/timeframe/end |
|
$Group.enrollControl.accept |
groupRecord/group/enrollControl/enrollAccept |
|
$Group.enrollControl.allowed |
groupRecord/group/enrollControl/enrollAllowed |
|
$Group.shortDescription |
groupRecord/group/description/shortDescription |
|
$Group.longDescription |
groupRecord/group/description/longDescription |
|
$Group.parentId |
groupRecord/group/relationship[relation="Parent"]/sourcedId |
C.7 LIS Membership Variables
|
Message Variable Name |
XPath for value from LIS Database |
|
$Membership.sourcedId |
membershipRecord/sourcedId |
|
$Membership.collectionSourcedId |
membershipRecord/membership/collectionSourcedId |
|
$Membership.personSourcedId |
membershipRecord/membership/member/personSourcedId |
|
$Membership.status |
membershipRecord/membership/member/role/status |
|
$Membership.role |
membershipRecord/membership/member/role/roleType |
|
$Membership.createdTimestamp |
membershipRecord/membership/member/role/dataTime |
|
$Membership.dataSource |
membershipRecord/membership/member/role/dataSource |
C.8 LTI LineItem Variables
|
$LineItem.sourcedId |
lineItemRecord/sourcedId |
|
$LineItem.type |
lineItemRecord/lineItem/lineItemType |
|
$LineItem.type.displayName |
lineItemTypeRecord/lineItemType/displayName |
|
$LineItem.resultValue.max |
resultValueRecord/resultValue/valueRange/max where resultValueRecord.sourcedId = lineItemRecord/lineItem/resultValueSourcedId |
|
$LineItem.resultValue.list |
resultValueRecord/resultValue/valueList/orderValue where resultValueRecord.sourcedId = lineItemRecord/lineItem/resultValueSourcedId |
|
$LineItem.dataSource |
lineItemRecord/lineItem/dataSource |
C.9 LIS Result Variables
|
$Result.sourcedId |
resultRecord/sourcedId |
|
$Result.createdTimestamp |
resultRecord/result/date |
|
$Result.status |
resultRecord/result/statusofResult |
|
$Result.resultScore |
resultRecord/result/resultScore/textString |
|
$Result.dataSource |
resultRecord/result/dataSource |
|
$Result.uri |
Note: this does not have an equivalent definition in LIS. It represents the URI of the result resource suitable for updating the result using the REST service decscribed in section 8.2. |
C.10 Custom Variables
Third parties may define custom variables. For example, a Tool Consumer may wish to provide access to certain values that are specific to the Tool Consumer’s platform. Custom variable names must be globally unique. By convention, the name of a custom variable should start with a registered domain name, where the components of the domain are listed in reverse order. Thus, we might have a variable named,
$com.example.Foo.bar
where example.com is a registered domain name.
Every variable is associated with a capability which is identified by some URI. The capability asserts that the Tool Consumer supports expansion of the specified variable within LTI message parameters. For example, the capability associated with the custom variable listed above might be given by
http://www.example.com/var#com.example.Foo.bar
When a Tool Consumer advertises the capability to expand a custom variable, the fully qualified URI should be listed in the set of capabilities offered within the Tool Consumer Profile, as shown in Figure C.1.
Figure C.1 Capability for a custom variable declared in Tool Consumer Profile.
Appendix D – Deprecated Parameter Names
LTI 1.0 defined a long list of standard parameters for an LTI launch request. All of these parameter names are still supported in LTI 1.2, but many of them are now deprecated. The preferred method for handling these parameters in LTI 1.2 is to use custom parameters with variable substitution as described in Section 4.2.
If an LTI Link is associated with a Tool Proxy, then it is clear that the link was constructed in accordance with the rules for LTI 1.2 (with “custom_” as a prefix). In this case, the Tool Consumer should not use any of the deprecated parameter names. On the other hand, if an LTI link is NOT associated with a Tool Proxy, then during a transitional period, the Tool Consumer should list the parameter in the launch request twice – once using the deprecated name (without the “custom_” prefix) and again with the prefix.
The following list enumerates the parameters from LTI 1.0 that are deprecated in LTI 1.2.
context_title=Design of Personal
Environments
(Deprecated. Use
custom_context_title)
A title of the context
– it should be about the length of a line.
context_label=SI182
(Deprecated. Use
custom_context_label)
A label for the context
– intended to fit in a column. This parameter is
recommended.
resource_link_title=My Weekly Wiki
(Deprecated. Use
custom_resource_link_title)
A title for the
resource. This is the clickable text that appears in the
link.
resource_link_description=…
(Deprecated. Use
custom_resource_link_description)
A plain text
description of the link’s destination, suitable for display
alongside the link. Typically no more than several lines
long.
lis_person_name_given=Jane
(Deprecated. Use
custom_lis_person_name_given)
lis_person_name_family=Public
(Deprecated. Use
custom_lis_person_name_family)
lis_person_name_full=Jane Q.
Public
(Deprecated. Use
custom_lis_person_name_full)
lis_person_contact_email_primary=user@school.edu
(Deprecated. Use
custom_lis_person_contact_email_primary)
These
fields contain information about the user account that is
performing this launch. The names of these data items are taken
from LIS. The precise meaning of the content in these fields is
defined by LIS.
user_image=http://....
(Deprecated. Use
custom_user_image)
This attribute specifies the
URI for an image of the user who launched this request. This
image is suitable for use as a "profile picture" or an avatar
representing the user.
lis_person_sourcedid=school.edu:user
(Deprecated. Use
custom_list_person_sourcedid)
This field
contains the LIS identifier for the user account that is
performing this launch. The example syntax of "school:user" is
not the required format – lis_person_sourcedid is
simply a globally unique identifier (i.e., a normalized string).
This field is optional and its content and meaning are defined by
LIS.
lis_course_offering_sourcedid=school.edu:SI182-F08 (Deprecated. Use custom_lis_course_offering_sourcedid)
lis_course_section_sourcedid=school.edu:SI182-001-F08
(Deprecated. Use custom_lis_course_section_sourcedid)
These fields contain LIS course identifiers associated with the context of this launch. These fields are optional and their content and meaning are defined by LIS.
tool_consumer_instance_name=SchoolU
(Deprecated. Use
custom_tool_consumer_instance_name)
This is a
user visible field – it should be about the length of a
column.
tool_consumer_instance_description=University of School
(Deprecated. Use
custom_tool_consumer_instance_description)
This
is a user visible field – it should be about the length of
a line.
tool_consumer_instance_url=http://lmsng.school.edu
(Deprecated. Use
custom_tool_consumer_instance_url)
This is the
URL of the consumer instance.
tool_consumer_instance_contact_email=System.Admin@school.edu
(Deprecated. Use
custom_tool_consumer_instance_contact_email)
An
email contact for the Tool Consumer’s service provider.
Appendix E – Developer Cookbooks
E.1 Outcomes Reporting Cookbook
E.1.1 Tool Consumer Requirements for Outcomes Reporting
|
Requirement |
Reference |
|
1. Publish a Tool Consumer Profile at some URL. See Figure E.1 for an example of a Tool Consumer Profile that supports outcomes reporting. |
Section 5.2 |
|
2. User Interface to Request Access to a Tool. Implement a user interface which allows the Tool Consumer Administrator to request access to an LTI Tool. This interface accepts a URL from the Administrator and then posts a ToolProxyRegistrationRequest to the specified URL. |
Section 6.1 |
|
3. Tool Proxy Service. Implement the POST method of the Tool Proxy Service. This method allows the Tool Provider to register a new Tool Proxy with the Tool Consumer. |
Section 10.1 |
|
4. User Interface to Make Tool Proxy Available. Implement a user interface which allows the Tool Consumer Administrator to make a newly registered Tool Proxy available. |
Section 6.4 |
|
5. Link Authoring. Implement a user interface which allows Content Builders to create LTI Links that are associated with a Resource Type. |
Section 7.1 |
|
6. Tool Launch Service. Implement a service that can launch a Tool from an LTI Link. |
Section 4.7 |
|
7. Result Auto-create Capability. The Tool Launch Service must include support for the Result.autocreate capability. |
Section 5.3.3 |
|
8. LIS Result Service. Implement PUT method of the LIS Result Service |
Section 10.2 |
|
<? xml version="1.0" encoding="UTF-8"?> < tool_consumer_profile lti_version="LTI-1p1" xmlns="http://www.imsglobal.org/lti/v1/schema#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" > < product_instance guid="LMS3.someuniversity.edu"> < product_info> < product_name> Alpha LMS</ product_name> < version> 1.0</ version> < product_family code="alpha"> < vendor code="LMSVendor.com"> < timestamp> 2011-10-01T12:00:00</ timestamp> < name> LMS Vendor</ name> </ vendor> </ product_family> </ product_info> </ product_instance> < service_offered> < contract rdf:resource="http://www.imsglobal.org/imspurl/lti/v1/service#ToolProxy" /> < method name="POST"/> < endpoint_url> http://lms3.someuniversity.com/services/</ endpoint_url> </ service_offered> < service_offered> < contract rdf:resource="http://www.imsglobal.org/imspurl/lis/v1/service#ResultService" /> < method name="PUT"/> < endpoint_url> http://lms3.someuniversity.com/services/</ endpoint_url> </ service_offered> < capability rdf:resource="http://www.imsglobal.org/imspurl/lti/v1/message#basic-lti-launch-request" /> < capability rdf:resource="http://www.imsglobal.org/imspurl/lti/v1/variable#Result.sourcedId" /> < capability rdf:resource="http://www.imsglobal.org/imspurl/lti/v1/capability#Result.autocreate" /> </ tool_consumer_profile>
|
Figure E.1 Profile for a Tool Consumer that support Outcomes Reporting
E.1.2 Tool Provider Requirements for Outcomes Reporting
|
Requirement |
Reference |
|
1. Message Handler for Tool Proxy Registration Request. Implement a message handler that can receive a Tool Proxy Registration Request. The handler should perform the following actions. |
Section 2.4 |
|
a. Tool Profile. Construct a Tool Profile that describes the Tool that will be reporting assessment results to the Tool Consumer. |
Section 3.4 |
|
i. Enable Result autocreate capability. The Tool Profile must contain at least one Resource Handler that enables the Result.autocreate capability. |
Section 3.4.4 |
|
ii. Custom Parameter for Result GUID. The Resource Handler(s) must declare a custom parameter whose value is given by the $Result.sourcedId variable. |
Section 3.4.3 |
|
b. Security Contract. Define the Security Contract for the integration with the Tool Consumer. This contract enumerates the service methods that the Tool intends to use and it also encapsulates a shared secret that will be used for future interactions. The Security Contract must include the PUT method of Result Service. |
Section 3.5 |
|
c. Tool Proxy. Construct a Tool Proxy that aggregates the Tool Profile and Security Contract. See Figure E.2 for an example of a Tool Proxy that supports outcomes reporting. |
Chapter 3 |
|
d. Register the Tool Proxy. Register the Tool Proxy with the Tool Consumer by issuing a POST request to Tool Consumer’s Tool Proxy Service. |
Section 11.1.1 |
|
e. Return control to the Tool Consumer. Redirect the user’s browser back to the Tool Consumer at the launch_presentation_return_url specified in the ToolProxyRegistrationRequest. |
Section 5.4 |
|
2. Message Handler for Tool Launch Request. Implement a message handler that receives a basic-lti-launch-request. This handler must be prepared to receive the GUID for a Result object so that the Tool can later report a score using this GUID. The parameter that holds the Result GUID is defined in the Tool Profile (see Requirement 1.a.ii above.) |
Section 2.3 |
|
3. Report Score to the Tool Consumer. After the Learner has completed the assignment, the Tool should report a score by issuing a PUT request to the Tool Consumer’s Result Service. |
Section 6.1.3 |
|
{ "@context" : [ "http://www.imsglobal.org/imspurl/lti/v2/ctx/ToolProxy" , "http://purl.org/blackboard/ctx/v1/iconStyle" ], "@type" : "ToolProxy" , "@id" : "http://lms.example.com/ToolProxy/869e5ce5-214c-4e85-86c6-b99e8458a592" , "lti_version" : "LTI-2p0" , ... "resource_handler" : [ { "resource_type" : { "code" : "asmt" }, "name" : {"default_value" : "Acme Assessment"}, "description" : {"default_value" : "An interactive assessment using the Acme scale."}, "message" : [{ "message_type" : "basic-lti-launch-request" , "path" : "/handler/launchRequest" , "enabled_capability" : [ "Result.autocreate" ], "parameter" : [ { "name" : "result_uri", "variable" : "$Result.uri" }, { "name" : "discipline" , "fixed" : "chemistry" } ] }], ... } ] }, "security_contract" : { "shared_secret" : "ThisIsASecret!" , "tool_service" : [ { "@type" : "RestServiceProfile", "service" : "http://lms.example.com/profile/b6ffa601-ce1d-4549-9ccf-145670a964d4#Result.item", "action" : ["GET", "PUT"] } ] } }
|
Figure E.2 Tool Proxy that supports Outcomes Reporting
Appendix F – JSON-LD
The IMS LTI standard adopts some conventions from the emerging W3C JSON-LD syntax specification which, as of October 2012, is in Working Draft status [JSON, 12]. JSON-LD is a specification for representing Linked Data in JSON. Within the IMS LTI standard, JSON-LD provides:
- A consistent way to identify resources through the @id property.
- A consistent way to describe resource types through the @type property.
- A formal way to describe the semantics of a JSON document through the @context property.
- An opportunity to implement data validation.
- A framework for defining data extensions.
- A method for URL shortening which results in more compact and more readable payloads.
- Alignment with W3C Semantic Web standards
The typical web developer does not need to understand all the nuances of JSON-LD syntax. Indeed, it is possible to treat JSON-LD keywords (@id, @type, @context) as plain-old JSON properties that happen to have somewhat peculiar names which start with the '@' symbol.
The @id property is used to identify resources. Its value is a URL (or more generally an IRI) for the resource. As a best practice, the URL should be dereferencable. That is to say, the URL should point to a representation of the resource on the web. Ideally, the representation will be another JSON-LD document (or a fragment of another JSON-LD document).
The @type property is used to identify a resource's type. For example, the JSON-LD representation of a Tool Proxy starts with the following lines:
|
{ "@context" : "http://www.imsglobal.org/imspurl/lti/v2/ctx/ToolProxy" , "@type" : "ToolProxy" , "lti_version" : "LTI-2p0" , ... }
|
Figure F.1 The beginning of a JSON-LD document
In this example, the type is identified by the simple name “ToolProxy.” The LTI standard uses RDF, the Resource Description Framework, to describe classes and properties. In the example above, the simple name “ToolProxy” maps to a fully-qualified URI for the corresponding class in an RDF schema. This mapping is provided by the JSON-LD context. In the example above, the JSON-LD context can be accessed at http://www.imsglobal.org/imspurl/lti/v2/ctx/ToolProxy. The JSON-LD context defines mappings like this:
|
{ "lti" : "http://www.imsglobal.org/imspurl/lti/v2/vocab/lti#" , "ToolProxy" : "lti:ToolProxy" , ... }
|
Figure F.2 A fragment of a JSON-LD Context
In this example, the simple name “ToolProxy” maps to the fully qualified URI
http://www.imsglobal.org/imspurl/lti/v2/vocab/lti#ToolProxy
The precise meaning of terms that appear in the JSON-LD document is established through this kind of mapping to terms in RDF schemas. The JSON-LD context effectively forms a data contract. It specifies what properties may appear in the JSON document and through the associated RDF schemas it specifies additional constraints such as cardinality constraints.
Developers can build LTI compliant applications without any knowledge of RDF. The JSON binding specifications for LTI resources provide all the details about what names to use for various properties and how to structure compliant JSON representations. However, it is important to have a basic understanding of the syntax for a JSON-LD context.
Usually, the “@context” property takes a single URI string for its value as illustrated in Figure F.1. However, it is permissible to define more than one JSON-LD context and put them all into an array as shown below:
|
{ "@context" : [ "http://www.imsglobal.org/imspurl/lti/v2/ctx/ToolProxy" , "http://example.com/json-ld/ExtraContext" ], ... }
|
In this way, it is possible to extend the data contract by introducing mappings for additional terms in an extra JSON-LD contract. The use of extensions is discouraged because it limits interoperability. A conforming LTI application may silently ignore extension properties, but it must not fail simply because extension properties are present.
It is also possible to put the definition of a JSON-LD context inline instead of providing a URI reference. An inline JSON-LD context is especially useful when defining prefixes which enable the use of compact URI (CURIE) values within the JSON document. Figure F.3 shows a JSON-LD document with an inline context.
|
{ "@context" : [ "http://www.imsglobal.org/imspurl/lti/v2/ctx/ToolProxy" , { "tcp" : "http://lms.example.com/profile/b6ffa601-ce1d-4549-9ccf-145670a964d4#" } ], ... "security_contract" : { "shared_secret" : "ThisIsASecret!" , "tool_service" : [ { "@type" : "RestServiceProfile" , "service" : "tcp:Result.item" , "action" : ["GET" , "PUT" ] } ] } }
|
Figure F.3 A JSON-LD document with an inline context
In this example, the inline JSON-LD context defines a prefix named “tcp” which expands to the URI for a Tool Consumer Profile. That prefix can then be used later in the JSON document. Thus, the compact URI “tcp:Result.item” expands to the fully qualified URI
http://lms.example.com/profile/b6ffa601-ce1d-4549-9ccf-145670a964d4#Result.item
About This Document
Title: IMS Learning Tools Interoperability Implementation Guide
Co-chairs: Greg McFall (Pearson), Lance Neumann (Blackboard)
Editor: Greg McFall (Pearson), Lance Neumann (Blackboard), Stephen Vickers (IMS Global)
Version: v1.0
Version Date: 1 November 2012
Release: v2.0
Status: Public Draft
Purpose: This document is made available for review and comment by the public community at large.
Document Location: Join the discussion and post comments on the LTI Public Forum: http://www.imsglobal.org/community/forum/categories.cfm?catid=44
10.3 List of Contributors
The following individuals contributed to the
authoring of this document:
|
Craig Dunk |
Desire2learn |
Colin Smythe |
IMS Global |
|
Greg McFall |
Pearson |
Matt Stoelting |
Cengage |
|
Mark McKell |
IMS Global |
John Tibbetts |
VitalSource |
|
Lance Neumann |
Blackboard |
Stephen Vickers |
IMS Global |
|
Charles Severance |
University of Michigan |
|
|
Revision History
|
Version No. |
Release Date |
Comments |
|
Base Document v1.0 |
27 July 2009 |
The first formal release of the Base Document. This document is released for review by the IMS LTI Workgroup. |
|
Internal Draft |
30 October 2009 |
The first formal release of the Internal Draft document. This document is released for interoperability implementation by the IMS Members and Affiliates. |
|
Public Draft v1.0 |
15 February 2010 |
The first formal release of the Public Draft. This document is released for interoperability adoption by the community at large. |
|
Final v1.0 |
17 May 2010 |
The first formal release of the Final specification. This document is released for public adoption. |
|
Final v1.1 |
13 March 2012 |
Added the tool registration and grade return use cases. |
|
Public Draft v2.0 |
1 November 2012 |
Implements a new model that specifies services using REST APIs in JSON format. |
IMS Global Learning Consortium, Inc. (“IMS Global”) is publishing the information contained in this IMS Global Learning Tools Interoperability Implementation Guide(“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 Implementation Guide v2.0 Public
Draft
Revision: 1 November 2012