Canvas API Integration - Roster Exchange Setup

The Roster Exchange API Integration allows Barnes & Noble College (BNC) to gather course enrollment information to use for billing purposes when content is provisioned in a First Day program.

Set Up the API Roster Exchange

The Canvas Administrator will create a Developer Key to enable this integration.

  1. Log into Canvas as an admin.
  2. Navigate to the Admin tab.
  3. Select the Root Account option.
    • Click Permissions  Account Roles Add Role
    • Role Name: Barnes and Noble API Role and click Save
    • Assign the following permissions to the role:
      • Courses - view list
      • Course content – view
      • SIS Data – read
      • Users - view list
      • Users - view login IDs
      • Users - view primary email address
Canvas Platform API User Permissions
To be able to call the Canvas API, we need to “authenticate” a Canvas user with the proper set of permissions so that we can retrieve data from the API. This is different from the Scopes, where the Scopes are for the Client ID. The Permissions are another layer of security for the API, where even though the developer key might have the proper scopes, the user who authenticated the API might not have the proper permission to call the necessary endpoints.

To properly set this up, create a new Canvas Account Role with the proper set of permissions, assign that role to a new Canvas user specially created for the integration, and then authenticate the Canvas API with that user.

  • Courses - view list   This permission allows us to view the list of courses associated with an account and term. One of the features of the BNC API integration is to ingest the courses within a given term into the BNC LTI tool. This allows us to match Canvas courses to book adoptions prior to students and faculty launching to the BNC LTI tool. Course materials can then be made available to the students & faculty on their first visit to the BNC LTI tool.
  • Course content - view  This permission allows the user associated with the BNC API integration to identify when BNC LTI tool links have been placed in a Canvas course. This enables BNC to better understand what course materials have been adopted in a Canvas course and pre-provision that content to the course users.
  • SIS Data - read  This permission allows BNC to get course sis ids and user sis ids. These identifiers are used to match courses and users to their enrollments within our First Day program management tools.
  • Users - view list  This permission allows BNC to view user data. This pulls users as related to their enrollment in specific courses.
  • Users - view login IDs  This permission allows BNC to view user login IDs. The user login IDs are used to match users to their enrollments within our First Day program management tools.
  • Users - view primary email address  This permission allows BNC to receive user email addresses. User email addresses are not currently returned in Canvas APIs. Email addresses are used to match users to their enrollments within our First Day program management tools.
      1. Create a new User in Canvas
        • Click Admin → People → + People
        • Full Name: Barnes and Noble API Integration
        • Email: integrations@bncollege.com
        • Do not check Email the user about this account creation
        • Click Add User
      2. On the People page, locate this new user and click on their name
        • Under Login Information, click the Edit (pencil) button, leave all fields as is, and click Update Login
        • Click the Edit button once more and setup a password for this user.
          • This username and password will be used to authenticate the integration. Be sure to hold on to the credentials.
      3. Add the Account Role to the new user
        • Admin → Settings → Admins
        • Scroll down to the bottom of the page and click + Account Admins
        • Select the Barnes and Noble API Role from the drop down and enter integrations@bncollege.com in the email field
        • Click Continue
        • Click OK
      1. Select Developer Keys from the left-hand navigation menu.
      2. Click on +Developer Key and select +API Key.
      3. Complete the Key Settings with the following information:
      4. Enforce Scopes and enable the following required endpoints:
        • Accounts
          • url:GET|/api/v1/accounts/:account_id/courses
        • Courses
          • url:GET|/api/v1/courses
          • url:GET|/api/v1/courses/:id
        • Enrollment Terms
          • url:GET|/api/v1/accounts/:account_id/terms
          • url:GET|/api/v1/accounts/:account_id/terms/:id
        • Enrollments
          • url:GET|/api/v1/courses/:course_id/enrollments
        • Sections
          •  url:GET|/api/v1/courses/:course_id/sections
          •  url:GET|/api/v1/courses/:course_id/sections/:id
          • url:GET|/api/v1/sections/:id
        • Users
          • url:GET|/api/v1/accounts/:account_id/users
          • url:GET|/api/v1/users/:id
      5. Click Save Key.
      6. On the Developer Keys page, locate the Key you just created and toggle the State to ON.
      7. The Client Key is located under Details, above the Show Key button and must be sent to Barnes & Noble College.
      8. The Developer Key is also required. Click Show Key in the Details column.
      9. Copy/paste and send both the Client ID and the Developer Key value to your (BNC) implementation point of contact via a secure method.
      10. Authenticate the API integration.
        • Your BNC contact will reply back with an API authentication URL. 
          • Log out of your personal Canvas admin account.
          • Click on the authentication URL.
          • Sign in with the system user and password created in step 3.
        • Click Authenticate. You should receive a Success! message.
          • If you receive an error, report this to your BNC implementation contact.
          • If you receive the Success! message, locate the Course Material link within the course in your upcoming term and click the link (this will initiate the API sync).
            • If there are no courses with the Course Material link currently installed for the upcoming term, please add to either a real or test course and click.
              • This will initiate the API sync and allow us to begin pulling course and roster information for the term.

For Next Term

The Canvas API allows us to pull course and roster information for courses associated to terms that have been initiated by a sync. This term sync is initiated with a click on the BNC Course Material link within a course associated to the upcoming term. In order to pull course and roster information for each new term, please be sure to click on the Course Material link in either a real or test course in the upcoming term to initiate the new term sync.

Remove the Roster Exchange API Configuration 

Stop

If you currently have First Day, do not remove this API until your current term courses have fully completed, or students will lose access to their materials.

You must only complete this step if you had a First Day program prior to the upcoming term. Otherwise, continue to the first step, Set Up API Roster Exchange.

      1. Within admin settings, click the Admins tab.
      2. Look for the admin who was assigned the “Roster Exchange” account role.
      3. Take note of the email address for that user.
      4. Sign out of your admin account.
      5. Sign in as the Roster Exchange admin user.
        • if your Canvas link routes you to an SSO page, try signing in at:
          https://yourdomain.instructure.com/login/canvas
      6. Click Account.
      7. Scroll down to Approved Integrations.
      8. Click the trash can symbol next to the right of BNEDRosterAPI to remove API access.
      9. Sign out.

 

 

 

Was this article helpful?
0 out of 0 found this helpful