> For the complete documentation index, see [llms.txt](https://guide.fariaedu.com/managebac-oneroster-custom-specification/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.fariaedu.com/managebac-oneroster-custom-specification/user_guide.md). # User Guide ## Description ManageBac allows administrators to import and export users, classes, enrollments, and related data using a customized version of the [OneRoster 1.2 standard](https://www.imsglobal.org/spec/oneroster/v1p2). 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. Technical details about ManageBac's custom implementation are available on GitHub. ## Mapping The below table illustrates the mapping across different categories of data that facilitates the direct exchange of information, accounting for different assumptions in the data model. | OneRoster 1.2 Entity(ies) | ManageBac Entity | OneRoster CSV file(s) | | ------------------------------------------ | --------------------------- | -------------------------------------- | | Organizations -> District | n/a | orgs.csv | | Organizations -> School | School | orgs.csv | | Organizations -> Program Ext | Programs | orgs.csv | | Academic Sessions -> School Year | Academic Years | academicSessions.csv | | Academic Sessions -> Term | Academic Terms | academicSessions.csv | | Courses | Subject Groups | courses.csv | | Courses -> Subjects | Subjects | courses.csv | | Classes | Classes | classes.csv | | (1)Users (2)Roles->Student (3)Demographics | Students | users.csv, roles.csv, demographics.csv | | (1)Users (2)Roles->Teacher | Teachers | users.csv, roles.csv | | (1)Users (2)Roles -> Parent | Parents | users.csv, roles.csv | | (1)Users (2)Roles->Admin | Administrators | users.csv, roles.csv | | Users->Agents | Parent / Child Relationship | users.csv | | Enrollments | Class Memberships | enrollments.csv | This table highlights how ManageBac data aligns with the **OneRoster** data model. 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. Some differences in data structure are handled using **OneRoster extensions**, which are described in a separate section. The **Data Exchange Manager (OneRoster CSV)** 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 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: If a **sourcedId** has been previously used, it directly matches to the corresponding record using the matching method described in the next point. If matching by **sourcedIds** is not available or it's the first encounter, the following table outlines the matching strategy for each entity: | Entity | Source Column (OR) | Matched to (MB) | | ----------------- | -------------------------------------------------------- | ---------------------------------------- | | School | `orgs.types` == "school" | Only 1 record, matches to current school | | Program | `orgs.types` == "ext:program", `orgs.identifier` | Program code | | Academic Sessions | `academicSessions.startDate`, `academicSessions.endDate` | Year / Term start / end dates | | Courses | `courses.title` | Subject Group Title | | Subjects | `courses.subjects[]` | Subject Title | | Classes | `classes.classCode` | Class ID | | Users | `users.identifier` | Student / Teacher / Parent ID | ## Export 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. Delta Export and Bulk Export in ManageBac serve different purposes in data management: * **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. * **Bulk Export**: In contrast, 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://guide.fariaedu.com/managebac-oneroster-custom-specification/user_guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.