BasicLTI PowerLink

This PowerLink provides a mechanism for connecting WebCT with external learning applications (referred to as tool providers) which support the IMS Learning Tools Interoperability 2 specification. This allows WebCT to act as a tool consumer of LTI-compliant tools. Support is provided for LTI 1.1 which includes a basic service for accessing a grade book column for students, as well as the unofficial extension services which, in addition to a grade book access, provide tool providers with access to a list of enrolments and a small data store.

LTI provides an important step towards enabling tool providers 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.5.00 (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 provider 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). However, even when using Section-level secrets, it is essential that an Institution-level secret is set as it is used for internal requests. As with all WebCT shared secrets, the Institution-level password should not be left at its default of SECRET.
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. This value should be one of Person ID (numeric database key), WebCT ID (username used to login with) or sourcedid value (which may be populated by the Student Information System).
9. This secret is not shared with the tool provider; it is merely used to secure data sent to the tool provider which is passed back when making a service request. To enable the services this should be something other than the default of SECRET.
10. 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 provider
11. 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 provider; this may be both Section Designer and Section Instructor whether the proxy tool is accessed from either the Build or Teach tab.
12. 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.
13. Additional parameters to be passed to the tool provider 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. The values of parameters are parsed for placeholders referring to user or context properties (see below).
14. As well as checking the boxes in this configuration setting, services will not be available unless a services secret value has also been set. The proxy tool instance must be configured to send the user ID value (without a user being able to veto this option) for the outcomes and memberships services to be available. The outcomes service also requires a column name to be entered in the grade book column setting.

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 provider 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).

Custom parameter values

The values entered for custom parameters are parsed before being sent to the external tool. This process uses the variable substitutions implemented by the getFormattedName methods of the LearningContextVO and UserVO classes in the WebCTDAO package (see the JavaDocs for full details). In addition, the following IMS LIS variables are supported:

Note that whilst a variable may be supported, it may always be replaced with an empty value (e.g. $Person.address.timezone).

This PowerLink is designed to cover two main use cases:

• a proxy tool created to connect to a specific tool provider
• 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. For both to work make sure that you have changed the Institution-level shared secret from its default value.

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
• Value to send as the User ID
• Extension services enabled for tool provider to use
• Secret to secure extension services
• Name for grade book column used by the outcomes service
• URL to a CSS file
• URL to a resource file
• Signature for resource file
• 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:

Further parameters will be included if any of the extension services are enabled (see below). OAuth is used to add a signature and other parameters to secure the connection between the two servers.

Using the extension services

If the tool provider supports one or more of the extension services it should be enabled in the configuration settings (see Extension services enabled for tool provider to use above). A secret must also be set to secure the requests being received from the tool provider (see Secret to secure extension services above).

Outcomes service

The outcomes service allows the tool provider to set, read, and delete a value for each student in the grade book. The name of the column to be used must be specified in the configuration settings. Support is provided for both the LTI 1.1 outcomes service and the unofficial Basic LTI outcomes extension service. When the service is enabled, the following parameters are included in the launch:

Memberships service

The memberships service allows the tool provider to request a list of enrolments for the current section. When enabled, the following parameters are included in the launch:

Setting service

The setting service allows the tool provider to set, read, and delete a value for the specific proxy tool instance. When enabled, the following parameters are included in the launch:

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
• check the secrets set at the Institution level is not empty and not set to the default of SECRET
• 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.