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. The Brightspace OneRoster implementation supports spreadsheet (CSV) import, as well as direct system exchanges using REST APIs.
The Brightspace implementation of OneRoster v1.1 specification lets administrators schedule data to be pulled from their SIS to populate the required roster-related data (such as schools, classes, users, and enrollments) in Brightspace.
The IPSIS OneRoster REST user interface includes a schedule to allow administrators to configure the time of day when the data pull occurs. For an SIS supporting grades passback, administrators can set the grades to be returned with the daily data synchronization or allow a faculty member to initiate a manual sync.
Before you configure your OneRoster integration in the IPSIS Administration area, review the following setup, mapping, and basic configuration information found in this topic.
Set up Roles
Before you configure your OneRoster integration in the IPSIS administration area, you must set up the roles you intend to use. The following roles are available in OneRoster:
- Administrator
- Aide
- Guardian
- Parent
- Proctor
- Relative
- Student
- Teacher
- Review the roles that are configured in your SIS.
- For any of the roles you want to send into the Brightspace platform, do one of the following:
- Verify that the roles you want to include in your Brightspace platform exist.
- If some of the roles do not exist in Brightspace, create them in the Roles and Permissions tool before you configure your SIS system. For more information, refer to Managing Roles and Permissions.
Set up Org Unit Types
You are required to set up mappings between org unit types in the SIS and in the Brightspace when you create the SIS Integration. The following org unit types are available in OneRoster:
- National
- State
- Local
- District
- School (mandatory)
- Department
- Review the org unit types that are configured in your SIS.
- For any of the org unit types that you want to send into the Brightspace platform, do one of the following:
- Verify that the org unit types you want to include in your Brightspace platform exist.
- If some of the org unit types do not exist in Brightspace, create them in the Org Unit Editor tool before you configure your SIS system. For more information, refer to Create and delete org unit types.
Mapping data types between OneRoster and Brightspace
OneRoster object types do not map exactly with object types in Brightspace. The following table shows the mapping relationship between OneRoster and Brightspace object types.
|
Note: Set up org unit types in Brightspace using the before you configure your OneRoster integration. For more information, refer to Create and delete org unit types.
Org Unit types are typically custom org unit types that you can map during the configuration process.
|
| OneRoster Data Type |
D2L Brightspace Data Type |
|---|
| Academic sessions |
Org Units |
| Org |
Org Units |
| School |
Org Units |
| Course |
Course Template |
| Class |
Course Offering, Course Section |
| User |
User |
| Enrollment |
Enrollment |
| Line item categories |
Grade categories |
| Line items |
Grade items |
| Results |
Grades, Scores |
|
Note: Org Unit types are typically custom org unit types that you can map during the configuration process.
|
Responsibilities for parent/guardian 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.
Overview of OneRoster integrations
There are two types of OneRoster integrations: OneRoster Rest, and OneRoster CSV. This section of the topic provides basic information about these two integrations. For more information, refer to About OneRoster REST integration or About OneRoster CSV integration
OneRoster REST integration: Basic workflow
The following steps describe the high-level sequence to help you understand the OneRoster REST integration. For more in-depth workflow information, refer to About OneRoster REST integration.
- In your organization's Student Information System (SIS), you generate a OneRoster Consumer for Brightspace with which you will call into your SIS from Brightspace.
| Note: The process for creating this role varies depending on your SIS. For more information, consult your SIS representative. |
- Record the OAuth Credentials from your SIS, and the endpoint URL your SIS. 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 Brightspace in the IPSIS administration area. To match existing records with OneRoster data, select the appropriate options to link Brightspace data with SIS equivalents.
- Set a schedule for your REST integration to synchronize with your SIS.
After you have saved your integration, you can wait for the next scheduled update, or you can run your integration immediately using the Run Update Now button on the Batches page.
OneRoster CSV integration: Basic workflow
The following steps describe the high-level sequence to help you understand the OneRoster CSV integration. For more in-depth workflow information, refer to About OneRoster CSV Integrations
- Create a CSV file with your roster-related information.
- Complete the configuration in the IPSIS Administration area of the Brightspace Learning Environment. To match existing records with OneRoster data, select the appropriate options to link Brightspace data with SIS equivalents.
- On the Batches page drag and drop or browse to 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 determine if a REST integration is complete, navigate to IPSIS Administration > Audit Log. Refresh the page to verify if all the expected record types (such as user, org unit, and so on) have run.
- To determine if a CSV integration is complete, do one of the following
Batches Page: After uploading a CSV ZIP file, the processing indicator appears on the Batches page in the source system. Refresh the page to confirm the indicator shows Completed.
Audit Log: Refresh the Audit Log to verify all expected record types have been processed.
- To determine if either type is complete, do the following:
- Org Units: Use the Org Unit Editor to review all org units that were created and make updates if necessary.
- Users: Use the Users tool to review the users that were created and make updates if necessary.
<<<<<<<<<<<<<DRAFT STARTS HERE
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.
<<<<<<<SOURCE DRAFT CONTENT STARTS HERE
REST mapping values
CSV mapping values
Academic Sessions
| OneRoster |
Supported values |
Brightspace mappings |
Required |
Notes |
|---|
|
SourcedId
|
|
|
Y |
|
|
Status
|
active, tobedeleted
|
|
N |
Field is required for files in delta mode.
|
|
DateLastModified
|
|
|
N |
Field is required for files in delta mode.
Date Format YYYY-MM-DDTHH:mm:SS.sssZ
|
|
Title
|
|
Org Unit Name and Org Unit Code
|
Y |
|
|
Type
|
|
|
Y |
Org Unit Type
|
|
StartDate
|
|
|
Y |
YYYY-MM-DD
|
|
EndDate
|
|
|
Y |
YYYY-MM-DD
|
|
ParentSourcedId
|
|
|
N |
Not Used
|
|
SchoolYear
|
|
|
N |
Not Used
|
Orgs
| OneRoster |
Supported values |
Brightspace mappings |
Required |
Notes |
|---|
|
SourcedId
|
|
|
Y
|
|
|
Status
|
active, tobedeleted
|
|
N
|
Field is required for files in delta mode. |
|
DateLastModified
|
|
|
N
|
Field is required for files in delta mode.
Date Format YYYY-MM-DDTHH:mm:SS.sssZ
|
|
Name
|
|
Org Unit Name and Org Unit Code
|
Y
|
If the Identifier field is empty, the Name is copied in the Org Unit Code in Brightspace |
|
Type
|
national, state, local, district, school, department
|
|
Y
|
Defines the OrgUnitType in Brightspace.
http://www.imsglobal.org/oneroster-v11-final-specification#_Toc480452024
|
|
Identifier
|
|
Org Unit Code (if provided)
|
N
|
|
|
ParentSourcedId
|
|
|
N
|
This field specifies the parent org unit. |
Courses
| OneRoster |
Supported values |
Brightspace mappings |
Required |
Notes |
|---|
|
SourcedId
|
|
|
Y
|
|
|
Status
|
active, tobedeleted
|
|
N
|
Field is required for files in delta mode. |
|
DateLastModified
|
|
|
N
|
Field is required for files in delta mode.
Date Format YYYY-MM-DDTHH:mm:SS.sssZ
|
|
SchoolYearSourcedId
|
|
|
N
|
Not used |
|
Title
|
|
Org Unit Name and Org Unit Code
|
Y
|
Creates a Brightspace Course Template.
If the CourseCode field is empty, the Title is copied into the OrgUnitCode.
|
|
CourseCode
|
|
Org Unit Code
|
N
|
If provided |
|
Grades
|
|
|
N
|
Not used |
|
OrgSourcedId
|
|
|
Y
|
This field specifies the parent org unit. |
|
Subjects
|
|
|
N
|
Not used |
|
SubjectCodes
|
|
|
N
|
Not used |
Classes
| OneRoster |
Supported values |
Brightspace mappings |
Required |
Notes |
|---|
|
SourcedId
|
|
|
Y
|
|
|
Status
|
active, tobedeleted
|
|
N
|
Field is required for files in delta mode. |
|
DateLastModified
|
|
|
N
|
Field is required for files in delta mode.
Date Format YYYY-MM-DDTHH:mm:SS.sssZ
|
|
Title
|
|
Org Unit Name and Org Unit Code
|
Y
|
Creates a Brightspace Section and Course Offering.
If the ClassCode field is empty, the Title is copied into the Org Unit Code.
|
|
Grades
|
|
|
N
|
Not used |
|
CourseSourcedId
|
|
|
Y
|
This field specifies the parent org unit |
|
ClassCode
|
|
Org Unit Code (if provided)
|
N
|
If provided |
|
ClassType
|
|
|
Y
|
Not used |
|
Location
|
|
|
N
|
Not used |
|
SchoolSourcedId
|
|
|
Y
|
Not used |
|
TermsSourcedIds
|
|
|
N
|
Not used |
|
Subjects
|
|
|
N
|
Not used |
|
SubjectCodes
|
|
|
N
|
Not used |
|
Periods
|
|
|
N
|
Not used |
Users
| OneRoster |
Supported values |
Brightspace mappings |
Required |
Notes |
|---|
|
SourcedId
|
|
OrgDefinedId
|
Y
|
If the Identifier field is not populated, the SourcedId is copied into the OrgDefinedId. |
|
Status
|
active, tobedeleted
|
|
N
|
Field is required for files in delta mode. |
|
DateLastModified
|
|
|
N
|
Field is required for files in delta mode.
Date Format YYYY-MM-DDTHH:mm:SS.sssZ
|
|
EnabledUser
|
|
|
Y
|
Not used |
|
OrgSourcedIds
|
|
Upper Org Unit Enrollments (with role in org)
|
Y |
Enrollment in the school org units |
| Role |
administrator, aide, guardian, parent, proctor, relative, student, teacher |
|
Y |
Role in org |
|
UserName
|
|
UserName
|
Y
|
|
|
UserIds
|
|
|
N
|
Not used |
|
GivenName
|
|
FirstName
|
Y
|
|
|
FamilyName
|
|
LastName
|
Y
|
|
|
MiddleName
|
|
MiddleName
|
N
|
|
|
Identifier
|
|
OrgDefinedId
|
N
|
If provided |
|
Email
|
|
ExternalEmail
|
N
|
|
|
Sms
|
|
MobilePhone
|
N
|
|
|
Phone
|
|
HomePhone
|
N
|
|
|
AgentSourcedIds
|
|
|
N
|
Used for Brightspace Parent & Guardian. This field asserts the parent-child relationship. Both the child and parent rows must reference each other’s sourcedIds. |
|
Grades
|
|
|
N
|
Not used |
|
Password
|
|
Password
|
N
|
|
Enrollments
| OneRoster |
Supported values |
Brightspace mappings |
Required |
Notes |
|---|
|
SourcedId
|
|
|
Y
|
|
|
Status
|
active, tobedeleted
|
|
N
|
Field is required for files in delta mode. |
|
DateLastModified
|
|
|
N
|
Field is required for files in delta mode.
Date Format YYYY-MM-DDTHH:mm:SS.sssZ
|
|
UserSourcedId
|
|
|
Y
|
User to Enroll |
|
ClassSourcedId
|
YYYY-MM-DD
|
|
Y
|
Brightspace enrollment |
|
SchoolSourcedId
|
|
|
N
|
Not used |
|
Role
|
administrator, aide, guardian, parent, proctor, relative, student, teacher
|
Role
|
Y
|
|
|
Primary
|
|
|
N
|
Not used |
|
BeginDate
|
|
|
N
|
YYYY-MM-DD |
|
EndDate
|
|
|
N
|
YYYY-MM-DD |