IMS Final Release

IMS Learning Tools Interoperability™ (LTI) Tool Management

Version 2.0 Final Specification

Date Issued: 6 January 2014
Latest version: http://www.imsglobal.org/lti/

IPR and Distribution Notices

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.

IMS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on IMS's procedures with respect to rights in IMS specifications can be found at the IMS Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.

Copyright © 2014 IMS Global Learning Consortium. All Rights Reserved.

Use of this specification to develop products or services is governed by the license with IMS found on the IMS website: http://www.imsglobal.org/license.html.

Permission is granted to all parties to use excerpts from this document as needed in producing requests for proposals.

The limited permissions granted above are perpetual and will not be revoked by IMS or its successors or assigns.

THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.

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

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

The IMS Logo and Learning Tools Interoperability (LTI) are trademarks of the IMS Global
Learning Consortium, Inc. in the United States and/or other countries.
Document Name: IMS Global Learning Tools Interoperability Tool Management v2.0 Final
Revision: 6 January 2014

# Table of Contents

1 Overview... 4

1.1 Nomenclature .. 4

1.2 LTI Management Activities . 4

1.3 Structure of this Document .. 4

1.4 References . 4

2 Overview of Tool Management Use Cases . 6

2.1 Tool Proxy Use Case Overview ... 6

2.2 Overview of Use Cases for Links without a Tool Proxy .. 7

3 Component Model.. 8

4 Tool Management Use Cases. 10

4.1 Tool Proxy Use Cases . 10

4.1.1 Basic Tool Proxy Deployment 10

4.1.2 Deployment initiated via Tool Proxy Request Form.. 13

4.1.3 Making a Tool Proxy Available. 15

4.1.4 Making a Tool Proxy Unavailable. 15

4.1.5 Enabling a Tool Proxy in a Learning Context 16

4.1.6 Disable a Tool Proxy in a Learning Context 17

4.1.7 Removing a Tool Proxy from a Learning Context 17

4.1.8 Removing a Tool Proxy from a Tool Consumer . 20

4.2 Use Cases for Links without a Tool Proxy .. 20

4.2.1 Setting TP Domain Credentials (Basic LTI) 21

4.2.2 Setting Link Level Credentials (Basic LTI) 21

4.2.3 Managing Credentials for Basic LTI Links Imported from a Cartridge. 22

5 Information Model.. 23

5.1 Tool Management Messaging Schema .. 23

5.1.1 ToolProxyRegistrationRequest Class. 23

5.1.2 RegistrationMixin Class. 24

5.1.3 RegistrationStatus Enumeration. 26

5.2 Mixin Types . 27

5.2.1 CoreMessageMixin Class. 27

5.2.2 LTIToolProxyMixin Class. 28

5.2.3 LaunchMixin Class. 29

5.2.4 ContextMixin Class. 30

5.3 Messaging Data Types . 31

5.3.1 LaunchPresentation Class. 31

5.3.2 DocumentTarget Enumeration. 33

About This Document.. 35

5.4 List of Contributors . 35

Revision History.. 36

# 1 Overview

This specification describes the activities related to the management of Tool Proxies within a Tool Consumer system.

## 1.1 Nomenclature

This specification assumes that the reader is familiar with the following terms which are defined in the LTI Implementation Guide document [LTI, 14 IMG].

- Tool Consumer
- Tool Provider
- Tool Proxy
- Tool Proxy Binding

## 1.2 LTI Management Activities

- Adding a new Tool Proxy to the Tool Consumer system.
- Making a Tool Proxy “available” within the Tool Consumer system.
- Making a Tool Proxy “unavailable” within the Tool Consumer system.
- Enabling or disabling a Tool Proxy within a given learning context such as a course.
- Removing a Tool Proxy from the Tool Consumer.

- Setting Security Credentials for Basic LTI links
- Importing LTI Links from a Cartridge

## 1.3 Structure of this Document

The structure of this document is:

2 Overview of Tool Management Use Cases | Description of use cases included in the LTI 2 specification
3. Component Model | Description of the various components used in LTI 2
4. Tool Management Use Cases | Descriptions of each of the LTI 2 use cases
5. Information Model | Description of the classes and schemas for the LTI information model

## 1.4 References

[BLTI, 10 IMG] C.Severance, IMS Global Learning Tools Interoperability Basic LTI Implementation Guide v1.0, IMS Global Learning Consortium, May 2010. http://www.imsglobal.org/lti/index.html.

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

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

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

# 2 Overview of Tool Management Use Cases

## 2.1 Tool Proxy Use Case Overview

Figure 2.1 Full LTI Use Cases.

There are two primary use cases that result in the deployment of a Tool Proxy within the Tool Consumer. These use cases are:

· Deployment initiated via the Tool Proxy Request Form

· Deployment initiated as a result of importing a course archive.

Both of these scenarios extend the Basic Tool Proxy Deployment Process.

Once a Tool Consumer Administrator has deployed a Tool Proxy, the administrator may make it available or unavailable for use within the Tool Consumer system. The administrator may also remove it from the system entirely.

Before a Tool Proxy can be used within a learning context (such as a course), it must be bound to the context and configured.

Section 4 provides a detailed discussion of these use cases.

## 2.2 Overview of Use Cases for Links without a Tool Proxy

Figure 2.2 Basic LTI Use Cases.

There are two different mechanisms for securing LTI links without a Tool Proxy. Either the TC Administrator can set credentials for all LTI links associated with a given Tool Provider domain, or Instructors can set credentials for each individual link.

These security related activities are an important part of the use case for importing LTI links from a Common Cartridge.

Section 4.2 provides a detailed discussion of these use cases.

# 3 Component Model

Figure 3.1 Component Model for Tool Proxy Deployment.

Figure 3.1 presents a ball-and-cup model that illustrates the interfaces exposed by the Tool Consumer and Tool Provider in support of the Tool Management activities. Each ball corresponds to an interface. A straight line connector identifies the component that implements the interface. A connector ending in a cup identifies the component that uses the interface. These interfaces are described below.

Tool Proxy Request Form: This web-based, user interface allows an administrator to initiate the process of deploying a new Tool Proxy into the Tool Consumer. Via this interface, the administrator launches the Tool Provider's Deployment UI.

Deployment UI: This web-based, user interface allows administrators to request that the Tool Provider register a particular Tool Proxy with the Tool Consumer. The IMS LTI standard defines a mechanism for launching this user interface from the Tool Consumer, but it does not prescribe the detailed interactions that occur within the interface. For example, the standard does not define a mechanism for the administrator to authenticate himself or herself to the Tool Provider. Nor does it prescribe a method for the administrator to pay for access to the Tool if payment is required.

Tool Consumer Profile Accessor: This interface allows the Tool Provider to obtain the Tool Consumer Profile, which defines the capabilities of and services offered by the Tool Consumer.

Registration Service: This interface allows the Tool Provider to register a Tool Proxy with the Tool Consumer. The Tool Provider uses this interface in response to requests from administrators interacting with the Deployment UI.

Tool Console: This user interface allows the Tool Consumer Administrator to manage the Tool Proxies that have been registered with the Tool Consumer system. This interface has the following features:

- Provides access to the Tool Proxy Request Form so that the administrator can add new Tool Proxies to the Tool Consumer system.

- Allows the administrator browse or search for Tool Proxies that are currently registered with the Tool consumer.
- Allows the administrator to change the state of any registered Tool Proxy, making it available or unavailable.
- Allows the administrator to update a Tool Proxy to a new version.
- Allows the administrator to upgrade Tool Proxy Bindings.

Cartridge Import Service: This interface provides a way to import content into the Tool Consumer from an IMS Common Cartridge. If the cartridge contains a Tool Proxy Locator, then the import process may trigger the deployment process for that Tool Proxy, as described in Use Case LTIv1-03.

State Change Notification Handler: The Tool Provider exposes this interface to receive notifications from the Tool Consumer when the state of the Tool Proxy changes.

Binding UI: This user interface allows an Instructor or Course Builder to manage Tool Proxy Bindings associated with a learning context such as a course section. With this interface, the user can add tools to the learning context, temporarily disable tools, or remove them from the learning context altogether.

# 4 Tool Management Use Cases

## 4.1 Tool Proxy Use Cases

### 4.1.1 Basic Tool Proxy Deployment

Figure 4.1 Flow chart for basic tool proxy deployment.

Use Case Title: | Deploying a Tool Proxy within a Tool Consumer
Use Case Local ID: | LTIv1-01
Brief Description: | This use case describes the basic steps involved in the deployment of a Tool Proxy within a Tool Consumer.
Level: | Summary
Actors: | TC Administrator, Tool Provider system, Tool Consumer system
Preconditions: | There are three different ways to initiate this workflow: By submitting the Tool Proxy Request form (see Use Case LTIv1-02) By participating in the workflow for importing an archive that contains a Tool Proxy Locator (see Use Case LTIv1-03), or By choosing to deploy a new version of a Tool Proxy that is already registered with the Tool Consumer (see Use Case LTIv1-11). In all three cases, the workflow starts with the TC Administrator interacting with a user interface in the Tool Consumer system. This use case picks up immediately after that initial interaction.
Basic Flow of Events: | 1. Launch Deployment UI. The TC Administrator’s browser (a.k.a. User Agent ) sends a ToolProxyRegistrationRequest to the Tool Provider’s Deployment URL, and hence the browser navigates into the Deployment UI within the Tool Provider system. The ToolProxyRegistrationRequest is sent to the Tool Provider via the automatic submission of an HTML form, as described in the LTI Messaging Framework specification [LTI, 14 MSF]. 2. Get Tool Consumer Profile. Among other things, the ToolProxyRegistrationRequest includes the URL for accessing the Tool Consumer Profile. The Tool Provider obtains the Tool Consumer Profile from this URL by appending the lti_version query parameter to the URL and submitting an HTTP GET request. The Tool Consumer will return the JSON representation of the Tool Consumer Profile in the response using the “application/vnd.ims.lti.v2.ToolConsumerProfile+json” media type. 3. Interact with Administrator. The Tool Provider interacts with the administrator. The LTI standard does not define the details of this step. Here are some typical interactions that may occur within the Deployment UI: Tool Provider requires the administrator to authenticate himself or herself by submitting an access code that was received out of band. Tool Provider requires the administrator to enter a Customer ID. Tool Provider requires the administrator to select the particular Tool that is to be deployed. Tool Provider allows the administrator to choose the set of tool features that should be enabled[1]. Tool Provider displays to the administrator the data access requirements of the Tool, based on the selected feature set.[2] Tool Provider requires the administrator to submit payment for the selected Tool. 4. Submit. When all the interactions are complete, the administrator makes a final submission to the Tool Provider. 5. Validate the Tool Consumer Profile. The Tool Provider examines the Tool Consumer Profile that was obtained in Step 2 and confirms that the capabilities and services offered by the Tool Consumer are compatible with the needs of the Tool. 6. Register the Tool Proxy. The Tool Provider constructs a Tool Proxy and submits it to the appropriate REST endpoint within the Tool Consumer. The Tool Provider discovers this endpoint by inspecting the Tool Consumer Profile. This operation allows the Tool Provider to convey the following information to the Tool Consumer: a. Tool Profile b. Shared Secret that will be used to secure subsequent communications between the two systems c. Set of services and operations which the Tool Provider requires. Typically, this will be a subset of the collection of all services offered by the Tool Consumer as declared in the Tool Consumer profile. d. A list of TC capabilities that the TP wishes to utilize. At this point, the Tool Proxy is registered with the Tool Consumer, but it is not enabled. 7. Redirect back to the Tool Consumer . The Tool Provider redirects the User Agent back to the Tool Consumer system at the URL specified by the launch_presentation_return_url parameter posted with the ToolProxyRegistrationRequest. 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 given by the return value from the registerTool operation. 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 (see the next step). 8. Make Tool Proxy Available. Before the Tool Proxy can be used within the Tool Consumer, it must be placed into the “available” state, as described in Use Case LTIv1-04. The Tool Provider will not have access to any Tool Consumer services until such access has been authorized by the administrator when the tool is enabled.
Alternative Flows: | A. Customize Options based on Tool Consumer capabilities At Step 3, the Tool Provider may customize the interactions with the Administrator based on the capabilities announced in the Tool Consumer profile. For example, if the Tool Consumer does not offer a web service for pushing scores into its online gradebook, then the Tool Provider should not offer this feature as an option. B. Tool Consumer Profile validation fails. At Step 5, the Tool Provider may determine that the capabilities and services offered by the Tool Consumer are not sufficient to support the needs of the Tool. In this case, the following actions occur: Tool Provider displays an error message to the administrator explaining why Tool Proxy deployment cannot be completed. Administrator clicks some control (such as a button) within the Deployment UI to cancel the deployment process. The Tool Provider redirects the administrator's User Agent to the Registration Completion UI. The Tool Provider appends the parameter status=failure to the redirect URL. C. Custom URL for each Tool In some cases, the Tool Provider may define a different deployment URL for each type of Tool. In this case, there is no need for the administrator to select a tool at Step 3, and the Tool Provider may be able to validate the Tool Consumer Profile immediately after receiving it in Step 2. D. Query Parameters in the Deployment URL If the Deployment URL contains query parameters, the Tool Consumer parses these parameters and adds them as POST parameters in the HTML Form that represents the ToolProxyRegistrationRequest. The query parameters are stripped from the Deployment URL, and the resulting URL (without the query parameters) is used as the action attribute of the HTML Form that is auto-submitted in Step 2. E. Early Validation of Tool Consumer Profile The Basic Path indicates that the Tool Provider validates the Tool Consumer Profile immediately prior to submitting the Registration Request. However, the Tool Provider may choose to validate the Tool Consumer Profile at other points within the workflow. For example, the TP may validate the TC Profile upon receiving it at Step 2, and it may abort the entire process immediately if the TC does not offer some minimal set of capabilities and services. F. No interaction with TC Administrator In some cases, it may not be necessary for the Tool Provider system to interact with the TC administrator. For example, the Tool Provider might offer only one Tool with no configuration options. Or the details might be encoded in the Deployment URL as query parameters. Thus, in some cases it may be possible to skip Steps 3 and 4.
Postcondition: | The Tool Proxy is deployed to the Tool Consumer but not enabled.

### 4.1.2 Deployment initiated via Tool Proxy Request Form

Figure 4.2 Flow chart for deployment initiated via Tool Proxy Request Form.

Use Case Title: | Deploying a Tool Proxy via the Tool Proxy Request Form
Use Case Local ID: | LTIv1-02
Brief Description: | This use case extends the Basic Tool Proxy Deployment process by defining one way to initiate the deployment workflow. In this use case, an administrator initiates the deployment of a Tool Proxy by submitting the Tool Proxy Request Form.
Level: | Summary
Actors: | Tool Consumer Administrator, Tool Consumer system
Basic Flow of Events: | 1. Obtain Tool Deployment URL. The administrator obtains a Deployment URL from the Tool Provider. This is the URL that will be used to launch the Deployment UI. The LTI standard does not define how the administrator acquires the Deployment URL. It may be delivered via email, or by any other means. 2. Submit Tool Proxy Request Form. The Tool Consumer implements a Tool Proxy Request Form which contains an input field where the administrator can enter the Deployment URL. The administrator navigates to this form within the Tool Consumer, enters the Deployment URL, and submits the form. 3. Generate ToolProxyRegistrationRequest. The Tool Consumer responds to the submission of the Tool Proxy Request Form by generating a ToolProxyRegistrationRequest. In this use case, the vendor_code, tool_code, and tool_version attributes of the request are not defined. In accordance with the LTI Messaging Framework [LTI, 14 MSF], the ToolProxyRegistrationRequest is rendered as an HTML form and auto-submitted to the Tool Provider. The value for the action attribute of the form is given by the Deployment URL that was submitted in Step 2. Thus, when the form is auto-submitted, it will be posted to the Tool Provider at the Deployment URL. 4. Use Basic Tool Proxy Deployment Process. The remainder of this use case follows the Basic Tool Proxy Deployment sequence, see Section 4.1.1. Since the tool_code and tool_version are not defined in the ToolProxyRegistrationRequest, the Tool Provider will need to identify the particular Tool Proxy that is being requested by some other means. The Tool Provider may use either of the following methods: The Tool Provider may infer the Tool Proxy from the Deployment URL. In other words, the Tool Provider might use a different Deployment URL for each version of the Tool Proxy. Alternatively, the Tool Provider might require the administrator to choose a particular Tool Proxy as one of the activities that occurs within the Deployment UI. (See Step 3 of the Tool Proxy Deployment use case.)
Alternative Flows: | A. Customized Tool Consumer Profile At Step 2, the Tool Proxy Request Form may allow the TC Administrator to limit the set of services and capabilities that will be offered to the Tool Provider. In this case, the Tool Consumer generates a customized Tool Consumer Profile which advertises only the selected services and capabilities. In this case, the ToolProxyRegistrationRequest generated at Step 3 will contain the URL for the customized Tool Consumer Profile.

### 4.1.3 Making a Tool Proxy Available

Use Case Title: | Making a Tool Proxy Available
Use Case Local ID: | LTIv1-04
Brief Description: | Describes the sequence of events that occurs when an administrator makes a Tool Proxy available within the TC system.
Level: | Summary
Actors: | · Tool Consumer System Administrator · Tool Consumer Runtime · Tool Provider
Preconditions: | · Tool Proxy has been deployed to the Tool Consumer · Tool Proxy is initially in the unavailable state.
Basic Flow of Events: | 1. Request Tool Proxy state change. The Tool Consumer System Administrator navigates to the Tool Console in the Tool Consumer system, and he or she submits a request to change the state of the Tool Proxy to “available.” 2. Display Security Warning. The Tool Console displays a warning about the security implications of making the Tool Proxy available. For each type of business object (Person, Course Section, Membership, Grades, etc.), the Tool Console discloses the ways in which the Tool Provider system might manipulate these objects. As a general rule, the TC should not merely report the specific web service operations that the TP will be authorized to access since this information may not be meaningful to the typical administrator. Instead, for each type of business object, the Tool Console should disclose whether or not the Tool Provider will be able to create, read, update or delete that entity. These details are derived from the security contract. For example, suppose the security contract declared that the Tool requires access to the readPerson operation of the LIS Person Manager and all the operations of the LIS Result Manager. In this case, the Tool Console should warn the administrator that the Tool will be able to read directory information about users and will be able to read and write entries in the gradebook. This disclosure step is a best practice; it is not required for compliance with the LTI standard. 3. Persist Tool Proxy state in Tool Consumer. The change to the Tool Proxy state is persisted in the Tool Consumer system. Once the Tool Proxy is available, Instructors and Course Builders can enable the Tool Proxy in any course section within the Tool Consumer (see Use Case LTIv1-07).
Postcondition: | Tool Proxy is in the available state.

### 4.1.4 Making a Tool Proxy Unavailable

Use Case Title: | Making a Tool Proxy Unavailable
Use Case Local ID: | LTIv1-05
Brief Description: | Describes the sequence of events that occurs when an administrator makes a Tool Proxy unavailable within the TC system.
Level: | Summary
Actors: | · Tool Consumer System Administrator · Tool Consumer Runtime · Tool Provider
Preconditions: | · Tool Proxy has been deployed to the Tool Consumer · Tool Proxy is initially in the available state.
Basic Flow of Events: | 1. Request Tool Proxy state change. The Tool Consumer System Administrator navigates to the Tool Console in the Tool Consumer system, and he or she submits a request to change the state of the Tool Proxy to “unavailable.” 2. Persist Tool Proxy state in Tool Consumer. The change to the Tool Proxy state is persisted in the Tool Consumer system. At this point, instructors and course builders will no longer be able to add the Tool Proxy to new course sections within the Tool Consumer system. All existing Tool Proxy Bindings for this tool must behave as if they have been explicitly disabled as described in use case LTIv1-08.
Postcondition: | The Tool Proxy is in the unavailable state.

### 4.1.5 Enabling a Tool Proxy in a Learning Context

Use Case Title: | Enabling a Tool Proxy in a Learning Context
Use Case Local ID: | LTIv1-07
Brief Description: | Instructor or Course Builder enables a Tool Proxy in some learning context.
Level: | Summary
Actors: | · Instructor or Course Builder · Tool Consumer (TC)
Preconditions: | The Tool Proxy has been registered with the Tool Consumer.
Basic Flow of Events: | 1. View available Tools. Instructor or Course Builder navigates to the Binding UI within the learning context. From this interface, the user can browse or search for all available Tool Proxies. 2. Enable Selected Tool. Instructor or Course Builder chooses to enable a particular Tool Proxy within the Learning Context. The TC creates a Tool Proxy Binding that relates the selected Tool Proxy to the given learning context, and initializes the binding in the enabled state. 3. Display links. If the learning context contains resource links, then those links become active.
Alternative Flows: | A. Enable an existing Tool Proxy Binding that is disabled The Basic Flow treats the case where a new Tool Proxy Binding is created. This effectively adds a new Tool to the learning context. However, it is possible that the Tool Proxy was previously added to the learning context but was subsequently disabled. In that case, at Step 2 the Tool Proxy Binding is not re-created but instead its state is merely changed to enabled.
Postconditions: | · A Tool Proxy Binding has been created and is in the enabled state. · Tool Provider may access data associated with the learning context by invoking the relevant web services offered by the Tool Consumer.

### 4.1.6 Disable a Tool Proxy in a Learning Context

Use Case Title: | Disabling a Tool Proxy in a Learning Context
Use Case Local ID: | LTIv1-08
Brief Description: | Instructor or Course Builder disables a Tool Proxy in some learning context.
Level: | Summary
Actors: | · Instructor or Course Builder · Tool Consumer (TC)
Preconditions: | The Tool Proxy has been registered with the Tool Consumer.
Basic Flow of Events: | 1. View Enabled Tools. Instructor or Course Builder navigates to the Binding UI. From this interface, the user can browse or search for all enabled Tool Proxies within the current learning context. 2. Disable Selected Tool. Instructor or Course Builder chooses to disable a particular Tool Proxy within the learning context. The TC persists this change internally.
Postconditions: | · The Tool Proxy Binding state has been changed to disabled.

### 4.1.7 Removing a Tool Proxy from a Learning Context

Use Case Title: | Removing a Tool Proxy from a Learning Context
Use Case Local ID: | LTIv1-09
Brief Description: | Instructor or Course Builder removes a Tool Proxy from a given learning context.
Level: | Summary
Actors: | · Instructor or Course Builder · Tool Consumer Runtime (TC) · Tool Provider (TP)
Preconditions: | Tool Proxy Binding has been created to establish a relationship between some learning context and a given Tool Proxy
Basic Flow of Events: | 1. View Bound Tools. Instructor or Course Builder navigates to the Binding UI within some learning context. From this interface, the user can browse or search for all Tools that are bound to the learning context. 2. Remove Selected Tool. Instructor or Course Builder explicitly performs an action to remove a selected Tool from the learning context. TC deletes the Tool Proxy Binding and disables or hides resource links.
Postcondition: | · The Tool Proxy Binding has been removed from the learning context. · All resource links associated with the Tool Proxy have been hidden or disabled within the context.

### 4.1.8 Removing a Tool Proxy from a Tool Consumer

Use Case Title: | Removing a Tool Proxy from a Tool Consumer
Use Case Local ID: | LTIv1-13
Brief Description: | The Tool Consumer administrator removes a Tool Proxy from the Tool Consumer system.
Level: | Summary
Actors: | · Tool Consumer Administrator · Tool Consumer Runtime
Preconditions: | Tool Proxy has been registered with the Tool Provider
Basic Flow of Events: | 1. Initiate the removal process. Tool Consumer Administrator navigates to a web page within the Tool Consumer system and performs an action to manually remove a selected Tool Proxy. 2. Disable Resource Links. The TC deletes all Tool Proxy Bindings associated with the specified Tool Proxy. As a best practice, the Resource Links should not be explicitly deleted. Instead, the TC should merely hide or “gray-out” Resource Links that do not have an active Tool Proxy Binding. If the Tool Proxy is redeployed into the Tool Provider system in the future, and a new Tool Proxy Binding is created, then those old Resource Links will become functional once again.

## 4.2 Use Cases for Links without a Tool Proxy

The use cases in this section explain how to establish the security environment for LTI links that are not associated with a Tool Proxy, and it explains how LTI links are distributed via Common Cartridge.

The security environment for Basic LTI launches must be set up using out-of-band interactions between the TP administrator and either the TC administrator or an Instructor who will be authoring a Basic LTI link.

There are two possible credentials associated with a particular Basic LTI launch.

1. TC-wide instance guid and secret associated with a particular TP. The TC-wide instance guid establishes the identity of the TC for launches to a particular TP. Once the TC-wide secret is established for a TP, all Basic LTI tool launches to the TP’s domain will use this same secret. Using a TC-wide secret gives TPs the option of trusting user information and context information across multiple contexts within a particular TC instance as being maintained properly by the TC.

In order to select which TC-wide password to be used for a particular LTI link, the TC examines the domain name in the launch URL for the LTI link. The TC-wide password is looked up in the list of TC-wide passwords scanning the domain name of the launch URL from right to left. So for example, if the launch URL was:

http://launch.math.vendor.com/launch.php

The TC would look up the following TC-wide secret keys in order from specific to general: launch.math.vendor.com, math.vendor.com, and then vendor.com. So when TPs 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 TC-wide secret for a particular TP with the appropriate launches.

2. Link-level key and secret associated with a particular link. This will occur when the Basic LTI link is directly authored by the instructor within the TC. This secret will often be produced when the Instructor creates or gains access to a TP content/tool and the TP content/tool provides the instructor with a key and secret associated with the TP link.

Basic LTI launches can happen from the TC with any combination of TC-wide and link-level credentials including one or the other, both, or neither being present. When both are present the launch uses the TC-wide secret to sign the request.

If there is no key/secret combination available for this launch and the TC wants to perform the launch, the TC should not sign the launch data using OAuth. The TC can decide if it wants to send unsigned requests and the TP can decide if it wants to accept unsigned requests. A TC may also choose to treat the lack of key/secret values as an error and refuse to perform the launch.

### 4.2.1 Setting TP Domain Credentials (Basic LTI)

Use Case Title: | Setting TP Domain Credentials (Basic LTI)
Use Case Local ID: | LTIv1-14
Brief Description: | The TC administrator configures TP domain credentials for a particular TP. These credentials apply to new Basic LTI links authored directly in the TC system and also to Basic LTI links imported from a Common Cartridge (see Use Case LTIv1-16).
Level: | Summary
Actors: | · TC Administrator · TP Administrator
Basic Flow of Events: | 1. Generate credentials. The TP Administrator creates the key and secret combination for the TC (where the TC administrator may request a particular key, often the TC domain name). 2. Exchange the credentials. The TC Administrator obtains the key, secret and TP domain name from the TP administrator. The LTI standard does not prescribe any particular method for this exchange. 3. Persist the credentials in the TC. The TC Administrator associates the credentials with TP’s domain and persists this information using a TC-provided dialog or configuration mechanism.

### 4.2.2 Setting Link Level Credentials (Basic LTI)

Use Case Title: | Setting Link Level Credentials (Basic LTI)
Use Case Local ID: | LTIv1-15
Brief Description: | An instructor authors a Basic LTI link and sets the key/password for that link.
Level: | Summary
Actors: | · Instructor · Tool Provider (TP)
Preconditions: | None
Basic Flow of Events: | 1. Exchange Link Level Credentials. The Instructor contacts the TP to obtain access to a provider tool or content. The TP provides the Instructor with (1) a Basic LTI launch URL or XML snippet for the content or tool, (2) a key that will be used to access this content/tool, and (3) a secret associated with the key. The LTI standard does not prescribe any mechanism for this exchange. 2. Persist Link Level Credentials in the TC system. The Instructor enters the three values (URL or XML snippet, Key, Secret) into a Basic LTI authoring dialog in the TC system.

### 4.2.3 Managing Credentials for Basic LTI Links Imported from a Cartridge

Use Case Title: | Managing Credentials for Basic LTI Links Imported from a Cartridge
Use Case Local ID: | LTIv1-16
Brief Description: | An Instructor imports a Common Cartridge containing Basic LTI link descriptors into their context and users use the content.
Level: | Summary
Actors: | · Instructor · TC User (typically a Student or Instructor)
Preconditions: | · A cartridge creator has authored a Common Cartridge that contains one or more Basic LTI Link descriptors. These descriptors specify the launch URL(s) and other data associated with the links, but they do not contain keys or secrets. · In accordance with Use Case LTIv1-14, the TC Administrator has set the domain credentials to particular TP(s) that are referenced in the cartridge.
Basic Flow of Events: | 1. Import the cartridge. The Instructor obtains the Common Cartridge and imports it into a learning context within the TC system. 2. Use domain credentials during Tool Launch. When a TC User launches a Basic LTI link imported from the Common Cartridge, the TC signs the launch request using the pre-configured credentials associated with the TP address. In particular, as long as the TC-wide credentials are already installed, the Instructor does not need to take any further action to secure the launch request beyond importing a cartridge.
Alternative Flows: | A. Domain Credentials are not predefined If the domain credentials are not predefined within the TC system (i.e. the preconditions to this use case are not satisfied) then at Step 2 the launch requests will not be signed. In this case, the TC may (at its discretion) refuse to allow the Tool Launch to proceed. If an unsigned tool launch does occur, the TP may (at its discretion) refuse to honor the request. To correct such launch failures, it is possible to add domain or link level credentials (in accordance with Use Cases LTIv1-14 and LTIv1-15 respectively) after the cartridge has been imported.

# 5 Information Model

## 5.1 Tool Management Messaging Schema

### 5.1.1 ToolProxyRegistrationRequest Class

Figure 5.1 ‘ToolProxyRegistrationRequest’ class diagram.

Table 5.1 Description of the ‘ToolProxyRegistrationRequest’ class.

Descriptor | Definition
Class Name | ToolProxyRegistrationRequest
Class Type | container
Parents | n/a
Children | [reg_password]
Description | The ToolProxyRegistrationRequest is a message sent from the Tool Consumer to the Tool Provider to launch the Registration UI as described in the basic Tool Proxy Deployment use case [LTIv1-01]. The Tool Consumer binds this message to an HTML form that is auto-submitted to the Tool Provider. For an explanation of this process, see the LTI Messaging Framework specification [LTI, 14 MSF]. The vendor_code, tool_code, and tool_version attributes uniquely identify the particular Tool Proxy that is being requested for deployment. When deployment is initiated as a consequence of importing an archive (see use case [LTIv1-03]), these attributes are obtained directly from the Tool Proxy Locator. When deployment is initiated via the Tool Proxy Request Form (see use case [LTIv1-02]), the values for these attributes will not be defined. In this case, the administrator will typically need to choose the target Tool Proxy during his or her interactions with the Deployment UI. Alternatively, the Tool Provider might be able to infer the Tool Proxy from the URL to which the ToolProxyRegistrationRequest was submitted. In other words, the Tool Provider might define a different Deployment URL for each Tool Proxy.

1

2

3

4

5

5.1

5.1.1

#### 5.1.1.1 reg_password Attribute Description

Table 5.2 Description of the ‘reg_password’ attribute for the ToolProxyRegistrationRequest class.

Descriptor | Definition
Attribute Name | reg_password
Data Type | String
Value Space | n/a
Multiplicity | 1
Description | This is the tool registration password. A single-use registration password is used when the TP submits the Tool Proxy to the TC. This password should be valid for a few hours, which is enough to cover an extended interaction between the TC administrator and the TP deployment application.

### 5.1.2 RegistrationMixin Class

Table 5.3 Description of the ‘RegistrationMixin’ class.

Descriptor | Definition
Class Name | RegistrationMixin
Class Type | container
Parents | n/a
Children | [tool_version, tool_code, vendor_code, tc_profile_url], ordered
Description | This mixin encapsulates parameters that the Tool Provider requires in order to register a Tool Proxy with a given Tool Consumer.

5.1.2

#### 5.1.2.1 tool_version Attribute Description

Table 5.4 Description of the ‘tool_version’ attribute for the RegistrationMixin class.

Descriptor | Definition
Attribute Name | tool_version
Data Type | NormalizedString
Value Space | n/a
Multiplicity | 0..1
Description | This parameter specifies which version of the Tool Proxy is being requested for deployment. The value corresponds to the tool_info/version value in the Tool Profile.

#### 5.1.2.2 tool_code Attribute Description

Table 5.5 Description of the ‘tool_code’ attribute for the RegistrationMixin class.

Descriptor | Definition
Attribute Name | tool_code
Data Type | Name
Value Space | n/a
Multiplicity | 0..1
Description | This parameter identifies the Tool Proxy that is being requested for deployment. The value corresponds to the tool_info/code value in the Tool Profile.

#### 5.1.2.3 vendor_code Attribute Description

Table 5.6 Description of the ‘vendor_code’ attribute for the RegistrationMixin class.

Descriptor | Definition
Attribute Name | vendor_code
Data Type | Name
Value Space | n/a
Multiplicity | 0..1
Description | This parameter indicates the 'expected' vendor for this registration request.

#### 5.1.2.4 tc_profile_url Attribute Description

Table 5.7 Description of the ‘tc_profile_url’ attribute for the RegistrationMixin class.

Descriptor | Definition
Attribute Name | tc_profile_url
Data Type | URL
Value Space | n/a
Multiplicity | 1
Description | This is a fully qualified URL pointing to the Tool Consumer Profile. The Tool Provider should append the lti version as a parameter to this url: lti_version=<ltiversion>. If the lti_version is not specified or if the specified version is not explicitly supported by the Tool Consumer then the Tool Consumer should return a profile for the newest version of LTI that they support.

### 5.1.3 RegistrationStatus Enumeration

Table 5.13 Literal Values for the ‘RegistrationStatus’ Enumeration.

Literal Value | Description
success | Indicates that the Tool Proxy registration process completed successfully.

## 5.2 Mixin Types

### 5.2.1 CoreMessageMixin Class

Figure 5.2 ‘CoreMessageMixin’ class diagram.

Table 5.22 Description of the ‘CoreMessageMixin’ class.

Descriptor | Definition
Class Name | CoreMessageMixin
Class Type | container
Parents | n/a
Children | [lti_version, message_type, custom], ordered
Description | This mixin is a container that specifies the LTI version and declares the message type. It also holds an optional collection of custom properties. All LTI messages must inherit this mixin.

5.2

5.2.1

#### 5.2.1.1 lti_version Attribute Description

Table 5.23 Description of the ‘lti_version’ attribute for the CoreMessageMixin class.

Descriptor | Definition
Attribute Name | lti_version
Data Type | NormalizedString
Value Space | For the current version of the LTI Specification (which you are now reading), this attribute must have the value "LTI-2p0".
Multiplicity | 1
Description | This attribute specifies the version of the LTI standard to which the message conforms.

#### 5.2.1.2 message_type Attribute Description

Table 5.24 Description of the ‘message_type’ attribute for the CoreMessageMixin class.

Descriptor | Definition
Attribute Name | message_type
Data Type | NormalizedString
Value Space | n/a
Multiplicity | 1
Description | This is an identifier for the type of message. Each concrete message that includes the CoreMessageMixin defines a distinct value for this parameter.

#### 5.2.1.3 custom Attribute Description

Table 5.25 Description of the ‘custom’ attribute for the CoreMessageMixin class.

Descriptor | Definition
Attribute Name | custom
Data Type | PropertySet
Value Space | n/a
Multiplicity | 0..1
Description | This list contains custom parameters declared in the Tool Profile.

### 5.2.2 LTIToolProxyMixin Class

Figure 5.3 ‘LTIToolProxyMixin’ class diagram.

Table 5.26 Description of the ‘LTIToolProxyMixin’ class.

Descriptor | Definition
Class Name | LTIToolProxyMixin
Class Type | container
Parents | n/a
Children | [tool_proxy_guid]
Description | All LTI messages originating from a registered Tool Proxy of the Tool Consumer include this mixin. The mixin contains the GUID for the Tool Proxy.

####

5.2.2

#### 5.2.2.1 tool_proxy_guid Attribute Description

Table 5.27 Description of the ‘tool_proxy_guid’ attribute for the LTIToolProxyMixin class.

Descriptor | Definition
Attribute Name | tool_proxy_guid
Data Type | GUID
Value Space | n/a
Multiplicity | 1
Description | This is the GUID string that is returned from the registerTool method in the Tool Registration Service.

### 5.2.3 LaunchMixin Class

Figure 5.4 ‘LaunchMixin’ class diagram.

Table 5.28 Description of the ‘LaunchMixin’ class.

Descriptor | Definition
Class Name | LaunchMixin
Class Type | container
Parents | n/a
Children | [user_id, roles, launch_presentation], ordered
Description | This is a common mixin used by all authenticated launch requests.

5.2.3

#### 5.2.3.1 user_id Attribute Description

Table 5.29 Description of the ‘user_id’ attribute for the LaunchMixin class.

Descriptor | Definition
Attribute Name | user_id
Data Type | Name
Value Space | n/a
Multiplicity | 1
Description | This is an identifier for the user that is locally unique within the Tool Consumer. This identifier should not carry any personally identifiable information. A globally unique identifier for the user may be formed by combining the Tool Consumer Instance GUID with the user_id into a sourcedid of the form "<ToolConsumerInstanceGUID>:<user_id>".

#### 5.2.3.2 roles Attribute Description

Table 5.30 Description of the ‘roles’ attribute for the LaunchMixin class.

Descriptor | Definition
Attribute Name | roles
Data Type | String
Value Space | n/a
Multiplicity | 1..*
Description | This is a comma-separated list of URN values for the roles of the user. The vocabulary for role names is open, but the list must include at least one role from the LIS vocabulary. In the case of LIS context roles, it is permissible to identify the role by its 'handle' only - rather than a fully qualified URN value as required for other vocabularies. Thus, LIS context roles form the default vocabulary for LTI roles.

#### 5.2.3.3 launch_presentation Attribute Description

Table 5.31 Description of the ‘launch_presentation’ attribute for the LaunchMixin class.

Descriptor | Definition
Attribute Name | launch_presentation
Data Type | LaunchPresentation
Value Space | n/a
Multiplicity | 0..1
Description | presentation is optional and aims at giving hints to the Tool Producer on how to display its content.

### 5.2.4 ContextMixin Class

Figure 5.5 ‘ContextMixin’ class diagram.

Table 5.32 Description of the ‘ContextMixin’ class.

Descriptor | Definition
Class Name | ContextMixin
Class Type | container
Parents | n/a
Children | [context]
Description | This is the mixin for all launch requests that are made from a specific context (such as a course section) in the Tool Consumer.

5.2.4

#### 5.2.4.1 context Attribute Description

Table 5.33 Description of the ‘context’ attribute for the ContextMixin class.

Descriptor | Definition
Attribute Name | context
Data Type | Context
Value Space | n/a
Multiplicity | 1
Description | This is a container that holds information about the context from which the message originates.

## 5.3 Messaging Data Types

### 5.3.1 LaunchPresentation Class

Table 5.42 Description of the ‘LaunchPresentation’ class.

Descriptor | Definition
Class Name | LaunchPresentation
Class Type | container
Parents | LaunchMixin
Children | [locale, css_url, document_target, window_name, width, height, return_url], ordered
Description | Container for all the parameters that are used by the Tool Provider to manage the User Interface

5.3

5.3.1

#### 5.3.1.1 locale Attribute Description

Table 5.43 Description of the ‘locale’ attribute for the LaunchPresentation class.

Descriptor | Definition
Attribute Name | locale
Data Type | String
Value Space | n/a
Multiplicity | 1
Description | language, country and variant separated by underscores. Language is the lower-case, two-letter code as defined by ISO-639 (list of codes available at http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt). Country is the upper-case, two-letter code as defined by ISO-3166 (list of codes available at http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html). Country and variant codes are optional.

#### 5.3.1.2 css_url Attribute Description

Table 5.44 Description of the ‘css_url’ attribute for the LaunchPresentation class.

Descriptor | Definition
Attribute Name | css_url
Data Type | URL
Value Space | n/a
Multiplicity | 0..1
Description | This is the URL for a cascading style sheet that the TP can use to render web pages in a style that matches the look of the TC.

#### 5.3.1.3 document_target Attribute Description

Table 5.45 Description of the ‘document_target’ attribute for the LaunchPresentation class.

Descriptor | Definition
Attribute Name | document_target
Data Type | DocumentTarget
Value Space | Enumerated as: {frame, iframe, window}. For descriptions of these values, see Table 5.50
Multiplicity | 0..1
Description | The value should be either ‘frame’, ‘iframe’ or ‘window’. This value is purely informative; it informs the TP how the destination within the tool is going to be rendered in the TC. When the value is "window", the tool will be rendered in a new window. In this case, the name for the new window may be specified by the "window_name" attribute. When the value is "frame", the tool will be rendered in the same frame (or current window) where the link appears. When the value is "iframe", the TC will open a new iframe in which to place the tool.

#### 5.3.1.4 window_name Attribute Description

Table 5.46 Description of the ‘window_name’ attribute for the LaunchPresentation class.

Descriptor | Definition
Attribute Name | window_name
Data Type | NormalizedString
Value Space | n/a
Multiplicity | 0..1
Description |

#### 5.3.1.5 width Attribute Description

Table 5.47 Description of the ‘width’ attribute for the LaunchPresentation class.

Descriptor | Definition
Attribute Name | width
Data Type | String
Value Space | n/a
Multiplicity | 0..1
Description | the width of the window or frame where the content from the Tool will be displayed

#### 5.3.1.6 height Attribute Description

Table 5.48 Description of the ‘height’ attribute for the LaunchPresentation class.

Descriptor | Definition
Attribute Name | height
Data Type | String
Value Space | n/a
Multiplicity | 0..1
Description | the height of the window or frame where the content from the Tool will be displayed

#### 5.3.1.7 return_url Attribute Description

Table 5.49 Description of the ‘return_url’ attribute for the LaunchPresentation class.

Descriptor | Definition
Attribute Name | return_url
Data Type | URL
Value Space | n/a
Multiplicity | 0..1
Description | URL where the Tool Provider can redirect the user back to the Tool Consumer interface. This URL may accept some additional parameters for specific LTIMessage types. See the documentation of each message type for details.

### 5.3.2 DocumentTarget Enumeration

Table 5.50 Literal Values for the ‘DocumentTarget’ Enumeration.

Literal Value | Description
frame | The Tool opens in the same frame that contained the link.
iframe | The Tool opens within an iframe nested inside the frame that contains the link.
window | The Tool opens in a new window.

# About This Document

Title: IMS Learning Tools Interoperability Tool Management

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

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

Version: 2.0

Version Date: 6 January 2014

Status: Final Release

Purpose: This document is made available for adoption 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

## 5.4 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
v2.0 Public Draft | 1 November 2012 | First release of the Tool Management specification for LTI 2.
v2.0 Final | 6 January 2014 | Remove ReRegistration message-type (to be included in a later release).

IMS Global Learning Consortium, Inc. (“IMS Global”) is publishing the information contained in this IMS Global Learning Tools Interoperability Tool Management(“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 Tool Management v2.0 Final
Revision: 6 January 2014

[1] Some Tools may have optional features that can be enabled or disabled independently. For example, a Tool may offer an optional gradebook integration that can be either enabled or disabled.

[2] As a best practice, the Tool Provider should disclose to the administrator the types of data exchanges that may occur when the Tool is enabled. For example, if the Tool will be reading sensitive user data or pushing scores into the Tool Consumer's gradebook, these interactions should be disclosed. Based on this information, the administrator may choose to change the set of selected tool features or abort the deployment process entirely.