Canvas - Sub-account level

If your institution is part of a consortia/shares an instance of Canvas with other institutions or systems, you will need to set up the Canvas integration at a Sub-Account level so that only data for your institution will be pulled in.

You will need two separate Canvas Accounts to establish the integration. One is a Canvas Admin Account created at the sub-account level with specified permissions. This account will authorize the integration for Planning & Self-Study. The second Canvas account is a root admin account, which is used for creating the key containing the scopes. The scopes are the data endpoints Planning & Self-Study will be limited to for the purpose of the integration.

It is best practice for the designated accounts to be created for the integration. You may use existing Canvas admin accounts but if those accounts are deactivated (ie., someone departs your organization), the integration will need to be reauthorized.

How to setup the feature

• Create an account role within Canvas, specifying a set of permissions, and assign it as an administrator for the sub-account 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.
    1. Open Account. In Global Navigation, click the Admin link [1], then click the name of the account [2].                         

    2. Open Permissions. In Account Navigation, click the Permissions link.

    3. Open Account Roles. Click the Account Roles tab.

    4. Add Role. Click the Add Role button.                                                         

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

    6. Save Role. Click the Save button.                                                     

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

        

        

  • Upon creating a new account role in Canvas, provide the following permissions to the role.

    1. Account-level settings - manage

    2. Course Content - view

    3. Courses - view list

    4. Discussions - view

    5. Feature Options - enable / disable

    6. Grades - view all grades

    7. Manage Assignments and Quizzes

    8. Rubrics - add / edit / delete

    9. SIS Data - read

    10. Users - view list

    11. Users - view login IDs

    12. Users - view primary email address

  • Make sure that the user of an account role (the one created by following the above steps 3a and 3b) is added as an account admin to the sub-account in Canvas. The user used to authorize the integration should be associated with only one sub-account.
  • Please refer to the following steps on how to add a user as an account admin in Canvas.

    1. Log in as an administrator in Canvas.

    2. Go to the Admin side menu.

    3. Select an account for which you are an admin. For Example: EvaluationKIT in the snapshot.

    4. Go to Settings side menu.

    5. Go to Settings > Admin tab.

        

        

    6. Click on Account Admin button.

    7. Select the role (Select the role that is created using steps 3a and 3b) in Add More drop down. Add the email address of the user.

    8. Click Continue.

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

The user will be added as an account admin.

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

This API key needs to be created by a user who is an admin at root level organization in Canvas. It’s a Canvas functionality that only an admin at root level can create a developer key.

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.

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

• Click the Add Developer Key button. Add Developer Key

• Click the Add API Key option. Add API Key                           

• Enter any Key Name you’d like. Paste the URI from Step 1 of canvas integration fly-out into the field called “Redirect URIs”. Click on Save The Key button.

•  Find the key you just created. Copy the ID and Key from the Details column and paste them in Step 4 of canvas integration flyout.                                           

•  To permit usage of all "includes" parameters for this key, click the Allow Include Parameters checkbox.                                                                       

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

•  Save the API key.                                                                                     

•  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

Following are the API endpoints that must be selected in an API key. The below mentioned endpoints 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

Following are the steps to enable integration and align results from canvas when adding measure to an outcome and getting results as per our selection.

1. In P&SS application navigate to Integrations page under 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 the the button 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 consisting the canvas application login page.

9. Login to the application using the credentials of account role user who is added at the sub-account level(with all the required set of permissions).

   • The user used here to authorize the integration should be associated with only one account.

     • Root account if institution is using their own Canvas instance,

     • or the relevant sub-account if institution is using a shared Canvas instance.

10. Click Authorize.

11. You will notice that a success message appears in the establish connection form.

12. Close the form. You will notice that a snackbar success message appears. You can also view the appropriate status for the integration.

     

Required Data Mapping

1. In System Administration, the course section’s section ID (to be used as an SIS ID) is required. However, in Canvas, the SIS ID for the course is not a required field. The clients would need to ensure that this SIS ID is provided in the course so that the necessary mapping can be done (through a resolver).
2. In System Administration & Canvas, the course/course section IDs must be unique so that the required mapping of these objects can be done in order to list the activities and their details in P&SS when aligning a measure from Canvas.
3. The term is set to the default term for any course in Canvas when it’s created (if no term is selected when creating a course). The institutions need to ensure that they select a term for their courses.
4. The student email address must be same in both Canvas and System Administration for mapping.