Integrations Documentation

Set up OneRoster v1.1 integration

OneRoster is the standard IMS Global specification designed to allow secure sharing of class rosters and related data between a student information system (SIS) and any other system. OneRoster 1.1 is a major upgrade to the educational content, tool, and platform roster related standard.

OneRoster supports spreadsheet (CSV) export-import as well as direct system exchanges using REST API’s. IPSIS in the Brightspace platform supports the IMS OneRoster v1.1 specification, which allows secure sharing of class rosters and related data between a student information system (SIS) and the Brightspace platform. More specifically, the Brightspace platform is IMS Global Certified in the following conformance certifications:

OneRoster v1.1 CSV Rostering Import Bulk
OneRoster v1.1 CSV Rostering Import Delta
OneRoster v1.1 REST Data Consumer Rostering Core

Set up roles for OneRoster

Before you configure your OneRoster integration in the IPSIS administration area, you must complete the following:

Review the roles that are configured in your SIS and the corresponding roles that are mapped. The following roles are available in OneRoster:
- Administrator
- Aide
- Guardian
- Parent
- Proctor
- Relative
- Student
- Teacher
For any of the above roles you want to send into the Brightspace platform, you must set up a mapping when you create the SIS integration. If there isn’t already an appropriate role in the Brightspace platform, create one before you configure your SIS Integration.

Set up Org Unit Types

Review the org unit types that are configured in your SIS and the corresponding roles that are mapped. The following org types are available in OneRoster:
- National
- State
- Local
- District
- School (mandatory)
- Department
For any of the above org unit types that you want to send into the Brightspace platform, you must set up a mapping when you create the SIS Integration, which map to org unit types in the LMS. If there isn’t already an appropriate org unit type in the Brightspace platform, create one before you configure your SIS integration.

About user relationships

Note: This information is for K-12 clients who want to use Brightspace Parent & Guardian.

Your institution is responsible for maintaining the accuracy of user relationships in your Student Information System (SIS). Consult with your advisers to ensure you adhere to your institution’s privacy and security policies, and applicable laws. For example, your institution or jurisdiction might have a policy or law that specifies when a child turns 18, the parent/legal guardian should no longer have access to their child's content, unless the child consents to granting access; this case needs to be handled while generating and sending Parent/Guardian-child relationships to Brightspace.

Configure a REST SIS integration

In your organization’s SIS, generate a OneRoster Consumer for the Brightspace platform with which to call into your SIS. Note: The process for this varies depending on your SIS. Consult your SIS representative for more information.
Record the OAuth Credentials from your SIS.
Record the URL of your SIS’s OneRoster endpoint. For example, https://www.sis.com/school/api. Note: Do not include ims/oneroster/v1p1 on the end of the URL. D2L does this within the IPSIS Service.
Complete the configuration in the new IPSIS administration area.
From the Data Exchange Format drop-down list, select REST.
Note: If you have existing records you want to match with the OneRoster data, ensure that for the questions pertaining to linking Brightspace platform data with their SIS equivalents, you select the appropriate options.
In the Scheduled Updates field, select the time each day that you want your REST integration to update automatically.
When you save your integration, it will begin to process when the time of the next scheduled update occurs. If you want to run your integration immediately, on the Batches page, from the Run Update Now button, select Resync all SIS records.

Configure a CSV SIS integration

Create a CSV file with your roster related data.
Complete the configuration in the new IPSIS administration area (see the IPSIS administration for new SIS integrations section). From the Data Exchange Format drop-down list, select CSV drag & drop.
Note: If you have existing records you want to match with the OneRoster data, ensure that for the questions pertaining to linking Brightspace platform data with their SIS equivalents, you select the appropriate options.
On the Batches page, drag and drop or browse and select a ZIP file containing the CSV file with your roster related data.
Your integration begins to process automatically.

Verify a OneRoster integration

There are several ways to verify a OneRoster integration:

To find out if a REST integration completed, go to the Audit log (in the original IPSIS administration interface) and refresh the page to check if all the record types you expected (user, org unit, and so on) have run.
To find out if a CSV integration completed, do one of the following:
- When you drag and drop or select a CSV ZIP file, a processing indicator displays on the Batches page of that source system. When it is done, refresh the page and the indicator updates to display Completed.
- Go to the Audit log and refresh the page to check if all the record types you expected (user, org unit, and so on) have run.
To find out if either type of integration completed, do either of the following:
- For org units, you can use the Org Unit Editor to review all org units that were created and make updates, if necessary.
- For users, you can use the Users tool to review all users that were created and make updates, if necessary.

Troubleshooting a OneRoster integration

If on your first run of either type of OneRoster integration an error occurs, try to reprocess the integration.

To reprocess a CSV integration:

On the Batches page, drag and drop your CSV ZIP file into the designated area again.
If the CSV ZIP file is corrupt, generate a new file from your SIS and drag and drop it into the interface to process it again.

To reprocess a REST integration:

On the Batches page, from the Run Update Now button, select either of the following:
- Resync updates - you can select the earliest date from which you want to synchronize only updates made to the data. Then click Resync.
- Resync all SIS records - you can pull all of the data from your SIS again, with no time constraint.

OneRoster mapping values

OneRoster object types do not map exactly with those in the Brightspace platform. The following table shows how the OneRoster values relate to those in the Brightspace platform.

OneRoster value	Brightspace platform value
Academic Sessions	Org Units*
Orgs	Org Units*
Courses	Course Templates
Classes	Course Offering & Course Section
Users	User
Enrollments	Enrollment

*The org unit type that each object is mapped to depends on the configuration of the mapping sections for the SIS integration in the IPSIS administration area.

REST mapping values

Academic Sessions

OneRoster	Supported values	Brightspace platform	Required
SourcedId		Internal tracking	Y
Status	active, tobedeleted	Active	Y
DateLastModified	YYYY-MM-DDTHH:mm:SS.sssZ	Internal tracking	Y
MetaData		Mapped
Title		Org Unit Name and Org Unit Code	Y
StartDate	YYYY-MM-DD	Internal tracking	Y
EndDate	YYYY-MM-DD	Internal tracking	Y
Type		Org Unit Type	Y
Parent		Mapped
Children		Mapped
SchoolYear		Mapped

Orgs

OneRoster	Supported values	Brightspace platform	Required
SourcedId		Internal tracking	Y
Status	active, tobedeleted	Active	Y
DateLastModified	YYYY-MM-DDTHH:mm:SS.sssZ	Internal tracking	Y
MetaData		Mapped
Name		Org Unit Name and Org Unit Code	Y
Identifier		Org Unit Code (if provided)	N
StartDate	YYYY-MM-DD	Internal tracking	Y
EndDate	YYYY-MM-DD	Internal tracking	Y
Type		Org Unit Type	Y
Parent		Parents	N
Children		Mapped

Courses

OneRoster	Supported values	Brightspace platform	Required
SourcedId		Internal tracking	Y
Status	active, tobedeleted	Active	Y
DateLastModified	YYYY-MM-DDTHH:mm:SS.sssZ	Internal tracking	Y
MetaData		Mapped
Title		Org Unit Name and Org Unit Code	Y
SchoolYear		Parents	N
CourseCode		Org Unit Code (if provided)	N
Grades		Mapped
Subjects		Mapped
Org		Parents	N
StartDate	YYYY-MM-DD	Internal tracking
EndDate	YYYY-MM-DD	Internal tracking
SubjectCodes		Mapped
Resources		Mapped

Classes

OneRoster	Supported values	Brightspace platform	Required
SourcedId		Internal tracking	Y
Status	active, tobedeleted	Active	Y
DateLastModified	YYYY-MM-DDTHH:mm:SS.sssZ	Internal tracking	Y
MetaData		Mapped
Title		Org Unit Name and Org Unit Code	Y
ClassCode		Org Unit Code (if provided)	N
ClassType		Mapped
StartDate	YYYY-MM-DD	Course Start Date	N
EndDate	YYYY-MM-DD	Course End Date	N
Location		Mapped
Grades		Mapped
Subjects		Mapped
Course		Parents	N
School		Parents	Y
Terms		Parents	N
SubjectCodes		Mapped
Periods		Mapped
Resources		Mapped

Users

OneRoster	Supported values	Brightspace platform	Required
SourcedId		OrgDefinedId	Y
Status	active, tobedeleted	IsActive	Y
DateLastModified	YYYY-MM-DDTHH:mm:SS.sssZ	Internal tracking	Y
MetaData		Mapped
UserName		UserName	Y
UserIds		Mapped
EnabledUser		IsActive	Y
GivenName		FirstName	Y
FamilyName		LastName	Y
MiddleName		MiddleName	N
Role		Role In Org	Y
Identifier		OrgDefinedId (if provided)	N
Email		ExternalEmail	N
Sms		MobilePhone	N
Phone		HomePhone	N
Agents		Mapped
Orgs		Upper Org Unit Enrollments (with role in org)
Grades		Mapped
Password		Mapped

Enrollments

OneRoster	Supported values	Brightspace platform	Required
SourcedId		Internal tracking	Y
Status	active, tobedeleted	Active	Y
DateLastModified	YYYY-MM-DDTHH:mm:SS.sssZ	Internal tracking	Y
MetaData		Mapped
User		User to Enroll	Y
Class	YYYY-MM-DD	Class & Section to Enroll in	Y
School	YYYY-MM-DD	Mapped
Role		Role	Y
Primary		Mapped
BeginDate		Mapped
EndDate		Mapped

CSV mapping values