Adding Harmonize to Canvas with LTI 1.3

Overview

The instructions below describe how to add Harmonize to your Canvas instance via LTI 1.3. This is the latest LTI specification offered by IMS Global and offers a number of improvements over LTI 1.1.

Adding Harmonie to Canvas is a 5 step process:

• Step 1: Create your Harmonize LTI Key
• Step 2: Create and configure your Harmonize Sync API Key.
• Step 3: Send your installation information to Harmonize Support.
• Step 4: Add Harmonize to the root, sub-account(s), or course(s) of your choosing.
• Step 5: Add Admin Tokens to Harmonize

Important Note: Adding Harmonize to Canvas via LTI 1.3 requires a Canvas Administrator user with access to the root account. All steps are required for a full Harmonize installation.

Step 1: Create Your LTI Key

Once you've received an installation email from Harmonize Support, please follow these instructions. Be sure to keep the installation email handy! You will need the values provided therein.

• Log into your Canvas instance as an Administrator with access to the root account.
• Click on the Admin menu and select the root account.
• In the navigation list, select Developer Keys.

• Click the + Developer Key button and select + LTI Key.

• You will see the Key Settings page:

• Enter the following values:
  • Method - Choose Enter URL from the drop down menu
  • Key Name - Harmonize
  • Redirect URIs - This is the "Redirect URI" provided by Harmonize Support; check your "Harmonize Setup in Canvas" installation email
  • JSON URL - This is the "Config URL" provided by Harmonize Support; check your "Harmonize Setup in Canvas" installation email
• Click Save.
• On the Developer Keys page, a new row will be added named Harmonize.

• In the State column, toggle the LTI key from OFF (gray x) to ON (green check mark).

• Note the Client ID located in the Details column just above the Show Key button.

• This is your LTI Key Client ID. It is one of the pieces of information you will need to send to Harmonize Support in Step 3. For now, however, move on to Step 2: Configuring Your Canvas API Integration.

Step 2: Create and Configure Your Canvas API Integration

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

• Navigate to the 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.

• You will see the Key Settings page:

• Enter the following values:
  • Key Name: Provided by Harmonize Support; check your "Harmonize Setup in Canvas" installation email
  • Redirect URIs: Provided by Harmonize Support; check your "Harmonize Setup in Canvas" installation email
  • Icon URL: Provided by Harmonize Support; check your "Harmonize Setup in Canvas" installation email
  • Enforce Scopes: Set to enabled
  • Allow Include Parameters: Check this box

Enforcing Scopes

Select the scopes listed below. 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.

Accessing API Key and Secret

• On the Developer Keys page, find the row for the newly created Harmonize Sync API Key.
• In the State column, toggle the LTI key from OFF (gray x) to ON (green check mark).

• Note the Client ID located in the Details column just above the Show Key button.
• This is your Harmonize Sync API Key Client ID. It is one of the pieces of information you will need to send to Harmonize Support in Step 3.

• In the Details column, click the Show Key button located below your Harmonize Sync API Key Client ID. 
• This is your Harmonize Sync API Key Client Secret. It is one of the pieces of information you will need to send to Harmonize Support in Step 3.

• Move on to Step 3.

Step 3: Send Your Installation Information to Harmonize Support

Please send the following information to Harmonize Support (support@harmonizelearning.com). You may reply to the initial installation email you were sent or use a secure service of your choosing.

From Your Harmonize LTI Key

• Client ID
• The URL of your Canvas instance (i.e. https://yourschool.instructure.com)

From Your Harmonize Sync API Key

• Client ID
• Client Secret

Once you've received a confirmation email from the Harmonize Support team, move on to Step 4. 

Step 4: Setting Harmonize Availability in Canvas

Canvas provides a page, called Apps, that allows you to control which accounts and courses Harmonize is available in. To get there, navigate to the root account in Canvas, look for Apps in the left-hand navigation and click on it.

• On the Apps page, select the middle tab labeled Manage. In the search field, type Harmonize and click on the Harmonize app listing.

• On the configuration page for Harmonize, make sure the Availability and Exceptions tab is selected.  You should see the root account in Canvas listed with Harmonize set to Not Available.

From here, there are a few different options you can take based on where you'd like to make Harmonize available.

Make Harmonize Available in All Accounts and Courses

If you'd like to make Harmonize available in all accounts and courses, the easiest way to do so is by setting availability in the root account.

• First, click on the pencil icon for the root account listing:

• Next, set the availability to Available and click Save.

Make Harmonize Available to Select Sub-Accounts or Courses

If you would like to limit availability of Harmonize to select sub-accounts and/or courses, click the Add Exception button.

Next, in the Add Availability and Exceptions dialog, you can search for the desired sub-accounts and/or courses by typing their names in the search bar. You can also browse the account tree by clicking the button with a tree icon on the far right.

For each sub-account and course selected, set the availability to Available. Once your selections are complete, click the Save button.

Make Harmonize Unavailable to Select Sub-Accounts or Courses

In the same way that you were able to make Harmonize available to select sub-accounts and/or courses, you can likewise make Harmonize unavailable. For example, let's say that Harmonize should generally be available to all courses in the Foreign Languages department but there is a specific course that should not use Harmonize. You can set the sub-account to Available and the course to Not Available.

It should be noted that you can always update the availability at any time. Updating availability does not modify any existing Harmonize content in courses, though changes could affect the ability to access those resources.  If you have any questions about what availability setup is best for Harmonize at your institution, feel free to reach out to our Support Team and they'd be happy to help you with your configuration.

Step 5: Adding Backup Tokens to Harmonize

Now is a great time for you to Enable Features in your Harmonize Sync API key. 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.  For the sake of redundancy, we encourage multiple administrators to complete this step. This will help ensure the Harmonize features continue to run smoothly in your courses. 

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

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

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

• 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 Step 2: Create and Configure Your Canvas API Integration section of this help guide to ensure all listed scopes have been enforced. Once all of the proper scopes have been selected, return to Step 5: Adding Admin Tokens to Harmonize and try again.
• If successful, the Canvas authorization window will close automatically and you will be returned to your Harmonize License Administration Page.
  • 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.
• Your Admin Token has been added to your Canvas API Integration and the features you selected are now available for instructors to utilize.
• Repeat this process with any number of Admins that you see fit. If the Admin sees a red banner stating "You have already enabled the Canvas API features for this account", it means they have already authorized their Admin Token. No further action is required.

Step 6: Increasing the Width of Harmonize

Canvas currently requires LTI tools like Harmonize to load within a standard iframe. While Harmonize cannot be forced to load outside of this iframe, there are two optional settings that may help Harmonize display at a wider width in Canvas.

Remove the Harmonize Selection Width

First, you can remove the Selection Width value from your Harmonize LTI Key. This allows Harmonize to use the full width of the iframe Canvas provides.

• Log into your Canvas instance as an Administrator with access to the root account.
• Click on the Admin menu and select the root account.
• In the navigation list, select Developer Keys.
• Locate your Harmonize LTI Key.
• In the Actions column, click the Edit this key button, which appears as a pencil icon.

• On the right side of the page, under Configure, scroll down to Additional Settings.
• Click the arrow to expand Additional Settings.
• Locate the Selection Width field.
• Remove the existing value of 800 and leave the Selection Width field blank.
• Click Save.

• Harmonize will now be able to load into the full width of the Canvas iframe.

Please note that this setting does not force Harmonize to extend across the entire Canvas page. It only allows Harmonize to use the full width of the iframe Canvas provides. The overall width of the iframe itself is controlled by Canvas.

Enable Full Width Everywhere in Canvas

Canvas currently offers a Feature Option called Full Width Everywhere, which allows Canvas pages to use the full screen width. Enabling this feature will allow the Canvas iframe, including the Harmonize content inside it, to extend across more of the page.

IMPORTANT NOTE: The Full Width Everywhere feature option changes Canvas views across the account, not just Harmonize content. We recommend reviewing your usual Canvas course items to confirm this view works well for your staff and students.

• Log into your Canvas instance as an Administrator with access to the root account.
• Click on the Admin menu and select the root account.
• In the navigation list, select Settings.
• Click the Feature Options tab.
• Scroll down to Full Width Everywhere.
• Click the icon on the far right to enable the feature. (The icon will change from a red X inside of a red circle, which indicates Disabled, to a white checkmark inside of a green circle, which indicates Enabled.)

• The next time you open a Harmonize assignment, Harmonize should fill the full width of the Canvas iframe, and the Canvas iframe should extend across the full width of the page.

To disable Full Width Everywhere, return to the Feature Options tab and click the Enabled icon to change it back to Disabled.

Next Steps

Ready to use Harmonize? Check out these links:

• Configuring Your Harmonize Turnitin Integration
• Creating Graded Harmonize Discussions in Canvas
• Getting Started with Harmonize - Instructor Help Guide
• Harmonize Virtual Training Series