🇨🇦 Canada Only Guide

This guide is only for Canadian schools who need to comply with Canadian data residency requirements. To view the worldwide version of this guide click here.

Who is this guide for?

• New or existing Hypothesis customers. If you are not yet a customer, please reach out to us here to talk with a member of Education team about using Hypothesis at your school.
• People with administrator-level access to their institution’s Blackboard instance

Upgrading an existing Hypothesis LTI 1.1 installation

If you are installing Hypothesis for the first time you can skip this section and begin at Register the Hypothesis LTI tool.

When the LTI 1.3 version of Hypothesis is installed in Blackboard, the existing LTI 1.1 tool will be upgraded and all previous Hypothesis assignments created with the LTI 1.1 version of the tool will use the new version of the tool.

To ensure that these previous Hypothesis assignments will continue to work properly after upgrading, we will need to know the LTI 1.1 consumer key of the previous Hypothesis tool before upgrading.

You can locate the consumer key, labeled by Blackboard as Tool Provider Key, from the Admin Panel under the info window for either Hypothesis LTI Tool Provider or Tool Placement

Copy this Consumer Key value into a temporary note or text document; you will need to refer to it later in the installation process.

Register the Hypothesis LTI tool

1. From the Administrator Panel, select “LTI Tool Providers” located under Integrations

2. Select the “Register LTI 1.3/Advantage Tool” link

3. Paste the following Hypothesis ID into the Client ID field

• Client ID:
  • fc08bd8b-2462-407d-825b-59e7a00abfba

Click the Submit button to continue.

4. If upgrading from the LTI 1.1 version you will be prompted to migrate to LTI 1.3

Click the OK button to continue.

5. Copy the “Deployment ID” to a temporary note or text file

You will need to supply this Deployment ID value to Hypothesis later in the installation process.

Scroll down the page to Tool Status.

6. Set the “Tool Status”  value to “Approved”

Scroll down the page to Institutional Policies.

7. Check that the following values are set under “Institutional Policies”

• User Fields to Send
  • ✓ Role in Course
  • ✓ Name
  • ✓ Email Address
• Allow grade service access
  • Yes
• Allow Membership Service Access
  • Yes

Click the Submit button to finish.

8. Confirm that the Hypothesis placement has been created

Locate Hypothesis in the list of LTI Tool Providers. Click the down arrow to the right of the name and select Manage Placements from the menu.

Confirm that you see Hypothesis listed as as Course Content placement. If not, you may need to click the Synchronize Placements button,

If you have upgraded from an existing LTI 1.1, rather than installing Hypothesis new, you will now see a second new placement alongside the the previous existing placement. You may safely delete the new placement while leaving the old placement untouched, ensuring that any assignments created using the old placement will continue to work.

Create REST API integration

Note: If you have an existing REST API integration for Hypothesis, you do not need to create a new integration for the LTI 1.3 tool. You can skip this section and continue to submit LTI details to Hypothesis to complete registration.

Though optional, creating a Hypothesis REST API integration allows Hypothesis to utilize Blackboard course groups and content collections. If you choose not to create a REST API integration, please let us know in the Notes field of the LTI Submission Form below.

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.

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']}

Submit LTI details to Hypothesis to complete registration

1. Gather the Deployment ID value, and (if upgrading) the LTI 1.1 consumer key value, previously copied during the above steps

You will be pasting these values into our form below.

2. Open our LTI 1.3 / Advantage Registration form

3. If upgrading, check the “Migrate from existing LTI 1.1?” box and enter the LTI 1.1 consumer key previously copied from above

4. Enter the following values into the form as shown

• Email
  • Your email address, or another address that you want associated with this registration
• LMS URL
  • Enter the web address of your Blackboard instance, e.g. https://blackboard.myschool.edu
• LMS
  • Select Blackboard from the drop-down menu
• Deployment ID
  • Enter the Deployment ID value previously copied from above
• Additional notes
  • If you are not using Hypothesis REST API integration, please indicate that with a note here

5. Click the “Submit” button to send your LTI info to Hypothesis

We will email the address you provided above when your registration has been processed and Hypothesis is ready to be used. We can’t wait to have you annotating!

Important note: Hypothesis will not be available to use in courses until you have received confirmation that we have processed your LTI instance.