How to Set Up Advanced Canvas Integration

It is best practice for a designated account to be created for the purpose of setting up the integration. An existing Canvas Administrator account can be used, but if those accounts are deactivated (ie., someone departs your organization), the integration will need to be reauthorized.

Setting Up the Advanced Canvas Integration

1. Create an account role within Canvas, specifying a set of permissions, and assign it as an administrator for the root organization in the institution hierarchy. This action will facilitate the retrieval of all assessment data from Canvas to P&SS. 
   • Please follow the steps to create an account role in Canvas.
     • Open Account. In Global Navigation, click Admin link [1], then click name of the account [2].
     • Open Permissions. In Account Navigation, click the Permissions link.
     • Open Account Roles. Click the Account Roles tab.
     • Add Role. Click the Add Role button.                                                           

     • Add Role Name. In the Role Name field, type the name of the new role.

     • Save Role. Click the Save button.                                                     

     • View Account Role. View the new account-level role.

   • Upon creating a new account role in Canvas, provide the following permissions to the role.
     • Account-level settings - manage
     • Course Content - view
     • Courses - view list
     • Discussions - view
     • Grades - view all grades
     • Manage Assignments and Quizzes
     • Rubrics - add / edit / delete
     • SIS Data - read
     • Users - view list
     • Users - view login IDs
     • Users - view primary email address
   • Make sure that the user of an account role (the one created from the above steps) is added as an account admin in Canvas. Please refer to the following steps on how to add a user as an account admin in Canvas.

     • Log in as an administrator in Canvas.

     • Click Admin on the left hand navigation.

     • Select the account or sub-account where the user will be added as an admin.

     • Click Settings.

     • Click the Admin tab.

     • Click on +Account Admin button.

     • Select the role (the role created in the above steps) in Add More drop down. Add the email address of the user.

     • Click Continue.

     • Click "OK Looks Good, Add This 1 User."

       The user will be added as an account admin.

2. To enable this feature, a P&SS institution must request backend flagging in the database, a process facilitated by the Watermark engineering team.

Create API Developer Key & Enable scoping for a developer API key

NOTE: By default, the scoping is disabled when creating a developer key. For the institutions that had already set up their integrations the scope option will be disabled. However, the scopes can be updated for a developer API key at any time. 

1. In Account Navigation, click the Developer Keys link. Open Developer Keys.

2. Click the Add Developer Key button. Add Developer Key. 

3. Click the Add API Key option. Add API Key.

4. After completing the developer key information, click the Enforce Scopes button. By default, the scopes are disabled. 

5. To permit usage of all included parameters for this key, click the Allow Include Parameters checkbox. 

6. Search the endpoints that are required to fetch the necessary assessment data. To search for a specific endpoint, type the name of the endpoint in the Search Endpoints field. To see all available endpoints, scroll through the Endpoints table.

7. Save the API Key.

8. Enable the API Key. 

This does not require any changes in the Planning & Self Study application. Once the scopes are enabled, we can utilize the key to make the connection to Canvas in P&SS.

Required API Endpoints

These are the endpoints that must be selected in an API key. The endpoints below will fetch the Courses, Assignments, Quizzes, Discussions, Rubrics, and results data from Canvas.

1. Accounts: GET|/api/v1/accounts
2. Accounts: GET|/api/v1/accounts/:account_id/sub_accounts
3. Accounts: GET|/api/v1/accounts/:account_id/courses
4. Assignments: GET|/api/v1/courses/:course_id/assignments
5. Enrollment Terms: GET|/api/v1/accounts/:account_id/terms
6. Rubrics: GET|/api/v1/courses/:course_id/rubrics
7. Rubrics: GET|/api/v1/courses/:course_id/rubrics/:id
8. Rubrics: GET|/api/v1/accounts/:account_id/rubrics
9. Sections: GET|/api/v1/courses/:course_id/sections
10. Submissions: GET|/api/v1/courses/:course_id/students/submissions
11. Users: GET|/api/v1/accounts/:account_id/users

Key things to consider when enabling scopes

1. All the required endpoints must be selected in the key in order to make the integration work seamlessly. The integration will not work even if one of these endpoints is missed.
2. Allow Include Parameters option must be selected in an API key. "Includes" parameters may grant access to additional data that is not included in the Endpoints table.
3. Make sure that no additional endpoints are selected other than the required ones in an API key.
4. Scopes must be enabled for the API key.
5. If the scopes are removed, the refresh token will become invalid, causing the integration to disconnect. The user will need to reauthorize the integration after re-adding the necessary scopes.
6. Make sure that the API key is in enabled state.

Use the API key to set up Integration in P&SS

The following are the steps to enable integration and align results from Canvas in order to add measures to an outcome and get results. 

1. In P&SS, navigate to Integrations under the Admin section. 

2.Click on Connect to Canvas LMS button in Canvas LMS card under Other Integrations section to open canvas integration flyout.

3. Click on COPY URI. 

4. Paste the URI from Step 1 into the field called Redirect URIs in the Canvas API key. Save the key.

5. Find the key you just created. Copy the ID and Key from the Details column in Canvas and paste them in ID and Key columns in P&SS. 

6.Paste the institution’s canvas URL in canvas URL field. 

7. Click Authorize Canvas button. 

8. A new tab opens up to the canvas application login page. 

9. Log in to the application using the credentials of the account role user (the role that was set up with all required permissions). 

10. Click Authorize.

11. A success message will appear in the establish connection form. 

12. Close the form. A snackbar success message appears below. The appropriate status for the integration can also be viewed.