Overview

IMS Global Certified
IMSC1ss2012W2

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

System requirements

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.

Installation

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:

Configuration settings

The BasicLTI PowerLink has the following custom configuration settings:

Name Level [see note 1] Required? Default value [see note 2] Comments
Name of external tool Section Yes    
URL of external tool Section Yes http://  
Tool consumer name Section No NA e.g. UofT
Tool consumer description Section No NA e.g. University of Testing
Tool consumer administrator email Section No NA e.g. admin@testing.edu
Tool consumer GUID Section Yes   [see note 3]
Institution-level shared secret Server and Institution Yes SECRET [see note 4]
Resource-level shared secret Section No NA [see note 4]
Locale (e.g. en_GB) Section No en_US  
Section title format Section No %1 - %C [see note 5]
Section label format Section No %G [see note 5]
Format for user fullname Section No %a %b [see note 6]
Details to be sent to external tool Section Yes None [see note 7]
Details which user can veto being sent to external tool Section Yes None [see note 7]
Value to send as the User ID Section Yes Person ID [see note 8]
Extension services enabled for tool provider to use Section Yes None [see notes 7 and 14]
Secret to secure extension services Section No SECRET [see note 9]
Name for grade book column used by the outcomes service Section No NA Must be set for outcomes service to be available
URL to a CSS file Section No NA Any value entered here will override the default setting of /webct/css/styles.jsp
URL to a resource file Section No NA  
Signature for resource file Section No NA  
Role mapping for Section Designers Section Yes Administrator [see note 7]
Role mapping for Section Instructors Section Yes Instructor [see note 7]
Role mapping for Teaching Assistants Section Yes Teaching Assistant [see note 7]
Role mapping for Students Section Yes Learner [see note 7]
Role mapping for Auditors Section Yes Learner [see note 7]
Support Institution Administrator role? Section Yes No [see note 10]
Send Section Designer/Instructor role based on current tab (Build/Teach)? Section Yes No [see note 11]
Display splash page before redirecting? Section Yes No  
File containing splash text to display Section No NA [see note 12]
Custom parameters (name1=value1;name2=value2) Section No NA [see note 13]

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:

Name Equivalent WebCTDAO variable substitution or other source
$Person.sourcedId %j:%k
$Person.name.full Uses the format for user fullname setting value (see above)
$Person.name.family %b
$Person.name.given %a
$Person.name.middle %c
$Person.name.prefix %d
$Person.name.suffix %e
$Person.address.street1 %{Street 1}
$Person.address.street2 %{Street 2}
$Person.address.street3 %{Street 3}
$Person.address.street4 %{Street 4}
$Person.address.locality %{Locality 1}
$Person.address.statepr %{Region 1}
$Person.address.country %{Country 1}
$Person.address.postcode %{PCode 1}
$Person.address.timezone  
$Person.phone.mobile %{Mobile}
$Person.phone.primary %{Voice 1}
$Person.phone.home %{Voice 1}
$Person.phone.work %{Voice 2}
$Person.email.primary %h
$Person.email.personal %h
$Person.webaddress  
$Person.sms  
$CourseOffering.sourcedId %0:%4
$CourseOffering.label %4
$CourseOffering.title %1
$CourseOffering.shortDescription %D
$CourseOffering.longDescription %E
$CourseOffering.courseNumber  
$CourseOffering.credits  
$CourseOffering.academicSession  
$CourseSection.sourcedId %F:%G
$CourseSection.label %G
$CourseSection.title %C
$CourseSection.shortDescription %D
$CourseSection.longDescription %E
$CourseSection.courseNumber  
$CourseSection.credits  
$CourseSection.dept %H
$CourseSection.timeFrame.begin %I %J
$CourseSection.timeFrame.end %K %L
$CourseSection.dataSource LearningContextVO.getDataSource() for section
$CourseSection.sourceSectionId LearningContextVO.getGlcId() for section

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

Usage

This PowerLink is designed to cover two main use cases:

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:

The following settings may be left at their default value:

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:

Name Value
lti_message_type The value basic-lti-launch-request.
lti_version The value LTI-1p0.
tool_consumer_instance_guid The value of the Tool consumer GUID for tool setting.
tool_consumer_instance_name The value of the Tool consumer name setting.
tool_consumer_instance_description The value of the Tool consumer description setting.
tool_consumer_instance_url The URL of the WebCT server.
tool_consumer_instance_contact_email The value of the Tool consumer administrator email setting.
tool_consumer_info_product_family_code The value webct.
tool_consumer_info_version The release of WebCT (e.g. 8.0.6).
context_id The learning context ID for the current section.
context_type The value CourseSection.
context_title The formatted value generated by parsing the Section title format setting.
context_label The formatted value generated by parsing the Section label format setting.
lis_course_offering_sourcedid The sourcedid for the parent course (source name and ID are separated by a colon).
lis_course_section_sourcedid The sourcedid for the current section (source name and ID are separated by a colon).
resource_link_id The proxy tool instance ID.
resource_link_title The name of the proxy tool instance.
user_id The ID for the current user (using the value selected in the configuration settings).
lis_person_name_given The first name of the current user.
lis_person_name_family The last name of the current user.
lis_person_name_full The formatted value generated by parsing the Person name format setting.
lis_person_contact_emailprimary The email address of the current user.
lis_person_sourcedid The IMS Source name followed by the IMS Source ID for the current user separated by a colon.
roles One or more of Mentor, Learner, TeachingAssistant, Instructor or ContentDeveloper as well as Administrator if the user is also an institutional administrator.
launch_presentation_locale The value of the Locale setting.
launch_presentation_return_url The URL to redirect a user back to WebCT with optional messages.
launch_presentation_document_target The value window when the Open in new window is set to "Yes"; otherwise the value frame.
oauth_callback The value about:blank.
ext_lms The name and release of WebCT (e.g. webct-8.0.6).
ext_launch_presentation_css_url The URL of the CSS file parameter or, if none, the WebCT CSS file (/webct/css/styles.jsp)..
ext_resource_link_content The value of the URL to a resource file setting.
ext_resource_link_content_signature The value of the Signature for resource file setting.

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:

Name Value
lis_outcome_service_url The URL for the tool provider to use when making a request to the LTI 1.1 outcomes service
ext_ims_lis_basic_outcome_url The URL for the tool provider to use when making a request to the outcomes extension service
lis_result_sourcedid An identifier for the tool provider to use to identify the current user when making service requests
ext_ims_lis_resultvalue_sourcedids a list of the types of outcomes supported by the tool consumer: decimal,percentage,ratio,letteraf,letterafplus,passfail,freetext

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:

Name Value
ext_ims_lis_memberships_url The URL for the tool provider to use when making a request to the memberships service
ext_ims_lis_memberships_id An identifier for the tool provider to use in order to prove the validity of the request being made

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:

Name Value
ext_ims_lti_tool_setting_url The URL for the tool provider to use when making a request to the setting service
ext_ims_lti_tool_setting The current value of the setting
ext_ims_lti_tool_setting_id An identifier for the tool provider to use in order to prove the validity of the request being made

Troubleshooting

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

Version history

VersionDateDescription
1.1.018 February 2010First public release
1.1.0212 May 2010 Added support for resource_link_title, launch_presentation_return_url, and tool_consumer_instance_url parameters
Stopped "None" role option from being sent to tool providers
Added support for return messages and log requests (recorded with INFO and ERROR statuses)
1.1.039 October 2010 Corrected name of lis_person_sourcedid parameter
Added launch_presentation_document_target parameter
1.2.005 November 2011 Added support for outcomes, memberships and setting extension services. These are not official parts of the IMS LTI specification but are widely supported by tool consumers. This release also requires a later release (2.5+) of the WebCTDAO library.
1.3.0015 January 2012 Added support for LTI 1.1 (including Outcomes service)
Added LIS vocabulary options to parsing of custom parameter values
Added optional CSS file parameter
1.3.011 April 2012 Updated support for LTI 1.1 in line with final specification and passed IMS conformance tests

Licence

Creative Commons License 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.

Valid XHTML 1.0 Strict