API Resources

LTI Overview

Learning Tools Interoperability® (LTI®) is a specification developed by IMS Global Learning Consortium. LTI provides a standard way for a tool consumer (eg. Bridge) to communicate with a tool provider (eg. a tool you’ve built.) By using the LTI specification:

  1. Implementation consultants can add the tool to Bridge
  2. users can launch and use the tool within the Bridge
  3. the tool will receive the user’s identity for authentication and authorization
  4. all messages passed between Bridge and the tool are secured via OAuth

The tool provider will need to provide XML configuration. This can be done via a URL endpoint or copy/paste. Admins will use the XML to setup the tool within Bridge. See Sample XML Configuration for more details.

After the tool is configured, Bridge users will be able to launch it. Behind the scenes, Bridge sends an HTTP POST request to the tool provider. The request occurs in the Bridge user’s browser. The tool provider’s response is rendered in an iframe, within the Bridge application. See LTI Launch Data Provided for a list of parameters sent from Bridge to the tool provider.

Admins will also be able to select lti content items to be used as a learning object within a program. Once the LTI Content Item has been added to the program, a learner will be able to launch the content item as a learning item. For more details on this process see LTI Content Items in Programs.

Sample XML Configuration

The user can retrieve the tool’s XML configuration from a URL endpoint that you provide (recommended) or paste in the XML. Here’s an example configuration:

    <?xml version="1.0" encoding="UTF-8"?>
    <cartridge_basiclti_link xmlns="http://www.imsglobal.org/xsd/imslticc_v1p0"
      xmlns:blti="http://www.imsglobal.org/xsd/imsbasiclti_v1p0"
      xmlns:lticm="http://www.imsglobal.org/xsd/imslticm_v1p0"
      xmlns:lticp="http://www.imsglobal.org/xsd/imslticp_v1p0"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.imsglobal.org/xsd/imslticc_v1p0
                          http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticc_v1p0.xsd
                          http://www.imsglobal.org/xsd/imsbasiclti_v1p0
                          http://www.imsglobal.org/xsd/lti/ltiv1p0/imsbasiclti_v1p0p1.xsd
                          http://www.imsglobal.org/xsd/imslticm_v1p0
                          http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticm_v1p0.xsd
                          http://www.imsglobal.org/xsd/imslticp_v1p0
                          http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticp_v1p0.xsd">
      <blti:title>Example Tool Provider</blti:title>
      <blti:description>This is a Sample Tool Provider.</blti:description>
      <blti:launch_url>http://lti-tool-provider-example.herokuapp.com/messages/blti</blti:launch_url>
      <blti:extensions platform="bridgeapp.com">
        <lticm:options name="admin_nav">
          <lticm:property name="domain">lti-tool-provider-example.herokuapp.com</lticm:property>
          <lticm:property name="icon_url">http://lti-tool-provider-example.herokuapp.com/selector.png</lticm:property>
          <lticm:property name="privacy_level">public</lticm:property>
          <lticm:property name="selection_height">500</lticm:property>
          <lticm:property name="selection_width">500</lticm:property>
          <lticm:property name="text">Extension text</lticm:property>
        </lticm:options>
        <lticm:options name="custom_fields">
          <lticm:property name="program_id">$Bridge.program.id</lticm:property>
          <lticm:property name="course_id">$Bridge.course.id</lticm:property>
        </lticm:options>
        <lticm:options name="config">
          <lticm:property name="outcomes_enabled">true</lticm:property>
        </lticm:options>
      </blti:extensions>
    </cartridge_basiclti_link>

Placement Options

There are a few places within bridge where an lti tool can be launched. Please refer to the table below to see a list of placement options.

identifier launch roles description
learner_nav learner Placement within the learner navigation menu
admin_nav administrator Placement within the admin navigation menu
live_course_tabs administrator Placement in the admin overview for a live course for an administrator
editor_nav administrator Placement within the course media modal. This launches a content item selection request to allow inserting LTI Content Items into a course slide.
course_tabs administrator Placement in the admin overview for a course for an administrator
checkpoint_tabs administrator Placement in the admin overview for a checkpoint for an administrator
program_object administrator Placement within a program editor to allow the author to launch an LTI Content Item Selection Request to select an LTI Content Item to be used as a learning object within the program.
program_tabs administrator Placement in the admin overview for a program for the administrator

Placements can also be customized with these parameters:

  • text - tool’s name to display Bridge’s navigation menu or tooltips
  • icon_url - icon displayed next to the tool’s name
  • config.launch_in_new_tab - if true, specifies that the placement should be a simple link to an external page, rather than an LTI tool that launches in an iframe in Bridge

Here is an example of placing your tool in the admin and learner navigation with custom icons and text. You can add or remove placements like this to fit the needs of your tool.

    <blti:extensions platform="bridgeapp.com">
      <lticm:options name="admin_nav">
        <lticm:property name="icon_url">http://lti-tool-provider-example.herokuapp.com/selector.png</lticm:property>
        <lticm:property name="text">Admin Tool Example</lticm:property>
      </lticm:options>
      <lticm:options name="learner_nav">
        <lticm:property name="icon_url">http://lti-tool-provider-example.herokuapp.com/selector.png</lticm:property>
        <lticm:property name="text">Learner Tool Example</lticm:property>
      </lticm:options>
    </blti:extensions>

Here is an example of a placement that’s really just a link to an external page.

    <blti:extensions platform="bridgeapp.com">
      <lticm:options name="learner_nav">
        <lticm:property name="icon_url">https://www.google.com/images/branding/googleg/1x/googleg_standard_color_128dp.png</lticm:property>
        <lticm:property name="text">Google</lticm:property>
        <lticm:property name="url">https://google.com</lticm:property>
        <lticm:options name="config">
          <lticm:property name="launch_in_new_tab">true</lticm:property>
        </lticm:options>
      </lticm:options>
    </blti:extensions>

LTI Launch Data Provided

These parameters are sent from Bridge to the tool provider when a user launches the tool.

  • lti_message_type - set to basic-lti-launch-request for all launches except for the program_object placement, which will send ContentItemSelectionRequest
  • lti_version - set to LTI-1p2
  • resource_link_id - unique id referencing the link, or “placement”, of the app in the consumer
  • resource_link_description - description of the link that launched the app
  • user_id - unique id referencing the user accessing the app, providers should consider this id an opaque identifier
  • roles - either Administrator or Learner
  • lis_person_name_full - full name of user accessing the app
  • launch_presentation_document_target - set to iframe
  • tool_consumer_info_product_family_code - set to Bridge
  • tool_consumer_instance_name - name of the instance from which the user is accessing the app
  • tool_consumer_instance_url - url of the instance from which the user is accessing the app
  • tool_consumer_instance_contact_email - email address of a contact at the instance from which the user is accessing the app.

You can optionally receive custom fields for certain launches by specifying options within the XML Configuration. The identifier specifies which data point you wish to receive, while the name specifies the name by which the value will be returned when the tool is launched. Names will have custom_ prepended to the name when supplied on launch. Here is a table of information you can receive:

identifier example name return parameter description
$Person.email.primary person_email custom_person_email the email of the user launching the tool or content item
$Person.name.full person_name custom_person_name the name of the user, if the user has a name specified. Otherwise, the uid of the user
$User.image user_image custom_user_image the url of the user image if present
$Bridge.user.loginId user_uid custom_user_uid the uid of the user launching the tool or content item
$Bridge.program.id program_id custom_program_id the program that is launching the tool or content item
$Bridge.course.id course_id custom_course_id the course that is launching the tool
$Bridge.liveCourse.id live_course_id custom_live_course_id the live course that is launching the tool
$Bridge.ltiContentItem.id lti_content_item_id custom_lti_content_item_id the link item that is being launched
$Config.resource_link_id resource_link_id custom_resource_link_id the generated resource link id that will be used for the LTI Content Item returned from the content item selection request. This is only sent in the content item selection request to a program_object placement that has the generate_resource_link_id config value set

Here is example XML to include in your XML Configuration to receive the program id and course id when your tool is launched from those items:

    <lticm:options name="custom_fields">
      <lticm:property name="program_id">$Bridge.program.id</lticm:property>
      <lticm:property name="course_id">$Bridge.course.id</lticm:property>
    </lticm:options>

LTI Content Items in Programs

LTI Content Items can be used as a learning item in a program within Bridge. There are two parts to this process: 1. an administrator can select and add a content item to a program 2. a learner can complete the content item as a learning item in a program We support LTI Content Items with a content item type of LtiLinkItem and a presentationDocumentTarget of iframe.

Adding a content item to a program

To allow an administrator to add a content item to a program, include configuration for a program_object placement in the XML Configuration. This will add an icon in the program edit flow for the administrator. When the administrator clicks on the icon, it will launch the tool with a LTI launch type of ContentItemSelectionRequest. When a user selects a content item, the tool should return a ContentItemSelection message.

Taking a content item as a learning item

When taking a program, a learner will be able to launch a content item as a learning item within the program. This will launch the item with a basic lti launch in an iframe. Once the user is finished with the content item, they will be able to click a button above the launch to complete the content item.

Launching a content item as an administrator

On the program overview screen, a tab can be added which contains a list of LTI Content Items from the tool in the program. When clicking on an item in the list, the LTI Content Item will be launched as an administrator. This can be useful for things like grading or admin overviews.

For the tab to be visible, a few things need to be in place: 1. the program_object placement must have the admin_launch_list_tab_title configuration variable set. This specifies the title of the tab. 2. the program must contain at least one LTI Content Item from the tool 3. the user must have permissions on Bridge to launch LTI Content Items as an administrator

Here is an example placement configuration to allow LTI Content Items to be launched as an administartor:

    <blti:extensions platform="bridgeapp.com">
      <lticm:options name="program_object">
        <lticm:property name="icon_url">http://lti-tool-provider-example.herokuapp.com/selector.png</lticm:property>
        <lticm:property name="text">Program Object Placement Example</lticm:property>
        <lticm:options name="config">
          <lticm:property name="admin_launch_list_tab_title">Example Tab Title</lticm:property>
        </lticm:options>
      </lticm:options>
    </blti:extensions>

Generating resource_link_id for content item selection

Occasionally a tool provider may want to know the resource_link_id of an LTI Content Item during the content item selection request instead of waiting for the content to be launched after it has been added to Bridge. This can be achieved by setting the generate_resource_link_id config variable in the program_object placement config and then retrieving the result from the custom variable $Config.resource_link_id. Here is an example xml snippet showing how this can be achieved:

    <blti:extensions platform="bridgeapp.com">
      <lticm:options name="program_object">
        <lticm:property name="icon_url">http://lti-tool-provider-example.herokuapp.com/selector.png</lticm:property>
        <lticm:property name="text">Program Object Placement Example</lticm:property>
        <lticm:options name="config">
            <lticm:property name="generate_resource_link_id">true</lticm:property>
        </lticm:options>
      </lticm:options>
      <lticm:options name="custom_fields">
        <lticm:property name="resource_link_id">$Config.resource_link_id</lticm:property>
      </lticm:options>
    </blti:extensions>

In this example, when the content item selection request is launched, it will include a custom_resource_link_id value which will specify the resource_link_id that the LTI Content Item will launch with once it has been added to Bridge.

Enabling LTI Basic Outcomes

Using LTI outcomes, tool providers may send learner scores to Bridge. By default, an LTI tool will not accept score data, but can be setup to receive score data at configuration. Below is an xml snippet showing how to enable basic outcomes for a tool:

      <blti:extensions platform="bridgeapp.com">
        <lticm:options name="config">
          <lticm:property name="outcomes_enabled">true</lticm:property>
        </lticm:options>
      </blti:extensions>

OAuth Signature

All messages sent between Bridge and the tool provider are signed with an OAuth signature. Before any messages are sent, Bridge and the tool provider must agree on a consumer key and shared secret. The consumer key is used for identification and the secret for securely signing every request.

The steps involved when Bridge sends a request:

  1. form HTTP request with LTI Launch Data
  2. sign the request using the consumer key and shared secret
  3. POST request to the tool provider

The steps involved when the tool provider receives a request:

  1. receive an HTTP POST request
  2. verify the signature using the OAuth signing process, if the signature is invalid then no information should be trusted
  3. authorize the current user using the launch data provided by Bridge
  4. launch the tool or resource, many services require an additional registration step the first time a user launches its app

Additional Resources