Installing the Hypothesis LMS app for Blackboard: Administrator Guide – LTI 1.1 (Worldwide)

This guide is for schools without specific data residency requirements. For compliance with Canadian data residency requirements please see the Canadian version of this guide.

Who is this guide for?

• This guide is for people with administrator-level access to their institution’s Blackboard instance.
• If you are a Blackboard user and do not have administrator access and want to use Hypothesis in an assignment, please see our article on Creating Hypothesis-enabled readings in Blackboard.
• Are you having trouble getting Hypothesis installed in Blackboard? Please contact us!

Before you install Hypothesis you may wish to review the LTI parameters we use. You can find them here.

1. Generate Hypothesis Credentials

These instructions assume that you have already spoken with a member of our Education Team and been provided with a link to the page where you can generate Hypothesis credentials.

If you have not yet received a link, please fill out this form and a someone from our Education Team will get in touch with you about the next steps.

In the form to generate credentials, fill out the following:

• LMS Domain:
  • This is the basic web address instructors and students use to access your LMS (e.g., lms.yourschool.edu)
• Email:
  • Can be any valid email address that belongs to you

Note: Ignore the two Canvas-specific fields. Those are relevant only for use in Canvas LMS.

Click the Generate Credentials button.

You will be shown a screen that contains your new Hypothesis Consumer Key and Shared Secret.

Don’t close this tab/window! You will need to copy and paste these credentials later in the install process.

2. Create a new LTI Tool

Select “LTI Tool Providers” from the Integrations menu

On the next screen, select Register LTI 1.1 Provider.

Configure the Provider Domain

Under Provider Domain Status set the following:

• Provider Domain:
  • lms.hypothes.is
• Provider Domain Status:
  • Select Approved

Under Default Configuration set the following:

• Default Configuration:
  • Select Set globally
• Tool Provider Key and Tool Provider Secret:
  • Paste in the Consumer Key and Shared Secret respectively, as generated in Step 1 above.

Under Institution Polices set the following:

• Send User Data:
  • Select Send user data only over SSL
• User Fields to Send:
  • Check to select Role in Course and Name
• Select No for the final two questions

Click the Submit button to save Hypothesis as a tool provider.

3. Create Placement Information

You should now see Hypothesis listed as a tool provider. On the row, next to “lms.hypothes.is” click the down arrow, and then select Manage Placements.

On the following screen, click the Create Placement button.

Under Placement Information set the following:

• Label:
  • Hypothesis
• Handle:
  • Hypothesis
• Availability:
  • Select Yes
• Type:
  • Select Course content tool
  • If you want to allow teachers to create gradable assignments, check Allows grading.
• Launch in New Window:
  • We recommend checking this box
• Icon:
  • You can download the Hypothesis icon here

Under Tool Provider Information set the following:

• Tool Provider URL:
  • https://lms.hypothes.is/lti_launches
• You should not need to re-enter the key and secret
• Custom parameters should be left blank

Click the Submit button to save Placement Information.

4. Set LTI Global Properties to allow grading

Note: If you do not want tool integration with the Blackboard grade book you can skip this step.

Return to the LTI Tool Providers page and click the Manage Global Properties button.

Under Feature Availability set the following:

• Allow configured tool providers to post grades:
  • Select Yes

Click the Submit button to save.

5. Create REST API integration

Though optional, we recommend configuring a REST API integration to allow advance integration features with Hypothesis. More information is available here.

Note: This integration requires Blackboard version 3700.13.0 or newer

Important: When you have completed the steps below, you will need to contact the Hypothesis Support team so we can enable the advanced Blackboard integrations for your school.

1. From the Blackboard Administrator Panel, locate “Integrations” and select “REST API Integrations”

2. Click the “Create Integration” button

3. Under “General Information” enter the following:

• Application ID:
  • 36a86b89-5df8-4746-aff6-90e023e67e2a
• Learn User:
  • The user you select  here does not require any specific role or permissions. We recommend creating a new Hypothesis-specific user with the Institution Role “Other” and the System Role “None” specifically for this implementation.
• End User Access:
  • Set to Yes
• Authorized To Act As User:
  • Set to Service Default

Click the Submit button to save the REST API integration

4. Contact Hypothesis to turn on the Blackboard integration features for your school

When you’re ready to have us turn on Hypothesis advanced Blackboard integrations please contact the Hypothesis Support team with the following information:

• Your institution name
• The Hypothesis Consumer Key you currently use in your Blackboard instance
  • You can copy this from the Blackboard Admin Panel under the info window for either Hypothesis LTI Tool Provider or Tool Placement
    
• Confirmation that you’ve completed the above steps to create a REST API integration within Blackboard for Hypothesis

Blackboard API Endpoints used by Hypothesis

The following is a list of the Blackboard API endpoints used by Hypothesis:

• Gather course content folders and files for the Hypothesis file browser:
  • /learn/api/public/v1/courses/uuid:{course_id}/resources
  • /learn/api/public/v1/courses/uuid:{course_id}/resources/{folder_id}/children
• Retrieve public URL of a Blackboard file:
  • /learn/api/public/v1/courses/uuid:{course_id}/resources/{file_id}?fields=downloadUrl
• List group sets in a course:
  • /learn/api/public/v2/courses/uuid:{course_id}/groups/sets
• List groups in a group set:
  • /learn/api/public/v2/courses/uuid:{course_id}/groups/sets/{group_set_id}/groups
• Check student group memberships when launching group assignments:
  • /learn/api/public/v2/courses/uuid:{course_id}/groups
  • /learn/api/public/v2/courses/uuid:{course_id}/groups/{group['id']}