Overview

IMS Global Certified
[IMSC1ss2012W3]

This Building Block provides a mechanism for connecting Blackboard Learn 9+ with external tools which support the IMS Basic LTI or LTI 1.1 specification. LTI is a mechanism for connecting tool consumers (systems such as virtual learning environments or learning management systems) with tool providers (external learning applications which provide additional functionality within a course, such as a blog, wiki, assessment tool, or some restricted content).

Support for Basic LTI was introduced by Blackboard in Learn 9.1 SP4; however, this building block supports all releases of Learn 9 and also provides support for the unofficial Basic LTI extension services (see below) and LTI 1.1 (which includes an Outcome service). Whilst the specification is still being developed, Basic LTI (now known as LTI 1.0) and LTI 1.1 provide an important step towards enabling external tool providers to support different flavours of tool consumer with a single integration. 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).

To download a copy of this Building Block, follow the link to OSCELOT in the Licence section at the bottom of this page.

Note that this page has not yet been fully updated with the changes included in release 2.3.1

Acknowledgements

The support of the following organisation is gratefully acknowledged:

SoftChalk logo
   SoftChalk
   home of SoftChalk Cloud - Create. Connect. Inspire!   

   PebblePad logo
   Pebble Learning
   home of PebblePad - not just an eportfolio

Such support assists with the ongoing development and enhancement of this Building Block allowing LTI solutions which fit the needs of tool providers to be delivered to users of Learn 9. If you have any specific needs or would like to support this project, please contact the author.

System requirements

The BasicLTI Building Block is written for Blackboard Learn 9.0 (or higher). It includes the following dependent Java library files:

Installation

This Building Block is installed by a Learn 9 system administrator in the same way as other Building Blocks. The following attribute privileges are required to be approved when making the Building Block active:

TypeNameAction
attributeuser.authinfoget
attributeuser.personalinfoget
persistContentcreate,modify
persistContentHandlercreate,modify,delete
persistGroupAssignmentcreate,delete
persistOutcomecreate,modify,delete
persistOutcomeDefinitioncreate,modify
persistOutcomeDefinitionCategorycreate,modify
persistOutcomeDefinitionScalecreate,modify
java.net.SocketPermission*connect

Configuration settings

The Building Block may be configured from the System Admin tab by either:

The main page displays a list of any existing tool provider registrations with a summary of the settings selected for each. The order of the tools can be changed (using the Learn 9 drag-and-drop functionality) and. its status updated - when a tool is disabled it is not available for use within courses. The action menu against the title of each tool provides access to options for editing the registration.
Sample tools list page

System settings

Click on the System Settings button to specify the default installation settings. Textual default settings are dependent on the current language pack and so may differ from those specified below.
Sample System Settings page

Institution details

Name Required? Description
Institution name Yes A short name for the institution (e.g. UoT)
Institution description Yes Full name for the institution (e.g. University of Testing)
Institution administrator email No An email contact for the institution (e.g. system.admin@testing.edu)

Extension services

Check the box against the name of an extension service to enable it for the server. See below for information about support for the extension services. If the box is not checked then no requests for this service by tool providers will be accepted.

Other options

This section can be used to enable the following options:

Defining a tool

Connections to tool providers can be defined in three different ways:

  1. Register a system-wide tool by entering its settings via the System Admin tab;
  2. Register a course-specific tool by entering its settings via the Course Tools area of the Control Panel (this is only available if the option has been enabled, see above);
  3. Register a course-specific tool by entering its launch URL via a course content item.

In all three cases, it is possible for an XML description of the tool to be used to initialise the settings (see below).

Initial registration

Register by settings

Click on the Register New Tool button to register a new tool provider, this will display the Registration Settings page. Connecting to each tool provider requires three pieces of data: a URL, a consumer key and and shared secret. These details will be provided by the tool provider and should be entered into the second section of the registration form. Take care to make sure these details are entered accurately; errors will cause connections to fail.
Sample registration by name settings page

If the tool provider uses any of the extension services (including the Outcome service supported by LTI 1.1), they should be selected on this page. The Used but not required by tool option allows the decision to be delegated to the course instructor. The services selected are summarised in the final column on the main page; a "x" indicates that the service is not enabled on the server (see the System Settings page above), a "-" indicates that the service is not selected, "O", "M" and "S" indicate that the Outcomes, Memberships and Setting services are selected, respectively (a lower case letter indicates that the service is optionally selected). Consult the tool provider about whether any of the services are required.

Normally the memberships service will send a full list of enrolments to the course when it is requested by a tool provider. This list may include users who do not have access to the link if a membership-based adaptive release criterion has been applied. An option is provided, therefore, to restrict the list to only students for which the link is visible; anyone assigned the LTI role of Instructor will also be included in the list. For group-based access restrictions to a tool to be reflected in the list returned by the memberships service, make the tool available as a content item and assign it to groups under the "Groups" section, rather than setting membership-based adaptive release rules.

The URL of a CSS file may also be passed to the tool provider on launch; some tool providers may use this option to allow users to change the appearance of their tool (e.g. to better match the Blackboard colour scheme). The default icon used when displaying links to tools in a course can be overridden by entering a URL to an alternative image in the "Other Settings" section.

Register by URL

An instructor may add a tool as a content item in a course. When doing so the "By URL" tab allows them to register a connection by entering a launch URL. A consumer key and secret may also be entered. However, if the URL matches a registered domain, then any key and secret associated with the domain will be used. In this way an administrator may enter the key and secret to be used by all tools for a specified domain leaving the instructor to only enter the launch URL for the required tool.
Sample registration by URL settings page

Register by XML

A tool provider may distribute the connection details to their tool in the form of XML. Such descriptors may be pasted into the box on the "By XML" tab to initialise the relevant settings.
Sample registration by XML settings page

See below for more information on the XML format.

Data settings

Each time an external tool is launched data about the user and their context (e.g. course) may be passed to the tool. Which data items are passed is controlled by the data settings page. When a new tool is registered the default data settings are applied - these default values are set up by clicking on the Default Settings button and selecting the Data Settings option. To override or change these for a specific tool, use the Edit data settings option from the action menu next to the tool's name.

Context data

A unique ID and a title will always be sent to the tool provider to identify the link followed by the user to launch the tool. In addition to this it is also possible to send an ID and title for the course.
Sample data settings page - context data section

Personal data

A unique ID is normally required to identify a user and allow the tool provider to retain details of their activities. The value to be used to represent this ID can be selected on this page; typically the database key provides a convenient opaque value but is subject to change if a user account is deleted and restored. For internally hosted tool providers, it may be preferable to use the username as the ID so that a more widely recognised value is used within the other systems. It is also possible to restrict the sending of a user's name, email address, roles and avatar (if enabled on the System Settings page above).
Sample data settings page - personal data section

When a user's role is selected to be sent to the tool provider, their course role in Learn 9 is mapped to zero, one or more roles recognised by LTI:

This section determines which LTI roles (columns) are sent for each course role (rows). The table will also include a row for each custom course role if the option to configure these separately has been selected on the System Settings page (see above); when the option is not selected.
Sample data settings page - role mappings section

It is also possible to send the administrator role when the user is also a system administrator.

Resource file

The LTI specification also allows a URL to a resource file (with an optional signature) to be sent to the tool provider. This section allows these details to be entered when required.
Sample data settings page - resource file section

Launch settings

The Launch Settings page determines how the tool is launched and specifies any custom parameters to be included in the data which is sent to the tool provider. When a new tool is registered the default data settings are applied - these default values are set up by clicking on the Default Settings button and selecting the Launch Settings option. To override or change these for a specific tool, use the Edit launch settings option from the action menu next to the tool's name.
Sample tool launch settings page

The tool may be opened in the Learn 9 frame, in a new window or in an iframe. The iframe option allows the course menu to be retained on the screen when accessing the tool from the Course tools page. When opening a tool in a new window, a window name may be specified so that the same window can be re-used each time the tool is opened. The window name should not start with an underscore. If no window name is specifed a default value of _blank is used.

A description of the tool can be displayed on a splash screen before a user is connected, If a URL is entered as the text the contents of this web page is displayed to the user.

Custom settings may be passed to a tool by entering one per line in the format name=value; for example:

debug=true
timeout=300

It is possible to specify custom settings when configuring a tool as well as when creating an instance of a tool within a course. In the case where values are specified with the same name, the one specified on the tool configuration page will take precedence.

Using XML to configure settings

A tool or domain can be configured using the XML format defined in the LTI specification. The extensions section is used to allow a value for each configuration setting to be specified. The names and permitted values of these settings are listed below.

NameDescriptionPermitted values
guidConsumer key 
secretShared secret 
administratorSend administrator role?true
false
avatarSend avatar URL?true
false
contextidSend context ID?true
false
contextidtypeWhich field to use as the context IDP
B
C
contextsourcedidSend context sourcedid?true
false
contexttitleSend context title?true
false
emailSend user's email address?M
O
N
ext_membershipsEnable Memberships extension service?M
O
N
ext_memberships_limitRestrict memberships to users for whom the link is visible?true
false
ext_memberships_groupsAllow group membership data to be sent to tool providers?true
false
ext_memberships_groupnamesAn optional name prefix (or regular expression) to limit the groups which are sent 
ext_outcomesEnable Outcomes services (LTI 1.1 and unofficial extension)?M
O
N
ext_outcomes_columnCreate a column in the Grade Centre when the link is createdtrue
false
ext_outcomes_formatDisplay format for the grade centre columnP
S
ext_outcomes_pointsSet the points possible for the column 
ext_outcomes_scorableInclude the column in Grade Centre calculationstrue
false
ext_outcomes_visiblemake the column visible to students in My Gradestrue
false
ext_settingEnable Setting extension serviceM
O
N
openinWhere to open the toolF
FNB
W
I
role.BMapping for Course BuilderI
D
T
L
M
role.GMapping for Grader/Marker role
role.PMapping for Instructor role
role.SMapping for Student role
role.TMapping for Teaching Assistant role
role.UMapping for Guest role
rolesSend user's role(s)?true
false
splashDisplay splash screen on launch?true
false
useridSend user's ID?M
O
N
useridtypeWhich field to use as the user IDP
B
N
S
usernameSend user's name?M
O
N
usersourcedidSend user's sourcedid?true
false
windownameName of window used to open the tool 

The setting option codes have the following meanings:

The contextidtype codes have the following meanings:

The ext_outcomes_format codes have the following meanings:

The openin codes have the following meanings:

The LTI role mapping codes have the following meanings:

The useridtype codes have the following meanings:

An XML description for a tool would be similar to the following example (note that the platform attribute should have a value of "learn" for this Building Block):



  My tool
  A simple example tool.
  https://my.server.edu/lit-launch/
  https://my.server.edu/images/mytool.png
  
    true
  
  
    true
    true
    true
    M
    F
    true
    M
    P
    M
    true
  

It is recommended that all setting values be specified in the extensions section so that the tool is completely configured via the XML, although those settings which do not impact the launch of the tool can be ignored if preferred.

Adding tools to content page menus

In Learn 9.1+, a link to a system-wide tool may be added to one of the content page menus. This allows instructors to select it by name to add it as a content item, without needing to select it via the Basic LTI tools option on the Tools menu. Each tool may be added to one of the following menus:

To add one or more tools to one of these menus, tick the checkboxes for each tool and select the menu name from the Display on menu drop-down list. To remove tools from a menu, select None from the drop-down list.

Accessing tools via a module

A module may be created to access a system-wide tool as follows:

  1. navigate to the Modules page on the System Admin tab
  2. click on the Create Module button
  3. enter a title (such as the tool name)
  4. select Basic LTI tool as the module type
  5. select an appropriate category
  6. optionally enter a reference name and description
  7. set System Availability to Yes
  8. setting Allow Asynchronous Loading to Yes is recommended if a content feed is to be displayed within the module
  9. select the remaining options as preferred
  10. click on the Submit button to create the module and display the module admin page

Sample Module Admin page

A module may contain a button to launch the tool. It may also contain the output obtained from an LTI request to a content feed URL; for example, a dashboard summary for the user. The request is made direct to the URL passing the same parameters as on a launch; if the module is not displayed within a course, then no context is provided. The output returned from the request may be in RSS or Atom feed formats or HTML. A feed format is recommended so that the presentation fits as closely as possible to the user's Blackboard theme. When using an RSS feed, the title element from each item are displayed as a list. An image element is displayed if provided in the feed; if the Allow launch? setting is ticked the image will also act as a hyperlink to launch the tool, otherwise the title element acts as the Alt text. The equivalent elements from an Atom field are title (within each entry), logo and title. The optional No data message will be displayed when no data is returned from the request, is of the wrong format or an error occurs. A default message of Sorry, unable to connect to server. is displayed when none is provided. The date and time at which the content was generated is displayed in the footer to the module. Some memory-based caching of module content is possible to avoid the requests being made too often (see the System settings). An example module display follows:
Sample tool module

Usage

Basic LTI tools can be made available within a course via either the Course tools page, as a content item added to a content page, or as a hyperlink added via the text box editor. Each of these options can be made available to a course via the Tool Availability page accessed from the Customisation area of the Control Panel.

Course tools

The Basic LTI tools link in the Course Tools area of the Control Panel displays a list of the tools which have been registered and enabled by the system administrator (see above). If the option has been enabled (see above) the Register New Tool button may be used to define a new connection for use only within the current course. The process for adding new tools is the same as for system administrators (see above) and the action menu against the tool can be used to edit the settings. For system-defined tools, the action menu provides a limited set of settings which can be edited.
Sample Course Tools Settings page

Some of the options on the page may be disabled or have limited choices as a result of how the tool or system has been configured.

The Basic LTI Tools option available on the Course Tools page displays a list of the tools which have been made available on the tools list (they will also be displayed in the same order as on this page). If an icon URL has been specified for a tool, this icon will appear next to the tool name, otherwise the default icon is displayed. Clicking on the tool name will launch the tool.
Sample course tools page

If a tool has been defined to show a splash page or if the user has been given a choice about sending one or more data items, then a page is displayed before the user is redirected to the tool.
Sample splash page

The tool will be displayed in the bottom frame of Learn 9, within an iframe (as in the example shown below) or in a new window.

Content items

If a tool has been added to a content page menu (see above) it can be added to the page by selecting the menu item from the relevant menu, If not, then a link to a Basic LTI tool may be added to a content page as follows:

  1. navigate to a content page
  2. ensure edit mode is turned on
  3. select "Basic LTI tool" from the Tools menu

Add content item

A tool may be selected in one of the following three ways:

The list of named tools will include all those which have been enabled on the System Admin tab and also all those which are defined within the course (even if they are not available from the course tools page).
Add tool by name

The process for registering tools by URL or XML is described in the "Registering a tool" section above.

Once a content item has been created, clicking on its name will redirect users to the tool. The item settings may be modified by selecting the "Edit" from its options menu.
Edit options for content item

The settings are:

Mashup link

It is also possible to add hyperlinks to Basic LTI tools within the text of a content item. Such a link is added by selecting the "Basic LTI Tool" from the "Add Mashup" button on the toolbar for the visual text box editor. To edit an existing hyperlink, place the cursor within the link before selecting the mashup tool.
Add mashup link

A popup window is displayed when the mashup tool is selected which provides a form from which to:

The value of the link text and the link title will default to any text which was highlighted in the visual text editor before the tool was selected. Alternatively if the cursor was within a hyperlink then its link text and link title are displayed in the form; if the hyperlink is to a Basic LTI tool, the tool is also selected in the drop-down list. If the link text and title are left blank, the name of the selected tool is used for these fields.
Mashup popup window

Domains

Domains may be added via the System Admin tab. They provide default settings for tools registered by URL within courses. These settings may include a consumer-wide key and secret. When naming a domain any protocol, port number or query string are removed. A domain name may, however, include a path. When matching a launch URL against the list of registered domains, the longest match is selected over shorter ones. For example, if domains of "www.ltiapps.net" and "www.ltiapps.net/webpa" have been registered, then:

All tools registered in a content item by entering a launch URL must have a matching domain for a connection to be made. A typcial use case for domains would be:

  1. obtain connection details from a tool provider
  2. register the tool provider domain including the consumer key and secret
  3. within a course, add a content item, select the "By URL" tab, enter a name and the launch URL, submit the form

In this case, the instructor only needs to know the launch URL to add a link to the tool; the consumer key and secret from the domain are used on launch. If the domain has an icon URL, this icon will be used for launch URLs matching the domain.

A domain is either approved or denied; the latter means that it is blacklisted and any launch URLs which match the domain will not function.

Extension services

LTI 1.1 includes support for an Outcomes service which allows a tool provider to pass grades back to Learn 9. The Building Block also implements the unofficial extensions defined for Basic LTI; although these are not part of the formal IMS specification they are widely adopted by tool consumers and provide functionality of value to tool providers. Thus, the extensions available as part of this Building Block are:

These services are enabled for each tool on the tool configuration page (see above). It is not possible to enable/disable the services for individual instances of the tool.

Outcomes service

This service allows grades to be retrieved, updated and deleted from the Grade Centre. The following kinds of result value are supported (note that LTI 1.1 only includes the decimal type):

A column in the grade centre is automatically added when the first grade is added. The column will have a name of "BLTI" followed by the ID of the content item or the name of the tool (for a course tool). The column is assigned to a category named "Basic LTI" (which is automatically created if it does not already exist) and given the following setting values:

KindColumn typePoints possibleInclude in calculations?Visible to students?
decimalScore1NoNo
percentagePercentage100NoNo
ratioScoreSee belowNoNo
letterafLetter100NoNo
letterafplusLetter100NoNo
passfailTextNANoNo
freetextTextNANoNo

The points possible for a ratio-type value is the number following the "/" from the first update. If any subsequent grade is submitted with a different points possible, its value is adjusted to match the points possibel set for the column. For example, if a column is set up with a grade setting of "8/20", a subsequent grade update (for any student) of "12/15" will be adjusted to "16/20". Letter grades are converted to values based on the default grading schema set in Blackboard.

The result_resultscore_language, result_statusofresult, result_date and result_datasource parameters are ignored.

Note that this service is only available if it is selected on the tool configuration page and if user IDs are set to always be sent for the instance of the tool. The following error codes may be returned (as the codeminor XML element):

NB when using Learn 9.0, the column created in the Grade Centre is given a type of "Score" and should be changed manually to "Percentage", "Letter" or "Text" as required.

Memberships service

This service returns a list of enrolments for the course. The list will be a all users enrolled in the course unless the link to the tool is a content item which has been assigned to specific groups, in which case the list is restricted to all members of the selected groups and all instructors. If you wish to restrict the memberships list sent to the tool provider, it is important that the groups option on the settings page for a content item is used, rather than adding membership adaptive release rules. An option is also provided to limit the memberships list to those users able to view the link at that point in time; this list will also always include all instructors.

The memberships list may contain the following elements:

Note that this service is only available if it is selected on the tool configuration page and if user IDs are set to always be sent for the instance of the tool. The following error codes may be returned (as the codeminor XML element):

An additional message type has been added to the memberships service which adds group membership data to the service response. This option must be enabled on each tool registration page. It is also possible to limit the list of groups which are passed by specifying a name prefix or a regular expression. When specified, a group name must start with the prefix or match the regular expression to be included in the response.

Setting service

This service allows a value to be saved and retrieved for each instance of the tool added within Blackboard. The following error codes may be returned (as the codeminor XML element):

Troubleshooting

If you still experience problems, or have other issues, please report them via the discussion forum available in the project area on the OSCELOT projects site.

Version history

VersionDateDescription
1.0.09 February 2010First public release
1.1.02 August 2010Vendor ID changed to "osc"
Added support for Learn 9.1
1.1.17 August 2010Updated dependent utility
1.1.29 October 2010 Added support for resource_link_title, resource_link_description, tool_consumer_instance_url, tool_consumer_instance_description and launch_presentation_document_target parameters
Added support for return messages and log requests
Added options for opening tools in a new window or an iframe
Corrected name of lis_person_sourcedid parameter
Option to define a new tool producer via XML withdrawn
Improved exception handling when redirecting to a tool
Fixed names of LTI roles on system settings pages
1.2.017 September 2011Added support for outcomes, memberships and setting extension services
1.2.110 October 2011 Added ability to specify custom parameters for each instance of the tool, as well as for the tool configuration itself
Fixed error in the XML when returning data from the outcomes extension service
1.2.213 October 2011 Fixed bug which caused instances added as content items not to be orderable on a page
1.2.314 October 2011 ext_lms added to launch parameters; e.g. "learn-9.1.70081"
2.0.029 January 2012 Added support for LTI 1.1 (including Outcome service)
Added ability for instructors to register their own tool connections within a course
Updated user interface to separate settings into multiple pages
Improved handling of return links back into Learn 9 from a tool provider
Fixed iframe sizing issue when this option is used to display a tool provider
2.0.120 May 2012 Updated namespace for LTI 1.1 Outcome service
Added link to Basic LTI tools on Administrator Panel
Miscellaneous bug fixes with default values of tools
2.1.018 June 2012 Added support for domains, registering tools by URL and XML
Use tool icons on content pages
Added content item options to restrict availability to users (e.g. by date or group membership)
Added Basic LTI tool mashup option to visual text box editor
2.2.02 September 2012 Gradebook column names made the same as the content item title
Added option to place tools as a named menu item on a content page menus (Learn 9.1+ only)
Added option for adding LTI feeds to a module
Fixed support for Learn 9.0
2.2.16 September 2012 Fixed problem with links created using version 2.1.0
2.3.05 November 2012 Added option to place tools on the tools page in courses
Options provided to select the groups enhancement to the memberships service and to limit it to groups with matching names
Institution-level roles may be passed on launches from a module
Option provided to create the associated grade centre column immediately rather than when the first service request is received
2.3.117 December 2012 Fixed course copy issue for tools using Outomces service
Added grade column options for points possible, whether column is included in grade calculations and whether it is visible to students
Fixed session issue when launching tools from a module
2.3.23 April 2013 This release contains a fix to a security vulnerability - it is recommended that all users upgrade to this release
Allow instructors to defined tools by URL even when they are not permitted to create named tools (because such tools are managed via a domain setting)
The format used to render an RSS feed in a module has been changed to better use the Blackboard tag library
Fixed bugs when defining tools via XML
Fixed bug with separating custom parameter definitions on some platforms
3.0.030 October 2013 This is a major release based on the expected LTI 1.2 specification. It introduces extensible LTI services which can be discovered via the Tool Consumer Profile and includes an implementation of the proposed LTI 2 Tool Settings service
Tools may now be configured using XML obtained from a URL
Two new launch message types have been added: configure-launch-request and dashboard-request
3.0.15 November 2013 Fixed a bug with creating new system-level tools
Renamed new launch message types to ConfigureLaunchRequest and DashboardRequest
3.0.215 July 2014 Added support for April 2014 release of Learn 9.1
Removed support for Learn 9.0
A few minor UI bug fixes
3.0.329 July 2014 Fixed bug with adding service endpoints as custom launch parameters
3.0.422 December 2014 Added workaround for issue with October 2014 GA release - restart Learn 9 after installing with the October 2014 release
3.0.524 December 2014 Added further workaround for issue with October 2014 GA release - restart Learn 9 after installing with the October 2014 release
3.1.030 May 2015 Added support for Content-Item messages
Additional options for placement of LTI links including group tool, user tool, content editor
3.1.112 November 2015 A few bug fixes for processing Content-Item return messages, and additional log messages
Added a debug setting for increased message logging
3.2.017 January 2016 Added ability to define associated settings for services
Added registration option to allow tools to emulate launches made by core Learn 9 LTI functionality
Added option to allow domains to be defined using a regular expression
3.2.122 April 2016 Added ability to perform an LTI launch from a module when a splash screen is to be displayed (only for April 2014 release and later).
3.2.322 December 2016 Updated support for Content-Item message to comply with final version of specification
3.2.43 February 2017 Fixed course copy conflict with a bespoke building block.

Licence

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

Valid XHTML 1.0 Strict