Brightspace/D2L APIs for Courses and Enrolments

Part 1: Create a Role with Permissions 

We recommend you create a role specifically for this integration. This will allow you to control the permissions available to VitalSource without affecting other users.

  1. Click on the gear icon to view the Admin Tools.
  2. Under the Security Tab, select Roles & Permissions.
  3. Click Create/Copy.
  4. You can copy an existing role if you like or start afresh. Either way, make sure your role is configured as noted in the next steps.
    • General
      • Name: VitalSource
      • Cascading Role: Tick this box
      • Description: Can add if needed
      • Role Alias: Can add if needed
    • You do not need to select anything in Tool Behaviour Options or Classlist Display Options
    • Course Access Options:
      • Access Inactive Courses: Tick the box
      • Access Past Courses: Tick this box
      • Access Future Courses: Tick this box
      • Access All Course Sections
      • Access All Course Groups
  1. Click Save.
  2. On the Edit Role Interactions page, tick all boxes for your Administrator role.
  3. Click Save and you have created the role.
  4. On the Role List page, click the down arrow next to the VitalSource role you just created and select Import Permissions.
  5. Download the .txt file attached to this article. 
    • This contains all the permissions required by VitalSource. See below for a complete list of permissions.
  6. Select the VitalSource D2L Permissions file to import. Click Next and then Import.

Part 2: Create a System User

  1. Navigate to the Settings Menu (gear icon) and select Users.
  2. Click New User and enter the following:
    • First Name: VitalSource
    • Last Name: Integration
    • Username: vst.integration
    • Role: Select the VitalSource role you created in Part 1
    • Password: Tick the Manually set password box and enter a password that you will remember. You will need this later.
  3. Click Save.

Part 3: Register an App 

  1. Navigate to the Settings Menu (gear icon) and select Manage Extensibility.
  2. Click Register an App and enter the following:
    • Application Name: VitalSource
    • Trusted URL: https://bc.vitalsource.com/oauth2callback
    • Major and minor version box is mandatory for the admin to fill in as well.
    • Enable this application: Tick this box
    • I accept the Non-Commercial Developer Agreement: Tick this box
    • Click Register Application
  3. Copy the Application ID and Application Key and save them. You’ll need them again.
  4. Click Register Application.
  5. Copy the Application ID & Application Key and send them to the VitalSource team along with the URL for your Brightspace site.

Part 4: Authenticate

  1. The VitalSource team will send you an authentication link after receiving the application key and ID from you.
  2. Before clicking the link, go to your Brightspace site and make sure you are logged out of your own account.
  3. Click the link and enter the username and password for the user you created in Part 2 above.
  4. You should receive a Success! message, meaning that you have authenticated the rostering application. Send a confirmation back to the VitalSource team.
  5. Once VitalSource has confirmed that the setup was successful, please add a VitalSource link to a course in your upcoming term and click on this link.
    • This will initiate the API sync and allow us to begin pulling course and roster information.

For Each New Term

Each term sync is initiated with a click on the VitalSource link within a course associated with the upcoming term. To pull course and roster information for each new term, make sure you click on the VitalSource link in a course in the upcoming term to initiate the new term sync.

Permissions 

Here is a comprehensive list of the permissions required by the VitalSource app.

  • Classlist (Brightspace Reference→ Here)
    • Has Access to the Classlist: All boxes
    • See Classlist Report: All boxes
    • View Group Enrolments: All boxes
  • Content (Brightspace Reference→ Here)
    • View Course Content: All boxes
    • Manage Content: All boxes
    • Create and Edit Modules and Topics: All boxes
  • Course Management Console (Brightspace Reference→ Here)
    • See Course Info: Course Offering, Group, Semester, Section, Department, Programme, School Type, Campus
    • See Tool Management: Course Offering
    • Set Tool Status: Course Offering
  • External Learning Tools (Brightspace Reference→ Here)
    • Manage External Learning Tools Configuration: Course Template, Course Offering, Semester, Section, Department, Programme
    • Launch External Learning Tool Links: Course Offering
    • Manage and Delete External Learning Tool Links: Course Template, Course Offering, Semester, Section, Department, Programme
    • Manage External Learning Tool Providers: Course Template, Course Offering, Semester, Section, Department, Programme
    • Create Quicklinks from available External Learning Tools links: All boxes
    • Create External Learning Tool Links from available External Learning Tool Providers: All boxes
    • Manage LTI Advantage Tool Registrations: Organisation
    • Manage LTI Advantage Tool Deployments: Organisation
    • Delete External Learning Tool Links: All boxes
  • My Org Units (Brightspace Reference→ Here)
    • See My Org Units: Organisation, Course Template, Course Offering, Group, Semester, Section, Department, Programme
    • Manage My Org Units tool: Course Offering
  • Org Unit Editor (Brightspace Reference→ Here)
    • View Org Unit Editor: Organisation
  • Tool Management 
    • See Org Tool Management: Organisation
  • User Information Privacy (Brightspace Reference→ Here)
    • See First Names: All boxes
    • See Last Names: All boxes
    • See Usernames: All boxes
    • See Org-Defined IDs: All boxes
    • See Email Addresses: All boxes
  • Users (Brightspace Reference→ Here)
    • View the Users' Email Address: All boxes
    • View Users' Org-Defined IDs: All boxes
    • View User Enrolments: All boxes
    • Search for 'Instructor': All boxes
    • Search for 'Student': All boxes

Endpoints

Here is a comprehensive list of the D2L Valence APIs used by the VitalSource app.

  • GET /d2l/api/lp/1.2/courses/:course_id
  • GET /d2l/api/lp/1.2/orgstructure/:semester_id/children/
  • GET /d2l/api/lp/1.2/enrolments/orgunits/:course_id/users/
  • GET /d2l/api/lp/1.2/organisation/info
  • GET /d2l/api/lp/1.2/orgstructure/:semester_id
  • GET /d2l/api/lp/1.2/orgstructure/:org_id/children
  • GET /d2l/api/le/1.40/:course_id/content/root/
  • POST /d2l/api/le/1.40/:course_id/content/root/
  • GET /d2l/api/le/1.40/:course_id/content/modules/:module_id/structure/
  • POST /d2l/api/le/1.40/:course_id/content/modules/:module_id/structure/
  • POST /d2l/api/le/1.40/lti/link/:course_id
  • POST /d2l/api/le/1.40/lti/quicklink/:course_id/:lti_link_id

Data Storage & Usage

Here is a description of the Brightspace data the VitalSource app receives and how that data is stored & used.

Field

Description

Storage & Usage

(course) identifier

Unique course identifier

stored & used for identifying unique courses, communication of student opt-out decisions to publisher courseware providers when applicable

(course) name

Course title

stored & used for display in VitalSource Launch & Analytics and matching LMS/VLE course data to SIS course data for Inclusive Access programmes

(course) code

Course code/label

stored & used for display in VitalSource Launch & Analytics and matching LMS/VLE course data to SIS course data for Inclusive Access programmes

(course) StartDate

Course start date

stored & used for determining when courses should be considered active in application displays and when to issue add/drop content access to students

(course) EndDate

Course end date

stored & used for determining when a course ends

(semester) identifier

Unique semester identifier

stored & used to group courses together that belong to the same semester

(semester) name

Semester title

stored & used to group courses together that belong to the same semester

(semester) code

Semester abbreviation

not stored or used

(department) identifier

Unique department identifier

not stored or used

(department) name

Department name

not stored or used

(department) code

Department abbreviation

not stored or used

(user) identifier

Unique user identifier

not stored or used

(user) displayName

User full name

stored & used for personalised display

(user) emailAddress

User email address

stored & used for matching LMS/VLE student accounts to SIS student enrolment for Inclusive Access programmes

(user) orgDefinedId

Unique user identifier

stored & used for matching LMS/VLE student accounts to SIS student enrolment for Inclusive Access programmes

(user) profileBadgeUrl

D2L profile badge url

not stored or used

(user) profileIdentifier

D2L profile identifier

not stored or used

(user) role

A user's role within an org unit

stored & used to determine the appropriate user experience and access type a user should be granted

(organisation) identifier

Unique D2L organisation identifier

not stored, used to execute other D2L Valence APIs

Was this article helpful?