How to Set Up Advanced Canvas Integration

Before proceeding with the set up, it is a best practice to import the required data files in System Administration. 

Canvas - Required Data Mapping in System Administration & Canvas

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.

The Canvas user whose credentials are used to authorize the integration
should be associated with only one Canvas account:

• The root account, if the institution is using their own standalone Canvas instance- OR
• The relevant sub-account, if the institution is part of a shared Canvas instance.

This ensures that P&SS pulls data reliably from the correct account, and user have access to the expected assessment data. 

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. Users are presented with two options to select the terms for which they need data:
   1. Option 1: "Use all terms that are mapped in Watermark System Admin". When this option is selected:
      • Upon activating the integration, the system will perform a data sync.
      • The sync will only pull data for terms that have a corresponding SIS ID in Canvas, provided those terms are mapped in the Watermark System Admin.
        1. Both the term SIS ID in Canvas and the term ID in the Watermark System Admin must match for the term to be included in the sync.
      • The assessment data for the mapped terms will be pulled into P&SS.
      • For bi-weekly syncs, only the assessment data for the current mapped terms will be pulled into P&SS.
      • If a manual sync is triggered, the system will pull assessment data for all terms that are mapped in the system administration.
      • Note: If this option is selected then the terms in Canvas and System Administration must be mapped. Canvas term SIS ID and Term’s Term ID in System Administration should be added and match.
   2. Option 2: "Enter the number of past terms you need activity data from". When this option is selected:
      • A field will appear where the user can specify the number of past terms from which activity data should be pulled.
      • We can pull up to 6 terms worth of past data.
      • If this option is selected, then following Terms data will be pulled from Canvas.
        • Maximum of six past Canvas Terms.
          • Note: If an institution would like to pull data for more than six past terms then this can be done through a backend request.
          • Note: Date range must be added for terms in Canvas if this option is being selected when establishing the connection.

        • All current Canvas terms.

        • Two future Canvas terms.

           

8. Click Authorize Canvas button. 

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

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

11. Click Authorize.

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

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