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.
- Click on the gear icon to view the Admin Tools.
- Under the Security Tab, select Roles & Permissions.
- Click Create/Copy.
- 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
- General
- Click Save.
- On the Edit Role Interactions page, tick all boxes for your Administrator role.
- Click Save and you have created the role.
- On the Role List page, click the down arrow next to the VitalSource role you just created and select Import Permissions.
- Download the .txt file attached to this article.
- This contains all the permissions required by VitalSource. See below for a complete list of permissions.
- Select the VitalSource D2L Permissions file to import. Click Next and then Import.
Part 2: Create a System User
- Navigate to the Settings Menu (gear icon) and select Users.
- 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.
- Click Save.
Part 3: Register an App
- Navigate to the Settings Menu (gear icon) and select Manage Extensibility.
- 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
- Copy the Application ID and Application Key and save them. You’ll need them again.
- Click Register Application.
- Copy the Application ID & Application Key and send them to the VitalSource team along with the URL for your Brightspace site.
Part 4: Authenticate
- The VitalSource team will send you an authentication link after receiving the application key and ID from you.
- Before clicking the link, go to your Brightspace site and make sure you are logged out of your own account.
- Click the link and enter the username and password for the user you created in Part 2 above.
- You should receive a Success! message, meaning that you have authenticated the rostering application. Send a confirmation back to the VitalSource team.
- 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 |