1. VitalSource Success
  2. First Day™ Documentation
  3. LMS Integration and Roster Exchange Guides
  4. Canvas

Canvas API Integration - Roster Exchange Setup

Avatar
Kristin E
Follow

The Roster Exchange API Integration allows Barnes & Noble College (BNC) to pull course information to proactively map LMS courses to their corresponding SIS course(s). This ensures a seamless experience for faculty and students.

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
        • SIS ID: bnc_integration
        • 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
        • Enter bnc_integration in the field to add the user
        • Click Continue
        • Click OK
      4. Select Developer Keys from the left-hand navigation menu.
      5. Click on +Developer Key and select +API Key.
      6. Complete the Key Settings with the following information:
      7. Enforce Scopes and enable the following required endpoints:
        • Accounts
          • url:GET|/api/v1/accounts/:account_id/courses
          • url:GET|/api/v1/accounts
        • 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
      8. Click Save Key.
      9. On the Developer Keys page, locate the Key you just created and toggle the State to ON.
      10. The Client ID is located under Details, above the Show Key button and must be sent to Barnes & Noble College.
      11. The Developer Key is also required. Click Show Key in the Details column.
      12. Copy/paste and send the Client ID and the Developer Key value, as well as the base URL for your Canvas instance to your (BNC) implementation point of contact via a secure method.
      13. 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 Each New Term

Each 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 a 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?