OneRoster CSV

Description

ManageBac+ allows administrators to import and export users, classes, enrollments, and related data using a customized version of the OneRoster 1.2 standard. This feature is accessible under Settings > Data Exchange and includes validation reports to ensure data is correct before importing.

The OneRoster standard is developed and maintained by IMS Global Learning Consortium and provides a framework for this data exchange. The resource that describes the technical implementation can be referenced here:

ManageBac+ OneRoster 1.2 CSV Custom Specification

Exporting

An export in ManageBac+ refers to the process of transferring data from the system to an external format, allowing users to share, back up, or integrate information with other systems.

To begin the export, navigate to the Export tab in the Data Exchange Manager

If you see Step 2 - Mode Options (BULK and DELTA), it means another administrator has already completed an export. Select the desired export method and click Proceed to Export.

Bulk Export and Delta Export in ManageBac+ serve different purposes in data management:

• Bulk Export: This process exports all relevant records in one go. It is typically used when a complete dataset is needed, such as during an initial setup or when transitioning to a new system. This method ensures that all existing data is captured and transferred.
• Delta Export: This process exports only the records that have changed since the last export, such as newly created, updated, or deleted entries. It helps keep the data up to date without transferring the entire dataset, making it more efficient for ongoing synchronization. Delta export can only be performed after a bulk export has been completed.

Once Proceed to Export has been clicked, the export job will start in the background and navigate the user to the Exchange History tab.

When it is completed, locate your latest export and click the Download button (downward-facing arrow) to retrieve the ZIP file.

Review the downloaded file. The file contents will contain all the entities and how they are represented in ManageBac+'s Custom Specification.

Importing

To start the import process via the Data Exchange Manager, select your ZIP file in the Import tab.

Choose the OneRoster ZIP file from your computer and upload it by clicking Save.

Enter the required fields:
If your manifest.csv file does not include source.systemname and source.systemcode two fields will appear below the upload area for you to fill in. For more details, refer to the File Specifications > manifest.csvsection.
If these values are already in the manifest.csv file, the fields will be pre-filled and you cannot enter them.

Once everything is set, click the Proceed with Validation button at the bottom. This starts the import job, which runs OneRoster and ManageBac+ validations in the background.

Only one OneRoster import can proceed at a time.

Check the import status via the Exchange History tab at the top. Once the import has finished, locate your latest import, and review the validations.

The Exchange Report page will open, displaying a Summary and all the uploaded CSV files from your OneRoster ZIP.

In each CSV tab, errors and warnings will be highlighted in the respective colours within the cells where the issues exist.

There are three tabs, with Invalid being the default tab initially selected:

Valid — contains all rows with no warnings or validation failures
Warning — contains all rows with at least one warning
Invalid — contains all rows with at least one invalid

To understand the associated message with the warning or invalidation, click to expand the row information:

Warnings are potential issues that do not block importing. Administrators can choose to ignore it, or make adjustments, depending on context.

Invalid records do not meet the functional requirements and import cannot proceed.

After addressing all issues that resulted in an invalidation, perform a new import using the updated ZIP file.

Data Entities

The table below illustrates how different ManageBac+ entities correspond to OneRoster 1.2 entities and CSV files, ensuring seamless data exchange while accounting for variations in data models.

For example, a ManageBac+ Student corresponds to a OneRoster User with the role "Student." In OneRoster, Users and Roles are defined in users.csv and roles.csv, respectively.

The Data Exchange Manager only updates the records listed above and does not modify any other data.

Delta Import vs Bulk Import

A key distinction in the Data Exchange process is the difference between a delta import and a bulk import.

• Delta Import:
  • Matches and updates existing ManageBac+ records.
  • Creates new records if they do not already exist.
  • Leaves records not included in the source data unchanged.
• Bulk Import:
  • Performs the same actions as a delta import (matching, updating, and creating records).
  • Additionally, archives any active records in ManageBac+ that are not present in the source data.
  • For example, if a class like "IB Biology" is active in ManageBac+ but missing from the source data, it will be archived after the import is processed.

In summary, a bulk import not only creates and updates records from the source data but also archives any records that are missing from it.

If performing a bulk import during an Academic Year Transition, please note that OneRoster does not include Year Groups, so these must be managed separately.

Record Matching on Import

During both delta and bulk imports, ManageBac+ uses two main strategies to match records from the source data with those in the system:

1. If a sourcedId has been previously used, it directly matches to the corresponding record using the matching method described in the next point.
2. If matching by sourcedIds is not available or it's the first encounter, the following table outlines the matching strategy for each entity:

Frequently Asked Questions

Question: What is OneRoster and why is ManageBac+ using a custom specification of it?

OneRoster is a widely adopted specification developed by the IMS Global Learning Consortium to standardize the exchange of educational data like student information, course data, and enrollments between different systems. ManageBac+'s implementation of OneRoster 1.2 uses a custom specification, referred to as the "ManageBac+ OneRoster Dialect" (MB OR Dialect), because the base OneRoster specification's data model differs from ManageBac+'s functional requirements. This customization allows ManageBac+ to import and export records in a way that aligns with its internal data structure and features.

Question: What files are included in a ManageBac+ OneRoster import/export and which are mandatory?

ManageBac+ OneRoster data is exchanged as a zip archive containing CSV files. The manifest.csv file is mandatory. The following files are optional but must be present in the archive if their corresponding entities are included: academicSessions.csv, orgs.csv, courses.csv, classes.csv, roles.csv, users.csv, enrollments.csv, and demographics.csv. Note that empty optional files must contain the required column headers.

Question: What columns does each file need, and what are legal values?

These details are provided in the the resource that describes the technical implementation, which can be referenced here:

ManageBac+ OneRoster 1.2 CSV Custom Specification

Question: What are the validation rules for importing OneRoster data into ManageBac+?

ManageBac+ applies several universal validations to all imported CSV files. The results of these validations are reported in the Data Exchange history tab. Each entity has a set of validations, the details of which are provided in the the resource that describes the technical implementation, which can be referenced here:

ManageBac+ OneRoster 1.2 CSV Custom Specification

Question: What are the differences and potential incompatibilities when exchanging data between ManageBac+ and other OneRoster 1.2 compliant systems?

When exporting data from ManageBac+ to a third-party system that implements standard OneRoster 1.2, the export is generally compatible. ManageBac+ includes additional metadata columns in files like Users, Courses, and Classes, which can typically be ignored by the receiving system.

However, when importing data from a third-party system into ManageBac+, certain requirements need to be met due to ManageBac+'s custom specification. For example, Classes and Courses must be associated with organizations having a specific type (ext:program), and additional meta columns might be required in User, Course, and Class files. Academic Sessions also have partial compliance when importing.

Question: What is the difference between a "Bulk" and a "Delta" export in the ManageBac+ Data Exchange Manager? A Bulk export is a full export of the selected data, providing a complete snapshot of the current information in ManageBac+. This is typically performed as the initial export. A Delta export, on the other hand, only exports the changes (additions, modifications, and deletions) that have occurred since the last successful Bulk export. To perform a Delta export, you must have completed at least one Bulk export beforehand.

Question: Where do I specify the source system name and code when importing a OneRoster ZIP file into ManageBac+?

ManageBac+ requires a source.systemname and source.systemcode to identify the origin of the OneRoster data, especially when rostering data from multiple Student Information Systems. If these fields are not already included in your manifest.csv file, you will be prompted to enter them manually after uploading the ZIP file in the Data Exchange Manager. These values should be consistent across imports from the same source system.

Question: Why can't I select the Delta method for my export?
Answer: To enable the Delta method, you must complete your first bulk export. Once the initial bulk export is done, the Delta method will become available. The Delta method exports changes since the last full Bulk export.

Question: Where do I indicate Year Groups in ManageBac+'s Custom OneRoster Specification?
Answer: Year Groups is not supported at this time, although we are exploring working with OneRoster to support the necessary extensions needed to meet ManagaBac's functionality requirements. It is recommended to maintain Year Group membership via Settings -> Roster -> Memberships.

Question: What does the status on the Exchange History page mean?
Answer: ManageBac+ has four different statuses with the following explanations:
Scheduled - This means that the system has successfully scheduled the import, and has been queued to start at a later time. When started, it will transition to Processing.
Processing - This means the system is currently working on the background task for your export or import. It is temporary and will change to one of the statuses below.
Failed - If this status appears, it means the background task couldn’t be completed. For export errors, please contact the ManageBac+ Support team (support@managebac.com). For import errors, click the Eye icon to open the Report View page, check the validation errors, and fix them for your next import.
Successful - This means the task was completed without any errors.