Configuring Your Canvas API Integration in Harmonize

  • Updated

Overview

 

Harmonize offers additional features to Canvas users via an API integration! These features go beyond Canvas's standard LTI offering, so they require an additional scoped Developer Key to be installed and specific permissions enabled. Currently, this integration grants access to the following Harmonize features:

  • Group Syncing - Improves group discussions by selecting a specific group set from the course. 
  • Section Syncing - Allows instructors to filter their view of discussions by individual section.
  • Harmonize Rubrics - Allows instructors to auto-generate rubrics based on their Harmonize discussion prompts.
  • Assignment Dates - Allows instructors to set availability and due dates for assignments directly from Harmonize.
  • Calendar Syncing - Allows Harmonize Milestone Due Dates to appear in the Canvas Course Calendar.

 

Please note that all of the following steps are required to fully configure this integration. If you are running into issues, please open a ticket with Harmonize Support.

 

Accessing Your Harmonize License Administration Page

 

Note: The steps below require a login with admin access to the root account in Canvas.

 

There are two ways to accessing your Harmonize License Administration Page: through the Harmonize Communication Center and through the Canvas App Configurations.

 

From the Harmonize Communication Center

 

  • Visit any course currently using Harmonize.
  • Navigate to the Harmonize Communication Center or open an existing Harmonize discussion within the course.
  • Click the menu icon located in the top right of the Harmonize window and select License Administration from the drop down menu. This will open the License Administration page in a new browser tab. 

 

Harmonize Navigation menu with “License Administration” selected.

 

  • On the License Administration page, navigate to the Canvas API Administration section.

 

Screenshot of Canvas API Administration section.

 

From Canvas App Configurations

 

  • Navigate to an account where Harmonize is installed, then click the Settings link from the Canvas navigation menu.
  • Select the Apps tab, then click the View App Configurations button.

 

Canvas settings menu with Apps tab selected and an arrow pointing to View App Configurations. width=

 

  • Find Harmonize on the list of External Apps, then click the Configurations button located on the right app title (the  "gear" icon).
  • Select Configure from the drop down menu that appears. This will open the Harmonize License Administration page.

 

External apps tab with gear menu selected for Harmonize row. Arrow pointing to configure.

 

  • On the License Administration page, navigate to the Canvas API Administration section.

 

Harmonize License Administration Page Canvas API Administration Section

 

Creating a Harmonize Sync API Key in Canvas

 

  • In a separate browser tab or window, navigate to Admin page of your Canvas root account.
  • Click the Developer Keys link in the left side navigation menu.
  • Click the + Developer Key button located on the top right of the page and select + API Key. This will open a new Key Settings page.

 

Canvas Developer Keys Page Add API Key Option

 

  • Fill in the following values on the Key Settings page:

 

Screenshot of key settings page.

 

  • Key Name: Copy the Key Name value from your Harmonize License Administration page
  • Redirect URIs: Copy the Redirect URI value from your Harmonize License Administration page
  • Icon URL: Copy the Icon URL value from your Harmonize License Administration page
  • Enforce Scopes: Set to enabled
  • Allow Include Parameters: Check this box

 

Enforcing Scopes

 

Select scopes based on the features you want to enable. Click the name of each feature for more information.

    

Groups Syncing: Improve group discussions by selecting a specific group set from the course. To use this feature, select the following scopes:

  • Group Categories
    • url:GET|/api/v1/courses/:course_id/group_categories

  • Groups
    • url:GET|/api/v1/courses/:course_id/groups
    • url:GET|/api/v1/groups/:group_id/memberships

Sections Syncing: Allow instructors to filter their view of discussions by individual section. To use this feature, select the following scopes:

  • Sections
    • url:GET|/api/v1/courses/:course_id/sections

Rubrics: Select a rubric to use while grading directly from Harmonize. Additionally, starting in Spring 2024 instructors will be able to auto-generate rubrics based on their Harmonize discussion prompts! Visit Auto-Generated Rubrics for more information.

 

To use the Rubrics feature, select the following scopes:

  • Rubrics
    • url:POST|/api/v1/courses/:course_id/rubrics
    • url:PUT|/api/v1/courses/:course_id/rubrics/:id
    • url:DELETE|/api/v1/courses/:course_id/rubrics/:id
    • url:GET|/api/v1/courses/:course_id/rubrics
    • url:GET|/api/v1/courses/:course_id/rubrics/:id
    • url:POST|/api/v1/courses/:course_id/rubric_associations
    • url:PUT|/api/v1/courses/:course_id/rubric_associations/:id
    • url:DELETE|/api/v1/courses/:course_id/rubric_associations/:id

 

Assignment Dates: Set availability and due dates for assignments directly from Harmonize. To use this feature, select the following scopes:

  • Assignments
    • url:GET|/api/v1/courses/:course_id/assignments
    • url:GET|/api/v1/courses/:course_id/assignments/:id
    • url:PUT|/api/v1/courses/:course_id/assignments/:id

Calendar Syncing: Allows students and instructors to sync To Do items in Harmonize to their individual Canvas Calendars.

  • Calendar Events
    • url:GET|/api/v1/calendar_events
    • url:POST|/api/v1/calendar_events
    • url:PUT|/api/v1/calendar_events/:id
    • url:GET|/api/v1/calendar_events/:id
    • url:DELETE|/api/v1/calendar_events/:id

  • Click Save. Canvas will save the new API Key and close the Key Settings window.
  • On the Developer Keys page, find the row for the newly created API Key and click the ON button.

Screenshot of API Key toggled on.

 

  • Keep this browser tab open! Information from this page is needed to complete the setup.

 

Adding Your Harmonize Sync API Key to Your Harmonize License Administration Page

 

  • In the browser tab with your Harmonize License Administration page, navigate to the Canvas API Integration section located under Platform Specific Extensions.
  • Enter the following values:

 

Canvas API Integration with API Base URL, Client ID, Client Secret, and Add selected.

 

  • API Base URL: Enter the URL of your Canvas instance (ie. https://school.instructure.com. Canvas Vanity URLs will also work here.)
  • Client ID: In the browser tab with your Canvas Developer Key page, copy the value in the Details column of the Harmonize Sync API Key you just created. Paste this value in the Client ID field.
  • Client Secret: In the browser tab with your Canvas Developer Key page, click the Show Key button located below the Client ID in the Details column of the Harmonize Sync API Key. Copy this value and paste it into the Client Secret field.

  • When you're done, click Add.
  • You'll now see a new row on the License Administration page that looks like this:

Harmonize Canvas API Integration Details

 

Enabling Features

 

  • On the Harmonize License Administration Page, scroll down to the Platform Specific Extensions section.
  • In the Canvas API Integration section, click the Edit icon located in the Action column.
  • Click Select Features.
    • Note: To delete the Canvas API Integration, click Delete.

Harmonize Canvas API Integration Details Action Menu

 

Select features menu showing options: group, section, rubric, and assignment details. Update button highlighted.

 

  • When you are finished, click Update.

 

  • You will then prompted to Enable Canvas Features. Enabling Canvas features as an admin will add an Admin Token to your Canvas API Integration which allow the selected features to run for any course using Harmonize, even if an instructor has yet to access the course. This will help reduce the amount of time before essential syncing occurs for things like assignment dates and course calendar entries.

 

  • Click Enable Canvas Features.

 

Enable Canvas Features popup.

 

  • A new tab will open and Canvas will prompt you to authorize Harmonize. Click Authorize.

 

Harmonize sync popup with Authorize selected.

  • NOTE: If you are presented with an Authorization Error during this step, it means a required scope was overlooked during the API key creation process. Revisit the Creating a Harmonize Sync API Key in Canvas and Enforcing Scopes sections of this help guide to ensure all listed scopes have been enforced. Once all of the proper scopes have been selected, return to the Enabling Features step and try again.

 

  • If successful, the Canvas authorization window will close automatically and you will be returned to your Harmonize License Administration Page. Your Admin Token has been added to your Canvas API Integration and the features you selected are now available for instructors to utilize.

 

Adding Additional Admin Tokens to Harmonize

 

When new features are configured and enabled in your Canvas API integration, you will be prompted to Enable Canvas Features. See the previous section, Enabling Features, for more details. You may also want to add additional Admin Tokens to your API integration after features have been enabled. To do so:

 

  • Navigate to the Canvas API Integration section of your Harmonize License Administration Page.
  • The current number of Admin Tokens is listed in the Admin Tokens column.
  • Click the Action menu and select Authorize as Admin from the drop down list.

 

Harmonize License Administration page with action menu open and Authorize as Admin selected.

 

  • You will be prompted to Enable Canvas Features. Click the Enable Canvas Features button.

 

Enable Canvas Features popup.

 

  • A new tab will open and Canvas will prompt you to authorize Harmonize. Click Authorize.

 

Harmonize sync popup with authorize selected.

 

  • You have successfully added your Admin Token to Canvas API features integration.
    • A green banner will appear at the top of the page confirming that you have successfully enabled the Canvas API features for this account.
    • The number of Admin Tokens has increased by one.
  • If you see a red banner stating "You have already enabled the Canvas API features for this account", it means that you have already authorized your Admin Token. No further action is required.

 

Confirming Successful Configuration

 

  • Ensure you've completed all of the steps outline above.
  • Navigate to a course (preferably non-live, test, or sandbox course) and Create a Graded Harmonize Discussion.
  • On the Harmonize Edit Topic page, click the blue "Authorize Canvas Extensions" button.

 

Harmonize Edit Topics page with Authorize Canvas Extensions selected.

 

  • In the new browser tab or window that appears, click the Authorize button.

 

Canvas Authorize Access Form

 

  • The tab or window will close and return you to the Harmonize Edit Topic page.
  • Your Canvas API Integration has been properly configured!

 

Frequently Asked Questions

 

Q. Why am I receiving an error when I click the "Authorize Canvas Extensions" button?

  • Receiving an error when attempting to Authorize Canvas Extensions usually means a scope was missed during the setup process. Revist the Enforcing Scopes section of this article. After confirming that all scopes are properly selected, please retry the authorization.

 

Q. How often will instructors need to Authorize Canvas Extensions?

  • Canvas Extensions will need to be authorized once per unique course.

 

 

 

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request