The Integration Pack for Student Information System (IPSIS) platform
The Integration Pack for Student Information Systems (IPSIS) platform is an integration platform in Brightspace that consists of common components and a collection of products that allow you to import information from your organization's information system to Brightspace, for example, your organization structure, users, and enrollment information. Once that information is imported into Brightspace, you can continue to update your information system and import that information to Brightspace using the IPSIS platform.
Supported information systems
The IPSIS platform integrates with the following common types of information systems:
- Student Information Systems (SIS) - A software tool used by educational organizations to manage students, courses, and enrollments.
- Human Resource Systems (HRIS) - A software tool used by corporate organizations to manage employees and their data.
- Learner Information Systems (LIS) - A software tool used by educational organizations to manage the registration of student enrollments.
Components and products in the IPSIS platform
Under the IPSIS platform, there are common components and several products with unique features to integrate your specific information system with Brightspace. The collection of components and products are:
- D2L Standard CSV – Used for integrating with SIS/HRIS systems by using D2L-defined Comma-Separated Value (CSV) files.
- Ellucian ILP – Used for integrating with Banner or Colleague systems, based on LIS specifications.
- OneRoster CSV or OneRoster REST – Used for integrating with K-12 information systems that support the IMS Global Learning Consortium’s OneRoster specification.
- LIS v2.0 Adapter - Used for integrating with information systems that support the IMS Global Learning Consortium's LIS specification.
- SIS Course Merge - An interface in Brightspace used to enable instructors to merge and unmerge multiple IPSIS-processed courses into and out of one parent course offering.
- Section Association Interface (UI) - An interface in Brightspace used to manually manipulate relationships between enrollable courses or sections in an SIS and course offerings in Brightspace.
- IPSIS Administration Interface (Admin UI) - An administration interface in Brightspace used for configuring and reviewing the status of SIS integrations with Brightspace.
About OneRoster 1.1 REST
OneRoster is an IMS standard designed to allow secure sharing of class rosters and related data between a student information system (SIS) and any other system. The OneRoster standard supports spreadsheet-style (CSV) export-import as well as direct system exchanges using REST API’s. This administration guide focuses on the REST specification.
Before you use OneRoster REST 1.1
D2L supports the IMS OneRoster v1.1 specification and recertifies against the IMS Global product certification suite yearly. D2L supports the following Conformance Certifications:
- REST Data Provider Gradebook Push Core
- REST Data Consumer Rostering Core
The Brightspace implementation of the OneRoster v1.1 specification lets administrators schedule data to be pulled from their SIS to populate the required roster related data (schools, classes, users, enrollments, etc.) in the Brightspace platform. The new IPSIS OneRoster REST user interface includes a schedule to allow administrators to configure the time of day when the data pulls occur. Additionally, for an SIS partner supporting the Gradebook service, administrators can set the grades to be returned with the daily data sync and/or allow a faculty member to initiate a manual sync.
Endpoints used
| Type |
URL |
|---|
| GET |
ims/oneroster/v1p1/academicSessions |
| GET |
ims/oneroster/v1p1/classes |
| GET |
ims/oneroster/v1p1/enrollments |
| GET |
ims/oneroster/v1p1/orgs |
| GET |
ims/oneroster/v1p1/orgs/{id} |
| GET |
ims/oneroster/v1p1/schools/{id} |
| GET |
ims/oneroster/v1p1/schools/{id}/classes |
| GET |
ims/oneroster/v1p1/schools/{id}/courses |
| GET |
ims/oneroster/v1p1/schools/{id}/enrollments |
| GET |
ims/oneroster/v1p1/users |
| GET |
ims/oneroster/v1p1/categories (+metadata required) |
| PUT |
ims/oneroster/v1p1/lineitems |
| PUT |
ims/oneroster/v1p1/results |
How OneRoster REST is mapping to Brightspace
Below are the mapping values between a OneRoster object type and a Brightspace object type
| One Roster |
D2L Brightspace |
|---|
Academic Sessions
|
Org Units* |
| Orgs |
Org Units* |
| Schools |
Org Units* |
| Courses |
Course Template |
| Classes |
Course Offering & Course Section |
| Users |
User
|
| Enrollments |
Enrollment
|
| LineItems |
Grade Item |
| Results |
Grade Value
|
*Org unit types are typically custom org unit types that can be mapped during the configuration process.
Academic Sessions
| OneRoster |
Supported Values |
Used by Brightspace for |
Required |
|---|
| sourcedId |
|
N/A |
Y |
| status |
active or tobedeleted |
Create/Replace or Delete |
Y |
| dateLastModified |
YYYY-MM-DDTHH:mm:SS.sssZ |
N/A |
Y |
| metadata |
N/A |
N/A |
|
| title |
|
Org Unit Name and Org Unit Code |
Y |
| startDate |
YYYY-MM-DD |
Exposed for academic session in gradebook |
Y |
| endDate |
YYYY-MM-DD |
Exposed for academic session in gradebook |
Y |
| type |
Semester, Term, Grading Period, SchoolYear |
Org Unit Type |
Y |
| parent |
N/A |
N/A |
N/A |
| Children |
N/A |
N/A |
N/A |
| SchoolYear |
N/A |
N/A |
N/A |
Orgs
| OneRoster |
Supported Values |
Used by Brightspace for |
Required |
|---|
SourcedId
|
|
N/A |
Y |
Status
|
active or tobedeleted
|
Replace or Delete |
Y |
DateLastModified
|
YYYY-MM-DDTHH:mm:SS.sssZ |
N/A |
Y |
MetaData
|
N/A |
N/A |
|
Name
|
|
Org Unit Name and Org Unit Code |
Y |
Identifier
|
|
Org Unit Code (If provided) |
N |
StartDate
|
YYYY-MM-DD |
N/A |
Y |
EndDate
|
YYYY-MM-DD |
N/A |
Y |
Type
|
District, Department, Local, National, School, State |
Org Unit Type |
Y |
Parent
|
|
Parent Org Units |
Required to create org structure |
Children
|
N/A |
N/A |
N/A |
Courses
| OneRoster |
Supported Values |
Used by Brightspace for |
Required |
|---|
SourcedId
|
|
N/A |
Y |
Status
|
active or tobedeleted
|
Active |
Y |
DateLastModified
|
YYYY-MM-DDTHH:mm:SS.sssZ |
N/A |
Y |
MetaData
|
N/A |
N/A |
|
| Title |
|
Org Unit Name and Org Unit Code |
Y |
| SchoolYear |
|
Parent Org Units |
N |
| CourseCode |
|
Org Unit Code (If provided) |
N |
| Grades |
N/A |
N/A |
|
| Subjects |
N/A |
N/A |
|
| Org |
|
Parent Org Units |
Required to create org structure |
StartDate
|
YYYY-MM-DD |
N/A |
|
EndDate
|
YYYY-MM-DD |
N/A |
|
| SubjectCodes |
N/A |
N/A |
|
| Resources |
N/A |
N/A |
|
Classes
| OneRoster |
Supported Values |
Used by Brightspace for |
Required |
|---|
SourcedId
|
|
N/A |
Y |
Status
|
active or tobedeleted
|
Active or Inactive |
Y |
DateLastModified
|
YYYY-MM-DDTHH:mm:SS.sssZ |
N/A |
Y |
MetaData
|
Not Mapped |
| Title |
|
Org Unit Name and Org Unit Code |
Y |
| ClassCode |
|
Org Unit Code (If provided) |
N |
| ClassType |
N/A |
| Location |
N/A |
| Grades |
N/A |
| Subjects |
N/A |
| Course |
|
Parent Org Units |
Y |
| School |
|
Parent Org Units |
Y |
| Terms |
|
Parent Org Units |
Y |
| SubjectCodes |
N/A |
| Periods |
N/A |
| Resources |
N/A |
Users
| OneRoster |
Supported Values |
Used by Brightspace for |
Required |
|---|
SourcedId
|
|
OrgDefinedId |
Y |
Status
|
active or tobedeleted
|
IsActive |
Y |
DateLastModified
|
YYYY-MM-DDTHH:mm:SS.sssZ |
N/A |
Y |
MetaData
|
Not Mapped |
| UserName |
|
UserName |
Y |
| UserIds |
Not 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 |
|
N/A |
N |
| Phone |
|
N/A |
N |
| Agents |
|
Brightspace Parent & Guardian |
N |
| Orgs |
Upper Org Unit Enrollments (With Role in Org) |
| Grades |
N/A |
| Password |
|
User Password |
N |
Enrollments
| OneRoster |
Supported Values |
Used by Brightspace for |
Required |
|---|
SourcedId
|
|
N/A |
Y |
Status
|
active or tobedeleted
|
Active |
Y |
DateLastModified
|
YYYY-MM-DDTHH:mm:SS.sssZ |
|
Y |
MetaData
|
N/A |
| User |
|
User to Enroll |
Y |
| Class |
|
Course Offering & Section to Enroll in |
Y |
| School |
N/A |
| Role |
|
Role |
Y |
| Primary |
N/A |
| BeginDate |
N/A |
| EndDate |
N/A |
Assumptions and Limitations
Assumptions
D2L can work with any SIS that supports OneRoster 1.1 REST and is certified with IMS Global or working towards their certification.
REST Process
- Scheduled runs run from the previous run date of the data extract to the start date of the current data extract. If this is the first run, it acts like a sync operation and runs with no start date to the date range.
- There is an option to trigger a run manually from the previous run date, from a specific date or for all records in the system
- Call Order: The order that the various endpoints or consuming the various files are called in.
Academic Sessions
Orgs
- Schools
Courses
Classes
Users
Enrollments
- The order that data is sent back to Synergy
- Lineitems (sent on demand or nightly based on grade export settings)
- Results (sent on demand or nightly based on grade export permissions)
Grade Export
For a grade to be exported, the course must have been created through OneRoster SIS integration and the OneRoster IPSIS source system must have Grades Export enabled. The course may only be mapped to one active source system with grades. Grades must belong to Grade Categories that are retrieved from the SIS and the grade must have an Academic Session selected.
Academic Sessions
The Academic Session (Terms) dropdown menu is visible when creating a new grade item. The menu is populated by finding all org units created by the same SIS as the course where the SIS mapping is for Academic Session. The academic session must be a parent to the course offering.
Categories
Categories are required for the integration. Categories created by Synergy have the Export to SIS option selected. This category is used to link grade items so that Brightspace knows which grade items should and should not be sent.
How the grade sync works
Grade items (line items) are synced if they meet any of the following conditions:
Note: The line item sourced id that gets sent is class-specific and is generated like this: {lineItemSourcedId}_{classSourcedId}
Grades (results) are synced if they meet any of the following conditions:
- Result has never been sent
- Result has been updated since it was last sent
- Result failed to be sent during the last export
- Parent line item has been modified since the last export
Note: Line items and Results that were sent to the SIS as deleted do not appear in the Export History UI.
Limitations
- Records with a status of tobedeleted are only deleted if the child is deleted.
- Enrollments into upper org units that were created before the June 2024/20.24.6 release cannot be unenrolled via the OneRoster integration.
- Enrollments that were created manually in Brightspace cannot be unenrolled via the OneRoster integration.
- Unsupported characters: there are several characters that are not supported in the Brightspace Org Unit Code. These characters are replaced with an underscore (_). Unsupported Characters: \ : ? “ ” < > | ‘ # , % &
- Truncations: The max length for the Org Unit Code in Brightspace is 50 characters. If it exceeds this length, it is truncated in the UI.
- OneRoster allows multiple ScoreStatus: Brightspace only sends fully graded or exempt
Configuration options for OneRoster REST
You will work with your Brightspace Implementation Consultant to set up your OneRoster REST source system. Brightspace automatically defaults to your most common settings. However, these settings can be edited at any time with the appropriate permissions.
Before the source system can be configured, make sure you have the following items completed:
General Requirements
Contact your OneRoster representative to obtain your API information. You will need:
- Endpoint URL
- Authentication Endpoint
- Client Id
- Client Secret
Configuration
After the initial set up, you can update the configuration of your OneRoster REST source system:
- From the Admin Tools menu, select IPSIS Administration, select the Configuration tab
- Credentials provided during initial set up will appear first, these credentials can be edited if required.
- Source System fields:
- SIS Name: The SIS Name field is editable and is recommended to be kept up to date.
- Scheduled Updates: The time that Brightspace will automatically sync with the SIS. It is recommended that this process is completed overnight.
- Overwriting Brightspace: Granular choices to identify which fields in Brightspace your SIS can overwrite.
- People
- SIS Role Mappings: This section contains the OneRoster specific role to map SIS role names to Brightspace role names. Teacher and Student roles are included by default, but they can be deleted. The following are the roles available in OneRoster:
- Administrator
- Aide
- Guardian
- Parent
- Proctor
- Relative
- Student
- Teacher
To add additional SIS specific role names to map to Brightspace roles, click + Add Role.Note: If the SIS sends a role that is not configured, it results in an error and the user cannot be created.
- Map SIS Entries to Existing Users: Provides the option to map SIS entries based on username or OrgDefinedId to existing users that were created outside of the SIS (manually, bulk operations, API, etc.). If mappings are off, duplicates may be created.
- Courses and Sections
- Courses and Sections - Mappings: This section contains the OneRoster specific org unit types to map SIS orgs to Brightspace org names.
- Click + Add Org Unit Type to add additional SIS specific org unit names. The following Org Unit Types are required for Synergy:
- SIS Orgs
- District
- School
- Local, National, State, and Department are optional
- Academic Session Type
- Semester
- Term
- SchoolYear
- GradingPeriod
- SIS Group
- Course Offering
- Course Section
- Course Template
- Section Association
- Deletion: Provides two options on how a tobedeleted status affects an org unit in Brightspace.
- Do Nothing – the org unit mapping will be deleted from IPSIS mappings, but the org unit will remain unchanged in Brightspace
- Inactivate course offering – the org unit mapping will be deleted from IPSIS mappings, the course offering will be marked inactive in Brightspace, section and enrollments will remain
- Map SIS entries to courses and sections: Provides the option to map SIS entries based on org unit code to existing org units that were created outside of the SIS (manually, bulk operations, API, etc.). It is not recommended to turn these on for any org units created by your SIS unless you confirmed the codes are unique across schools and school years.
- Course Content: Provides the ability to copy course content from a master course or a course template to the newly created course. Select Yes and choose one of the following:
- If Find an Org Unit to automatically copy from based on specified criteria? is not selected, content is copied from a Master Course Offering to the sibling Course Offering when the Master Course Offering and Course Template share the same Org Unit Code
- If Find an Org Unit to automatically copy from based on specified criteria? is selected, you can choose from two options:
- Parent course template of the new course
- Content is copied from the parent Course Template to the new child Course Offering
- Sibling course where the Org Unit Code matches the parent template. Content is copied from the source course offering to the new child Course Offering based on the source course being manually added to Brightspace with the same org unit code as the parent template.
- Unenrollment: Provides the option to unenroll users from sections and courses based on the enrollment End Date provided by the SIS, and the option to unenroll users from SIS Orgs if they’re no longer associated with them in the SIS.
- Grades Export
- Provides the option to allow grade syncs of all modified grade items at the time of the Scheduled Update, and/or, to allow Teacher initiated grade export from the course offering.
- Departments, Semesters and Other
Map SIS entries to existing org units: Provides the option to map SIS entries based on org unit code to existing org units that were created outside of the SIS (manually, bulk operations, API, etc.). It is not recommended to turn these on for any org units created by your SIS unless you confirmed the codes are unique across schools and school years.
- Once complete, select Save Configuration.
Troubleshooting
The Dashboard provides the processing status of the latest batch. Both the Dashboard and Batches pages show a final indicator if the batch completed successfully or with errors. Each batch has a quick link to the Audit Log and if completed with errors to Error Messages.
Review all logs to verify all records processed as expected. If error messages were logged, expand the error to review the metadata captured to identify the error, correct the data in your SIS and either wait until the next day for the Scheduled Update or request an update from the Dashboard. The goal is to have the runs completed without error.
How to sync Grades
Grades can be sent nightly with the daily roster update, on demand via the grades interface, or both. These options are set up in IPSIS Administration > Configuration > Export Grades.
To send grades, a category, grade item, and grade are required. See the Grades Export section for overall rules to send a grade.
Category
Categories are automatically created by Synergy. These categories are noted in the Manage Grades UI with an SIS icon.
Create a Grade Item
- In the Manage Grades area, click New and select Item.
- Set the desired preferences and options for the category.
- Choose an Academic Session from the dropdown menu.
- Select the End of Course checkbox if the assignment should be sent as an End of Course assignment.
- Map the grade item to the Category synced with the SIS.
- Click Save and Close.
Export to SIS
To manually sync grades to the SIS:
- From the course home page, navigate to Grades> Enter Grades > Export to SIS
- On the Export Grades UI, you are presented with a summary page that includes:
- Section: a dropdown menu that allows you to choose between different sections in the course (if multiple sections are present)
- Academic Session: a dropdown menu that allows you to choose between different School Years associated with the course (if multiple academic sessions are used)
- Overview: Lists the number of Categories and the number of grades within the categories that meet the criteria selected in Section and Academic Session above and can be exported
- Scheduled Export: only visible if configured in SIS Integration configuration and can be edited in the Configuration tab in IPSIS Administration
- Click Export. The page refreshes and takes you to the View All Exports page. This UI provides an overview of who sent the grades and when.
- Once the export has completed, click on the Export Name to view details that include: Course name, Export start and end dates, and User who initiated the export
Note: If grades are sent via the nightly sync the IPSIS Service user is displayed
- Successful and failed export details for Categories, Grade Items and Results:
- You can navigate back to historical exports, using Grades > Enter Grades > Export to SIS and click View Export History at the top right.
Use academic session information for course start and end dates
On the IPSIS administration page the Course offering dates check box allows you to use academic session information for course offering start and end dates.
This check box is set to off by default. This option allows you to choose if academic session (semester, term, school year, or grading period) dates are associated to the course offering (this option defaults to term).
The start date and end date of a course can also be offset by a specified number of days. If multiple academic sessions are set for a single course offering, the first Academic Session received from the SIS will be used for the start and end dates.