Installing Hypothesis in Canvas – LTI 1.3 (Worldwide)

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 Create new Hypothesis LTI Key.

When the LTI 1.3 version of Hypothesis is installed at the root, sub-account, or course-level, all previous Hypothesis assignments created with the LTI 1.1 version of the tool at that same install level 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 tools before upgrading. If you have multiple LTI 1.1 installations of Hypothesis, such as with several separate course-level or sub-account installations, we need the consumer keys from each of these instances.

Locate the LTI 1.1 consumer keys

1. Navigate to the appropriate course, sub-account, or root level where Hypothesis is currently installed
2. From the left sidebar menu, click Settings, then select the Apps tab
3. Click the View App Configurations button
4. From the list of external apps locate Hypothesis
5. Click the gear icon to the right of Hypothesis and select Edit
6. In the Edit App window, locate the Consumer Key and copy the string into a temporary note or text document; you will need to refer to it later in the installation process.
   
7. We also recommend adding a note to the Description field indicate that this app is the old LTI 1.1 instance.

Create new Hypothesis LTI Key

1. Navigate to “Admin” > “Developer Keys”, click on the “+Developer Key” button, and select the “+LTI” option

2. On the Key Settings page configure the following

• Method
  • Enter URL

• JSON URL
  • https://lms.hypothes.is/canvas/1.3/config

• Key Name
  • Hypothesis

• Owner Email
  • Enter an appropriate email address

• Redirect URIs (make sure there are no extra spaces or characters copied and pasted here)

  • https://lms.hypothes.is/lti_launches
    https://lms.hypothes.is/content_item_selection

Click the Save button to save the LTI key.

3. Check if the LTI service needed for fetching course roster is enabled

1. Under the Actions column of the newly created Hypothesis LTI key, click Edit this Key. This will open the Key Settings window.
2. On the Key Settings window, expand LTI Advantage Services.
3. Look for the service ‘Can retrieve user data associated with the context the tool is installed in.’ Make sure that this service is enabled. This service enables the Hypothesis tool to fetch the roster within the course. Note that Canvas typically enables this by default.

   

    

4. Click Save.

4. Locate the new Hypothesis LTI Key in the list of Developer Keys and do the following

1. Copy the string of numbers shown in the Details column. This is the Hypothesis Client ID.
2. Paste the Client ID into a temporary note or text document; you will need to refer to it later in the installation process.
3. Click the On button located in the State column to enable the Hypothesis LTI key.

Create new Hypothesis API Developer Key

Note: If you have an existing API Developer Key created for the LTI 1.1 Hypothesis tool, you do not create a new key. Instead, make note of the existing API Developer Key’s ID and Key values and skip to step 5 below.

Creating a Hypothesis Developer Key is highly encouraged, and enables the following deeper integrations with Canvas:

• Access to Canvas Files for documents
• Integration with Canvas Groups
• Integration with Canvas Sections

Note that the Hypothesis Developer Key will be tied to the Hypothesis LTI Key. If the Developer Key is ever deleted the old Hypothesis LTI Key will no longer work and a new LTI key will need to be created.

1. From the “Admin” > “Developer Keys” page, click the “+ Developer Key” button, then click “+ API Key”

2. Under Key Settings, enter the following values

• Key Name:
  • Hypothesis

• Owner Email:
  • Enter an appropriate email address

• Redirect URIs (make sure there are no extra spaces or characters copied and pasted here):

  • https://lms.hypothes.is/canvas_oauth_callback
    https://lms.hypothes.is/module_item_launch_oauth_callback

• Redirect URI (Legacy):
  • leave blank

• Vendor Code (LTI 2):
  • leave blank

• Icon URL:
  • https://d242fdlp0qlcia.cloudfront.net/uploads/brand/HypothesisCanvasIcon.png

3. (Optional) If your institution enforces Scopes on Developer Keys, configure the following

1. Click the switch to Enforce Scopes and check the box to select Allow include parameters.
   
2. Enable the following 9 API endpoints (organized by category):
   
   • Courses
     • url:GET|/api/v1/courses/:id (3rd endpoint from top)
     • url:GET|/api/v1/courses/:course_id/users/:id (13th endpoint from top)
   • Files
     • url:GET|/api/v1/courses/:course_id/files (1st endpoint)
     • url:GET|/api/v1/courses/:course_id/folders (2nd endpoint from top)
     • url:GET|/api/v1/files/:id/public_url (27th endpoint from top)
   • Group Categories
     • url:GET|/api/v1/courses/:course_id/group_categories (5th endpoint from top)
     • url:GET|/api/v1/group_categories/:group_category_id/groups (9th endpoint from top)
   • Groups
     • url:GET|/api/v1/courses/:course_id/groups (10th endpoint from top)
   • Sections
     • url:GET|/api/v1/courses/:course_id/sections (1st endpoint)
   • Pages
     • url:GET|/api/v1/courses/:course_id/pages  (6th endpoint)
     • url:GET|/api/v1/courses/:course_id/pages/:url_or_id  (8th endpoint)
3. Click the Save Key button in the lower right corner to finish

4. Locate the new Hypothesis API Developer Key in the list and click the “On” button to enable

5. Make note of the following Hypothesis API Developer Key values

The ID (shown in the Details column) and Key (shown in a pop-up once you click the Show Key button) will correspond to the API Developer Key ID and API Developer Key Secret fields in our form to which you will submit to Hypothesis later in the install process.

Copy both these values to the temporary note or text file used previously.

Install the Hypothesis App

1. With the appropriate account, sub-account, or course loaded, navigate to “Settings” > “Apps”, and click on the “View App Configurations” button

2. Click the “+ App” button

3. In the “Add App” pop-up window, select and configure the following

• Configuration Type
  • By Client ID
• Client ID
  • Refer to the temporary note or text file used previously, and paste in the Client ID copied earlier from the Hypothesis LTI key

Click the Submit button to continue.

4. Canvas will recognize the Client ID and ask if you would like to install Hypothesis

Click the Install button to install Hypothesis.

5. Locate Hypothesis in the list of Apps, click the Gear button at the far right, and select “Deployment ID”

6. Copy the Hypothesis Deployment ID shown in the pop-up window

Paste this Deployment ID into the same temporary note or text file used previously.

Click the Close button to close the pop-up window.

Submit LTI details to Hypothesis to complete registration

1. Gather the text document that you copied LTI values into during the above steps

You should have values for the following:

• (If upgrading) Previous LTI 1.1 consumer key
• Client ID
• API Developer Key ID
• API Developer Key secret
• Deployment ID

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(s) 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 Canvas instance, e.g. https://myschool.instructure.com
• LMS
  • Select Canvas from the drop-down menu
• Client ID
  • Enter the Client ID value previously copied from above
• API Developer Key ID
  • Enter the API Developer Key ID value previously copied from above
• API Developer Key Secret
  • Enter the API Developer Key Secret value previously copied from above
• Deployment ID
  • Enter the Deployment ID value previously copied from above

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.