View source for LTI/Best Practice/Issues for System Administrators

This section discusses issues relevant to system administrators for tool consumers seeking to make LTI tool providers available to their users.

== Tool requirements ==
The addition of an LTI-based tool to a VLE should involve the same type of due diligence process as for any other learning application. This includes:

* checking that its functionality meets needs and is compatible with existing infrastructure;
* agreeing the SLA, licence agreement and any licence fee;
* ensuring it complies with policies such as data privacy.

In order to properly assess the last of these, a system administrator needs to know what data is being passed between the VLE (tool consumer) and the tool. The LTI specification has no required parameters involving personal data, but does support the sharing of user IDs, names, email addresses and roles, as well as data about the link and course from which the launch originated. The tool consumer should have options to turn on and off the passing of such data, but it may not be easy to determine which parameters are required for the successful use of the tool provider, or when the inclusion of a particular parameter may provide enhanced functionality to users. It would be very helpful if the documentation provided by tool providers included the following to assist system administrators in knowing how to configure the link and understand the consequences of their use:

* which launch parameters not required by the LTI specification are required for a successful launch;
* which launch parameters are not required, but their presence gives enhanced functionality to users;
* which LTI roles are supported and what privileges are given to users with each role (this is particularly important if the TeachingAssistant role is supported as it is the one which is most likely to vary in level of privilege given to it by different institutions).

If such information is not readily available, then the best approach would be to start by turning off all the available options for passing context/resource/user data and only turn them on if a launch request fails or to improve the user experience.

== Configuring tools (XML) ==
The LTI specification does provide a mechanism for defining a connection to a tool provider using XML and some tool consumer implementations provide this option within their UI (e.g. the open source LTI building block for Blackboard Learn 9 and Canvas by Instructure). This XML can be used to specify:

* title;
* description;
* launch URL (including an optional URL for secure connections);
* custom parameters;
* URL for an icon (including an optional URL for secure connections);
* details about the vendor: code, name description, URL, contact email address.

In addition to these details extension sections may be defined for settings specific to individual platforms. For example, an extensions section with a platform name of "learn" is used by the open source LTI building block to enable all the configuration settings to be specified in the XML (e.g. which parameters should be passed, which value to use for a context ID, etc.). [[LTI/Best Practice/References#ceLTIc-G|[ceLTIc-G]]] It can, therefore, make it very convenient for customers to be supplied with an XML description of tool providers (or a URL to such an XML file) and can reduce problems with transcription errors. However, not all tool consumers adopt the format provided in the LTI specification; for example, Canvas expects XML with a root node named <code>cartridge_basiclti_link</code> rather than <code>basic_lti_link</code>. In addition the XML used by Canvas fails to validate because elements are not in the correct order, a new element (<code>options</code>) is introduced, and a required element (<code>vendor</code>) is omitted. Hence it is not possible, at present, for a single version of an XML description of a tool provider to be defined for use with any tool consumer. So be prepared to request a specific variation for your own needs or edit the XML provided.

== Verifying connections ==
{{anchor|CS4}}
{{Infobox
|title = Case Study 4 - Testing mode
|titlestyle = background-color: #fff; color: #000;
|bodystyle = background-color: #008080; color: #fff;
|datastyle = text-align: left;
|data1 = Any tool providers built using the PHP or Java LTI Tool Provider class libraries support a custom parameter of "debug=true" which causes more detailed error messages to be returned on failed launch requests.
}}
After configuring a new LTI tool, it is good practice to verify that it works. There is no mechanism in the specification for assisting with this; it is normally a matter of adding the tool to a course and trying a launch. Some tool consumer implementations may provide a launch option from the tool configuration page to make this easier. The main purpose of the test at this point is to verify the URL, key and secret used to configure the tool; if any of these items is entered incorrectly any attempt to launch the tool should fail. (Note that LTI 2 should overcome this issue as the configuration of tools is undertaken as a negotiation between the tool provider and tool consumer servers, without the risk of human error in entering launch parameters.) However, a failed launch request may also occur if:

* the tool provider has not yet set up the details on their system;
* the consumer key has not been enabled by the tool provider;
* the consumer key is only valid for a specific time period and the current time is not within that period;
* the launch request does not include sufficient data to support the requirements of the tool provider;
* the length of a parameter exceeds the tool provider's acceptable limit.

Hopefully, the tool provider returns a detailed reason for any errors which arise as a log entry for the tool consumer, or has an option to display such messages as part of a "testing mode".

== Course archive/restore/copy ==
When a course containing a link to an LTI tool is copied, for example, the link in the new course will have a different value for the <code>resource_link_id</code> parameter when launched. This means that a tool provider will see this as a launch from a new link but without appreciating that it originated from an existing link so that, for example, an option to duplicate the content from the original link could be offered. Tool providers may have a mechanism in place for trying to handle this situation, but system administrators should be aware the any archive/restore or copy actions which take place on the tool consumer system, are not automatically replicated by tool providers and so some manual intervention may be required. This is an important aspect to test when investigating new tool providers.

== Mapping VLE/LTI roles ==
LTI uses the LIS [[LTI/Best Practice/References#IMS-G|[IMS-G]]] vocabulary for user roles. These are likely to be different from those available within a course so a tool consumer will implement some form of mapping from course roles to LTI roles. This mapping need not be on a one-to-one basis, though typically it is. The mapping may be a static implementation applied to all LTI launches for all tool providers, or it may be configurable for each tool provider or even each resource link. The key for a system administrator is to ensure that, as far as they are able, users are given an LTI role appropriate to the tool provider and their course role. If the mapping is static and cannot be altered, then a review of the tool provider to ensure that users are given sufficient privileges within the tool provider and not given privileges which are not appropriate to their course role.

<comments />