Sub-account level

Updated
Watermark Support

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.
      • Open Account. In Global Navigation, click the Admin link [1], then click the name of the account [2].
        The admin menu panel showing the Admin option selected in the left navigation and the Documentation Canvas link highlighted on the right.

      • Open Permissions. In Account Navigation, click the Permissions link. The course settings menu showing navigation links with the Permissions option highlighted.

      • Open Account Roles. Click the Account Roles tab. The roles configuration section showing tabs for Course Roles and Account Roles with the Account Roles option highlighted.

      • Add Role. Click the Add Role button.
        The Add Role section showing an Add Role button highlighted for creating a new role.

      • Add Role Name. In the Role Name field, type the name of the new role. The New Account Role dialog showing the Role Name input field highlighted for entering a new role name.

      • Save Role. Click the Save button.
        The Save Role dialog showing Cancel and Save buttons with the Save button highlighted.

      • View Account Role. View the new account-level role. The account roles permissions table showing a comparison of permissions for Account Admin and Analytics Manager with allowed and restricted settings indicated.

    • 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

      • Feature Options - enable / disable

      • 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 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. The Admin menu showing the EvaluationKIT account listed with the All Accounts option indicated by an arrow.

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

      4. Go to Settings side menu. The account settings page showing the Settings tab selected with account configuration fields and options displayed in the main panel.

      5. Go to Settings > Admin tab. The account settings page showing the Admins tab selected with a list of account administrators and assigned admin roles displayed.

      6. Click on Account Admin button. The account settings page showing the Admins tab with a list of account administrators and the + Account Admins button highlighted at the bottom.

      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. The Add Account Admins section showing the role selection dropdown and an email address field populated for adding new account administrators.

      8. Click Continue.

      9. Click "OK Looks Good, Add This 1 User." The Add Account Admins confirmation section showing the selected user listed with buttons to go back or confirm adding one new user highlighted at the bottom.

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 The admin settings side menu showing the Developer Keys option highlighted among account configuration links.
  • Click the Add Developer Key button. Add Developer Key
  • Click the Add API Key option. Add API Key The developer keys menu showing options to add a Developer Key with the API Key option highlighted.
  • 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.The API settings panel showing Enforce Scopes enabled and the Allow Include Parameters option selected.
  • 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.The API permissions configuration panel showing enforce scopes enabled and a list of read-only endpoint categories displayed with selection checkboxes.
  • Save the API key. The action buttons section showing Cancel and Save buttons with the Save button highlighted.

  • Enable the API key.The developer keys list showing an active API key entry with the status toggle enabled and key details displayed.

    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. The integrations overview page showing available learning management system connections with the Canvas LMS option highlighted for selection.
  3. Click on the the button COPY URI. The Establish Connection dialog for Canvas LMS showing the redirect URI field with a Copy URI button highlighted and required ID and key entry fields displayed below.
  4. Paste the URI from Step 1 into the field called “Redirect URIs” in the Canvas API key. Save the key. The Key Settings page showing the Redirect URIs field highlighted alongside enforce scopes options and a list of available API endpoint permissions.
  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. The Establish Connection dialog for Canvas LMS showing highlighted ID and key input fields with the Authorize Canvas button displayed below.
  6. Paste the institution’s canvas URL in Canvas URL field. The Establish Connection dialog for Canvas LMS showing the canvas URL input field highlighted above the Authorize Canvas button.
  7. Click Authorize Canvas button. The Establish Connection dialog for Canvas LMS showing completed ID, key, and canvas URL fields with the Authorize Canvas button highlighted.
  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. The Canvas LMS authorization screen showing the Test API Key permission prompt with the Authorize button highlighted alongside the Establish Connection dialog.
  11. You will notice that a success message appears in the establish connection form.The Establish Connection dialog for Canvas LMS showing a successful connection confirmation message displayed at the bottom with a Close button on the right.
  12. Close the form. You will notice that a snackbar success message appears. You can also view the appropriate status for the integration. The active integrations page showing Canvas LMS marked as connected with activation details displayed and a confirmation message indicating the integration is now active.

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.
Was this article helpful?
0 out of 0 found this helpful

Articles in this section

How to Contact Support
There are many ways to reach out! Click the icon above for our support options.
Watermark Academy
Click the icon above to access the Watermark Academy for consultation, training, and implementation companion courses.
Customer Community
Can’t find the answer? Ask fellow users how they’re making the most of Watermark in our Community!