BasicLTI PowerLink

This PowerLink provides a mechanism for connecting WebCT with external tools which support Basic LTI, a subset of the full IMS Learning Tools Interoperability 2 specification. This allows WebCT to act as a tool consumer of Basic LTI-compliant tools. Whilst the full specification has still to be released, Basic LTI provides an important step towards enabling tool producers to support access from multiple platforms, including different flavours of virtual learning environments (or learning management systems). From a tool consumer perspective it also opens up new opportunities for collaborative work between users of different platforms (or just different installations of the same platform).

The BasicLTI PowerLink is written for WebCT Vista 4.2 (or higher) and WebCT Campus Edition 6.2 (or higher). The Installation section lists the dependencies on other library files.

This PowerLink is installed in the same way as any other WebCT Vista 4+ PowerLink:

1. Create a directory called basiclti in the deployablecomponents area of the WebCT domain directory on each application server (including the administration server for a cluster).
2. Copy the basiclti.jar and dependent jar files (see below) into the basiclti directory. If desired, the dependent jar files may be placed in a directory named common in the deployablecomponents area; this would allow them to be shared with any other PowerLinks with the same dependencies.
3. Restart the WebCT service.
4. Log into WebCT as serveradmin.
5. In the Utilities, Settings area click on the link labelled BasicLTI module in the System Integration column.
6. Enable the tool by selecting the radio button labelled True for the enable setting and click on the Save Values button at the bottom of the page.
7. In the Utilities, PowerLinks Proxy Tools area click on the Add Proxy Tool button.
8. Select BasicLTI module from the drop-down list and click on the Next button.
9. Enter details as required in the boxes provided; for example:
   • Proxy Tool Name: Basic LTI tool
   • Version: 1.1
   • Description: Connect to an external tool supporting Basic LTI.
   Note: the Proxy Tool Name is what will appear to Section Designers when they add the tool to their sections. Click on the Save button.
10. In the Utilities, Settings area click on the link labelled with the Proxy Tool Name entered in the previous step which should appear in the Tools column.
11. Clear the tick in the Lock setting checkbox for the Enable Tool setting. Click on the Save Values button.
12. Select the settings for the proxy tool again to enable the tool by default so that it is visible under the Add Content Link button within each section. Alternatively, you can leave the tool disabled and allow Section Designers to enable it in any section where it is to be used.

The BasicLTI PowerLink depends upon the following Java library files:

• webctdao.jar, release 2.4.01 (or higher)
• org.apache.commons.httpclient
• velocity-dep.jar, version 1.6 (or higher)
• oauth-core.jar

The BasicLTI PowerLink has the following custom configuration settings:

Notes:

1. The level specifies the position within the learning context hierarchy at which this setting should be specified; it may, of course, be inherited from a higher level or even locked at a higher level where the setting value is to be fixed. Due to a bug in WebCT, value for settings at levels above Section should be edited for the module in the System Integration column of the Utilities area and not for the proxy tool itself in the tools column (see the known issues page for details).
2. A setting value of NA is treated as an empty string; this is a workaround to the SDK bug relating to locked empty settings (see the known issues page for details).
3. The consumer GUID is used to identify the tool consumer and is normally the domain name of the consuming system (for example, www.university.edu).
4. A secret should be agreed between the tool producer and the tool consumer to secure the connection between the two systems. The shared secret may be entered either at the Server or Institution level (for example, when setting up a proxy tool for a dedicated LTI tool) or at the Section level (for example, when setting up a generic proxy tool to be configured by Section Designers for an LTI tool of their choice). Any section-level secret will take precedence over the server/instution-level secret. A server/institution-level secret may also be extracted from a properties file (see Usage section below). The value entered into the PowerLink configuration settings is also used to secure internal calls within the PowerLink code itself. The main reason for having separate settings for the different levels of shared secret is to workaround a security issue in WebCT (see the known issues page for details).
5. The format of the section title and label may use any of the variable substitutions supported by the LearningContextVO.getFormattedName() method (see the WebCTDAO documentation area for details). For example, the default section title format of%1 - %C represents the course title followed by the section title.
6. The format of a user's display name may use any of the variable substitutions supported by the UserVO.getFormattedName() method (see the WebCTDAO documentation area for details). For example, the default user fullname format of %a %b represents the user's firstname followed by their lastname.
7. Check the boxes against the items to be selected; if the None option is selected then any other selections have no effect. This is a workaround to bug in WebCT (see the known issues page for details).
8. When this option is set and the user is an Institution Administrator a role of urn:lti:instrole:ims/lis/Administrator is also passed to the tool producer
9. When this option is set the designer role is only sent when the proxy tool is accessed from the Build tab (via the Preview option on the Action links menu) with the Instructor and Teaching Assistant roles only being sent when accessing from the Teach tab. When this option is not set all the user's roles within the Section will be passed to the tool producer; this may be both Section Designer and Section Instructor whether the proxy tool is accessed from either the Build or Teach tab.
10. A file containing the text to display on a splash page can be specified by entering its path within Class Files area of the Section; for example, a value of /lti/tool.htm refers to a file named tool.htm in a Class Files folder named lti. It is also possible to refer to a shared file in the System Files area by entering its content ID number (or a pseudonym of the system file may be entered, see below). Alternatively the text may be retrieved from a website by entering the URL. The splash page file may merely contain text or be an HTML page in which case the content between the <body> and </body> tags is used.
11. Additional parameters to be passed to the tool producer may specified as name/value pairs separated by semicolons; for example, group=A;login=true which will cause a parameter called custom_group with a value of A and a parameter called custom_login with a value of true to be passed in addition to the other parameters.

A properties file may be used to record server/institution level shared secrets and/or pseudonyms for system files. The properties file should be located in the same directory as the basiclti jar file and have the same name but with an extension of .properties.

A system file is referenced by its content ID. To make it easier for Section Designers to reference shared files, and to make the proxy tool settings more portable across systems, a pseudonym for a system file can be added to the properties file as follows:

//name=id

where name is the pseudonym and id is the content ID of the system file it refers to. The pseudonym may be used in the File containing splash text to display setting by entering it with a prefix of //; for example:

//name

A shared secret can be associated with the domain for an external tool by adding an entry to the properties file of the following form:

Tool producer domain name=secret

For example,

wiscrowd.appspot.com=secret

or

appspot.com=secret

If the properties file contains both of the above entries the secret corresponding to the more specific domain name (wiscrowd.appspot.com) will be used in preference to the more general domain name (appspot.com).

This PowerLink is designed to cover two main use cases:

• a proxy tool created to connect to a specific tool producer
• a generic proxy tool which can be configured by a Section Designer to connect to an Basic LTI-compliant tool of their choice

The following sub-sections illustrate each of these two use cases with the Wisdom of Crowds demonstration tool as an example.

Configuring a tool-specific Basic LTI proxy tool

Follow the installation procedure (see above) naming the proxy tool Wisdom of Crowds. Configure the proxy tool under the Tools column of the Settings page:

• Name of external tool - Wisdom of Crowds
• URL of external tool - http//wiscrowd.appspot.com/wiscrowd/12345/
• Tool consumer name - a short name for your institution (e.g. UoT)
• Tool consumer description - a full name for your institution (e.g. University of Testing)
• Tool consumer administrator email - an administrator email address for your institution (e.g. admin@testing.edu)
• Tool consumer GUID - the domain name of your server (e.g. testing.edu)
• Details to be sent to external tool - your own selection (e.g. Section ID, User ID, User name)
• Details which user can veto being sent to external tool - your own selecton (e.g. User ID, User name)

The following settings may be left at their default value:

• Resource-level shared secret
• Locale (e.g. en_GB)
• Section title format
• Section label format
• Format for user fullname
• Role mapping for Section Designers
• Role mapping for Section Instructors
• Role mapping for Teaching Assistants
• Role mapping for Students
• Role mapping for Auditors
• Support Institution Administrator role?
• Send Section Designer/Instructor role based on current tab (Build/Teach)?
• Display splash page before redirecting?
• File containing splash text to display
• Custom parameters

All settings should be locked to prevent them from being changed by Section Designers. Set the Enable setting to true if it is to appear by default on the Build tab; alternatively, you can leave the tool disabled and allow Section Designers to enable it in any section where it is to be used.

The Institution-level shared secret setting should be set by editing the settings for the BasicLTI PowerLink under the System Integration column. This value will be used both for accessing the external tool as well as for internal connections within the PowerLink. In order to allow more than one tool-specific proxy tool to be configured with different shared secrets, the value may be retrieved from the properties file instead (see above).

Configuring a generic Basic LTI proxy tool

A generic proxy tool can be created using a name such as Basic LTI tool. Each of the settings should be left with default values and unlocked so that the Section Designer can enter those appropriate to the tool they wish to connect to. The Section Designer will need to know all the details for the external tool including the GUID and shared secret (although it is still possible to record the shared secrets in the properties file which will be used if a resource-level secret is not entered).

Redirecting to the external tool

The redirection process is performed via a POST request to the Tool URL setting with the following parameters:

OAuth is used to add a signature and other parameters to secure the connection between the two servers.

If you experience any problems using this PowerLink try the following to trace the cause:

• check that the tool URL being used is correct
• check the GUID and secret are correct for the external tool being connected to
• inspect the webct.log file for any reported errors
• increase the logging level for com.spvsoftwareproducts to DEBUG either temporarily via serveradmin or more permanently via the log4j.properties file in the serverconfs directory.

This work is written by Stephen Vickers and is released under a Creative Commons GNU General Public Licence. The BasicLTI PowerLink is available for download from OSCELOT where it is also possible to report bugs and submit feature requests.