BasicLTI Building Block

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

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

The BasicLTI Building Block is written for Blackboard Learn 9.0 (or higher). It requires the Community System to be licensed for the Blackboard Learn server. It includes the following dependent Java library files:

• b2context.jar, release 1.1.00 (or higher)
• org.apache.commons.httpclient
• oauth-core.jar

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:

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

• clicking on the Basic LTI tools link (available on the Tools and Utilities module)
• clicking on the Settings button against the Building Block entry on the Installed Tools page from the Building Blocks link

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.

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.

Institution details

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.

Other options

This section can be used to enable the following options:

• allow roles to be mapped for any custom course roles; otherwise a custom course role will be treated as either an instructor or a teaching assistant depending upon whether it has been given the capability of "Treat Users with this Role as Instructor";
• allow avatar URLs to be sent to tool providers (avatars must also be enabled within Learn 9 as well before a tool can support avatars;
• allow instructors to add their own tool registrations in courses (in addition to having access to those defined by the system administrator).

Register a tool provider

Click on the Register New Tool button to register a new tool provider, this will display the Registration Settings page. Each tool should be given a unique ID comprising up to 6 characters (letters, digits, hyphens and underscores only). This will be used internally to identify the tool; the name entered is the value which is visible to users.

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.

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 "-" 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. Note that, at present, it is not possible to limit the list to those users to which the link has been assigned irrespective of whether, or not, it is currently visible to them (as a result of other adaptive release criteria).

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). When accessing the Basic LTI tools from the Course tools area, an icon is displayed against each tool name. The default icon used can be overridden by entering a URL to an alternative image in this section.

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

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

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:

• Instructor
• Content Developer
• Teaching Assistant
• Learner
• Mentor

This section detemines 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.

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.

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

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:

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.

Basic LTI tools can be made available within a course via either the Course tools page or as a comtent item added to a content page. 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.

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.

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.

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.

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:

• outcomes service (both LTI 1.1 and unofficial varieties)
• memberships service
• setting service

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

• decimal
• percentage
• ratio
• letteraf
• letterafplus
• passfail
• freetext

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:

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

• Invalid request - required parameters missing
• Invalid signature - request signature not verified
• Invalid action - invalid action name
• Action not available - requested action is not available
• Security check failed - an invalid sourcedid has been passed
• User not found - this may be caused by an unrecognised user ID or by the user not having access to Blackboard
• Invalid role - this may be caused by the user not being enrolled as a student or not having access to the course
• Grade Center error - a system error occurred
• Result value missing - no value is provided for an update request

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; note that this is always the full list of members for a course and is not limited to those who have access to the instance of the tool if, for example, it has adaptive release criteria associated with it. The list may contain the following elements:

• user_id - a user's database key, username, batch UID or student ID (depending upon the selected tool configuration setting)
• roles - a comma, separated list of roles for the user (including system administrator if this configuration setting has been selected for the tool)
• person_sourcedid - a user's sourcedid (if this tool configuration option has been selected)
• person_contact_email_primary - a user's email address (if this value has been selected to always be sent for the instance of the tool)
• person_name_given, person_name_family and person_name_full - a user's name (if this value has been selected to always be sent for the instance of the tool)
• lis_result_sourcedid - a unique value which is used by the tool consumer to identify the tool instance and user
• user_image - URL to a users avatar image (if enabled)

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

• Invalid request - required parameters missing
• Invalid signature - request signature not verified
• Invalid action - invalid action name
• Action not available - requested action is not available
• Security check failed - an invalid ext_ims_lis_memberships_id has been passed

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

• Invalid request - required parameters missing
• Invalid signature - request signature not verified
• Invalid action - invalid action name
• Security check failed - an invalid ext_ims_lti_tool_setting_id has been passed
• Setting value too long - setting values cannot exceed 2048 characters

If you are upgrading to a new version of this Building Block and get an error on first access, try deleting and re-installing it. Note that any existing settings are not lost when the Building Block is deleted. 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.

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.