Configuring Your Canvas API Integration in Harmonize

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.
• Rubrics - Allows instructors to select a rubric to use while grading directly from Harmonize.
• 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. 

• On the License Administration page, navigate to the 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.

• 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.

• On the License Administration page, navigate to the 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.

• Fill in the following values on the 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. To use this feature, select the following scopes:

• Rubrics
  • 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: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.
  
  

• 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:

• 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:
  
  

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.
    
    

• From here you may select which Canvas-specific features you'd like enabled. Features include Group Details, Section Details, Rubric Details, Assignment Details, and Calendar Syncing. Toggle the feature on to enable, toggle the feature off to disable.
  
  

• When you are finished, click Update.
• The features you selected are now available for instructors to utilize.

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.

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

• 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.