Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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. Technical details about ManageBac's custom implementation are available on GitHub.
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.
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.
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:
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:
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.
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
Subjects
courses.subjects[]
Subject Title
Classes
classes.classCode
Class ID
Users
users.identifier
Student / Teacher / Parent ID
Organizations -> District
n/a
orgs.csv
Organizations -> School
School
orgs.csv
Organizations -> Program Ext
Programs
orgs.csv
Academic Sessions -> School Year
Academic Years
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
academicSessions.csv
Subject Group Title
role_not_match
The role cannot match the ManageBac role
models
role_cannot_be_deleted
The role cannot be deleted because a user cannot exist without a role
models
user_has_secondary_roles
User has primary and secondary roles, only primary would be used
models
cannot_modify_persisted_class
The existing class was matched by classCode, but certain attributes are restricted from being modified
models
cannot_modify_homeroom_subject_group
The existing Homeroom subject group was matched, but certain attributes are restricted from being modified
models
cannot_modify_common_subject_codes
The code cannot be changed for the common subjects: %{subject_names}
models
user_not_match
The enrollment cannot be matched with managebac user
models
class_not_match
The enrollment cannot be matched with ManageBac Class
models
ManageBac's support of OneRoster 1.2 is implemented via a custom specification. ManageBac exports and imports records by adopting OneRoster extensions. The special handling is necessary due to differences in the data model provided by the base OneRoster specification and ManageBac's functional requirements.
Due to this requirement, exports from source systems using the base OneRoster specification will require additional transformations or adjustments to the source data. To request that a source system, such as an MIS or SIS, export in ManageBac's custom specification, please contact the vendor.
This document will describe this custom specification by explaining the additional validations, required columns, and formatting required by ManageBac. This custom OneRoster specification is coined "ManageBac OneRoster Dialect" or "MB OR Dialect" for short.
The formal specification for base OneRoster CSV Binding is hosted by IMS Global.
The custom OneRoster specification validates the contents of the file according to requirements of ManageBac's data model.
ManageBac accepts zip archives that must contain the following file:
manifest.csv
The following files are not strictly required. If no such records for a given entity are to be included, the file associated with that entity can be optionally marked "absent" in the manifest. Otherwise, when marked "present", the file is required to be present in the archive:
academicSessions.csv
orgs.csv
courses.csv
classes.csv
roles.csv
users.csv
enrollments.csv
demographics.csv
The zip archive must have the ".zip" extension and the .csv files contain ordered columns. An empty file must still contain the requisite columns. For the required columns for each entity, see the respective details.
ManageBac processes every row and every file with the following commmon validations:
Every row must have a non-blank sourcedId and is unique across all the files
In delta mode, dateLastModified is included and non-blank and is a date
In delta mode, status is included and non-blank, and is either "active" or "tobedeleted"
In bulk mode, dateLastModified and status are included and values are blank
All dates values must be in ISO 8601 format
Additional row-level validations that apply to specific files are enumerated in the respective area under the heading "Import Validations."
In OneRoster there are two entities that have grade properties: students and classes.
The OneRoster grade property corresponds to ManageBac's core grade entity, which is found in the frontend in the table Settings > Schools Settings: Grades & Labels (Y axis).
The tables below indicate how this grade information corresponds to each other. Note that the "MB Core grade label" refers to an annotation in the table, and not the string used to represent the student's grade on their profiles.
IT
n/a
n/a
PR
-2
Pre-K2
PK
-1
Pre-K3
TK
0
-2
PR
-1
PK
0
TK
1
KG
2
01
3
02
Pre-K4
KG
1
Kindergarten
01
2
Grade 1
02
3
Grade 2
03
4
Grade 3
04
5
Grade 4
05
6
Grade 5
06
7
Grade 6
07
8
Grade 7
08
9
Grade 8
09
10
Grade 9
10
11
Grade 10
11
12
Grade 11
12
13
Grade 12
4
03
5
04
6
05
7
06
8
07
9
08
10
09
11
10
12
11
13
12
ManageBac Academic Sets — comprised of Academic Years and their associated Academic Terms — are represented in the academicSessions.csv file. This custom specification allows these entities to be specified in one file to satisify functional requirements.
The columns of the academicSessions.csv file must be in the following order:
Given that ManageBac's Academic Years must have at least one Academic Term, this file uses a combination of the type and the parentSourcedId columns to express the relationship. In addition, ManageBac requires that a year and associated terms be associated to a Program. The following required relational columns describe these relationships:
The type column can take three possible values that ManageBac supports:
In Bulk mode, academic sessions that are not present in the source data set, and do not have any relationships to classes or grades, are deleted.
This is the expected behavior for freshly-created or blank schools.
A row whose type -> schoolYear must have a blank parentSourcedId
There must be at least one type -> term row for every type -> schoolYear row that is associated via parentSourcedId.
There must be one row
A row of type -> schoolYear for each Program with a blank parentSourcedId
A type -> term row for each Academic Term in each Program, associated to the parent type -> schoolYear row, comprising a ManageBac Academic Set.
Each row belonging to the same Academic Set's metadata.managebac.orgSourcedId
Description of the columns for core columns for term and schoolYear rows:
Every row must have a sourcedId that uniquely identifies the row
The startDate must be prior to endDate
For each enabled Program, the associated academic year and child academic terms are exported.
The following columns values depend on the import or export mode:
The orgs.csv file expresses hierarchy in an organizational structure. Each row represents a unique organization, where the type column indicates the kind of organization the record is referring to.
The columns of the enrollments.csv file must be in the following order:
no
Required by OneRoster
type
yes
no
Required by OneRoster
startDate
yes
no
Required by OneRoster
endDate
yes
no
Required by OneRoster
parentSourcedId
yes
yes
Required by MB for type -> term
schoolYear
yes
yes
Required by OR, but can be blank as it is ignored
metadata.managebac.orgSourcedId
yes
no
Required by MB. The value must be a sourcedId of the org of type -> ext:program
type -> schoolYeartype => ext:programRows of type -> schoolYear must have startDate and endDate that fall within range the ManageBac's calendar for the Program resolved by metadata.managebac.orgSourcedId. The corresponding startDate and endDate of associated type -> terms must also fall within range of the same Program.
All type -> schoolYear and type -> terms that are associated with each other, via the parentSourcedId column for type -> term rows constitute a ManageBac Academic Set. They must all resolve to the same type -> ext:program in orgs.csv via metadata.managebac.orgSourcedId.
The startDate and endDate of an Academic Set cannot overlap each other.
Can the endDate = next startDate?
type -> ext:program2019-07-31
2019
6a9d...2d8f_myp
4a18...ccf02
First Term
term
2018-08-01
2018-12-31
9bbd...d4e0
2019
6a9d...2d8f_myp
2693...613f
Second Term
term
2019-01-01
2019-07-31
9bbd...d4e0
2019
6a9d...2d8f_myp
d895...f35f
August 2018 – July 2019
schoolYear
2018-08-01
2019-07-31
2019
6a9d...2d8f_diploma
3099...fff8c
First Term
term
2018-08-01
2018-12-31
d895...f35f
2019
6a9d...2d8f_diploma
3142...4644
Second Term
term
2019-01-01
2019-07-31
d895...f35f
2019
6a9d...2d8f_diploma
sourcedId
yes
no
Required by OneRoster
status
yes
must be blank for bulk, must be populated for delta
Follows OneRoster convention
dateModified
yes
must be blank for bulk, must be populated for delta
Follows OneRoster convention
title
sourcedId
Uniquely identifies the record
Used referentially
type
The kind of academic session
"year" | "term" | "semester"
parentSourcedId
Refers to the parent organization
"zxc-ksdf_org_1"
metadata.managebac.orgSourcedId
Associated to org of type ext:program
schoolYear
A collection of terms
term
A date range for when classes are scheduled
semester
A synonym for "term".
title
The name of the record
Ignored, may be blank
startDate
When the term begins
Helps to match on existing records
endDate
When the term ends (the last day of term)
Helps to match on existing records
schoolYear
The year of the last academic term of the current academic year
Ignored
status
Must be present but emtpy
Must be present and either "active" or "tobedeleted"
dateLastModified
Must be present but empty
Must be present and a date
9bbd...d4e0
August 2018 – July 2019
schoolYear
yes
"xcv-zxc_org_1_diploma"
2018-08-01
1
sourcedId
yes
no
2
status
yes
must be blank for bulk, must be populated for delta
3
dateModified
yes
must be blank for bulk, must be populated for delta
4
birthDate
yes
yes
5
sex
yes
yes
6
americanIndianOrAlaskaNative
yes
yes
7
asian
yes
yes
8
blackOrAfricanAmerican
yes
yes
9
nativeHawaiianOrOtherPacificIslander
yes
yes
10
white
yes
yes
11
demographicRaceTwoOrMoreRaces
yes
yes
12
hispanicOrLatinoEthnicity
yes
yes
13
countryOfBirthCode
yes
yes
14
stateOfBirthAbbreviation
yes
yes
15
cityOfBirth
yes
yes
16
publicSchoolResidenceStatus
yes
yes
The sourcedId column resolves to a student in users.
sourcedId
Uniquely identifies the record
Matched to user.sourcedId
These columns represents extended attributes for the given student.
birthDate
birthday
Updates
sex
gender
Matches to Student ID, Parent ID or Teacher ID
OneRoster includes the following columns, but do not match to a ManageBac attribute:
americanIndianOrAlaskaNative
-
Ignored
asian
-
Ignored
blackOrAfricanAmerican
-
Ignored
nativeHawaiianOrOtherPacificIslander
-
The following columns values depend on the import or export mode:
status
Must be present but emtpy
Must be present and either "active" or "tobedeleted"
dateLastModified
Must be present but empty
Must be present and a date
1
sourcedId
yes
no
Required by OneRoster
2
status
yes
must be blank for bulk, must be populated for delta
Follows OneRoster convention
3
dateModified
yes
must be blank for bulk, must be populated for delta
Follows OneRoster convention
4
name
There are two columns in orgs.csv that represents how the specified organizations are related to each other:
sourcedId
Uniquely identify the row
Used referentially
type
The kind of organization
Informs validations
parentSourcedId
Refers to the parent organization
Informs validations
Together, the type column and parentSourcedId translates the information contained in this file into a hierarchy. There are three Organizations that ManageBac understands: district, school, and the custom type ext:program:
district
A collection of ManageBac instances
Ignored
school
A specific instance of ManageBac / subdomain / school
Used referentially only
ext:program
A ManageBac Program, for example "IB Diploma"
Used referentially only
ext:year_group
A ManageBac Year Group, for example "Class of 2025"
There can only be one row of type -> district, or no such row
There must be only one row of type -> school
Only rows whose type -> district or type -> school can have a blank parentSourcedId
A row with non-blank parentSourcedId value must resolve to a row with matching sourcedId
A row with type -> ext:program must have its parentSourceId resolve to a school that the the given program enabled
A single row of type -> school is exported, with blank parentSourcedId
A row for each enabled Program is exported, with type -> ext:program
Each Program rows will have populated parentSourcedId values that points to the school row.
The org.csv file includes some core columns that represent the individual organization:
name
Name of the organization
No modification occurs
identifier
The human-readable code for the org, if available
Ignored
Name cannot be blank
The School and all enabled Programs are exported.
The following columns values depend on the import or export mode:
status
Must be present but emtpy
Must be present and either "active" or "tobedeleted"
dateLastModified
Must be present but empty
Must be present and a date
6a9d...2d8f
MYS checking
school
6a9d...2d8f_diploma
1
sourcedId
yes
no
Required by OneRoster
2
status
yes
must be blank for bulk, must be populated for delta
Follows OneRoster convention
3
dateModified
yes
must be blank for bulk, must be populated for delta
Follows OneRoster convention
4
classSourcedId
sourcedId
Uniquely identifies the record
Used referentially
classSourcedId
Refers to the class in classes.csv
Matched to classes.csv
schoolSourcedId
Refers to the school in orgs.csv
Matched to orgs.csv
userSourcedId
Refers to the user in users.csv
The schoolSourcedId must resolve to a row in org.csv of type -> school
The userSourcedId must resolve to a row in roles.csv with and a role of either "systemadministrator", "teacher" or "student"
Every row represents a single enrollment for either a Student, Teacher, or Administrator
role
The role of the user
Validated
The role must be either "systemAdministrator" "student" or "teacher"
The role must be the same as the role in roles.csv for the user referenced
Enrollments for ManageBac Administrators, Students, and Teachers are exported. Parents are not directly enrolled into classes; instead they inherit enrollments from associated children.
beginDate
When the enrollments started, always the Start Date of the Class
Ignored, defined via terms
endDate
When the enroolment ended, always the End Date of the Class
Ignored, defined via terms
primary
Whether the enrollment is "primary"
Ignored
The following columns values depend on the import or export mode:
status
Must be present but emtpy
Must be present and either "active" or "tobedeleted"
dateLastModified
Must be present but empty
Must be present and a date
5ce2...3d44
c4bb...bfd0
6a9d...2d8f
Roles specify whether users are Students, Parents, Teachers, or Account Admins.
The columns of the roles.csv file must be in the following order:
All of the following columns are required:
Only rows with role value of either "systemAdministrator", "teacher" "parent", "student", and are consumed; all others are skipped
Only rows with roleType value of "primary" are consumed; all others are skipped
The roles supported are:
Assigning students to year groups is supported through the use of orgSourcedId on the roles entity. The following table describes the behavior depending on several factors:
When the roleType is "student"
What type the associated org given by orgSourcedId is
The presence of year groups already on ManageBac
On bulk import, users not listed in the source are archived, except for Observer user types.
All users are exported with one role and "primary" roleType
There are no columns for this entity that are required but not relational, i.e. no "Core" columns.
The following columns values depend on the import or export mode:
yes
no
Required by OneRoster
5
type
yes
no
Required by OneRoster
6
identifier
yes
yes
Optional in OneRoster and MB
7
parentSourcedId
yes
yes
Required by MB for rows of type -> ext:program. The value must be a sourcedId of the org of type -> school.
8
metadata.managebac.grade
yes
yes
Required by MB for rows of type -> ext:year_group
Used referentially only
IB Diploma
ext:program
IB DP
6a9d...2d8f
6a9d...2d8f_myp
IB Middle Years
ext:program
IB MYP
6a9d...2d8f
yes
no
Required by OneRoster
5
schoolSourcedId
yes
no
Required by OneRoster
6
userSourcedId
yes
no
Required by OneRoster
7
role
yes
no
Required by OneRoster
8
primary
yes
yes
MB does not use this field
9
beginDate
yes
yes
MB does not use this field
10
endDate
yes
yes
MB does not use this field
Matched to users.csv
4d74...ed70
student
2018-08-01
2019-07-31
2003-09-13
female
Ignored
demographicRaceTwoOrMoreRaces
-
Ignored
hispanicOrLatinoEthnicity
-
Ignored
countryOfBirthCode
-
Ignored
stateOfBirthAbbreviation
-
Ignored
cityOfBirth
-
Ignored
publicSchoolResidenceStatus
Ignored
4d74...ed70
2000-05-01
male
b403...558b
no
Required by OneRoster
5
roleType
yes
no
Required by OneRoster
6
role
yes
no
Required by OneRoster
7
beginDate
yes
yes
MB does not use this field
8
endDate
yes
yes
MB does not use this field
9
orgSourcedId
yes
no
Required by OneRoster
10
userProfileSourcedId
yes
yes
MB does not use this field
userSourcedId
Points to the row in the user.csv file
Used referentially
ext:year_group
n/a
Add to the year group explicitly.
6a9d...2d8f
b403...558b
b403...558b
primary
student
6a9d...2d8f
1
sourcedId
yes
no
Required by OneRoster
2
status
yes
must be blank for bulk, must be populated for delta
Follows OneRoster convention
3
dateModified
yes
must be blank for bulk, must be populated for delta
Follows OneRoster convention
4
userSourcedId
sourcedId
Uniquely identifies the record
Used referentially
role
The user role
Cannot be modified
roleType
Primary or secondary
Cannot be modified
orgSourcedId
For students: Indicates the associated program; for others should be school
ManageBac Role
role Value
Student
student
Parent
parent
Teacher
teacher
Admin
systemAdministrator
ext:school
There is only one year group at the student grade
Add to year group implicitly.
ext:school
There is none or many year groups at the student grade
No action, warning "Cannot add to any year group" emitted.
ext:program
There is only one year group with the student's grade and the given program.
Add to year group implicitly.
ext:program
There is none or many year group with the student's grade and given program
beginDate
Not used
Ignored
endDate
Not used
Ignored
userProfileSourcedId
Not used
Ignored
status
Must be present but emtpy
Must be present and either "active" or "tobedleted"
dateLastModified
Must be present but empty
Must be present and a date
4d74...ed70
4d74...ed70
primary
yes
Cannot be modified
No action, warning "Cannot add to any year group" emitted.
student
1
sourcedId
yes
no
Required by OneRoster
2
status
yes
must be blank for bulk, must be populated for delta
Follows OneRoster convention
3
dateModified
yes
must be blank for bulk, must be populated for delta
Follows OneRoster convention
4
title
Note:
gradesis required because classes in ManageBac must have a grade associated with them.
sourcedId
Uniquely identifies the record
Used referentially
schoolSourcedId
Refers to the school in orgs.csv
Cannot be modified
termSourcedIds
List of applicable academic terms in academicSessions.csv
courseSourcedId
Refers to the subject group in courses.csv. For PYP homeroom classes, refers to the homeroom subject group
Every class must have courseSourcedId value that represents the Subject Group and Program associations
Every term listed must be associated to the same Program, and there are no gaps in the duration as given from the first startDate to the last endDate
Does this mean you can't skip a date?
Every item listed in metadata.managebac.courseSourcedIds (if present) must match a Subject Group title in the IB PYP
The course resolved by courseSourcedId must belong to the same Program as the terms resolved in termSourcedIds
Each item in termSourcedIds must resolve to a type -> term row in academicSessions.csv
Every non-archived class will be represented on export
title
The name of the class
Updated
grades
The grade associated to the Class, only one
Cannot be modified
classCode
Human-readable ID
Matches on Class ID
classType
One of their "homeroom" or "scheduled"
The grades must be one element, and be the same grade for indicated Subject Group, and must be offered for the associated Program
Every row must have a Subject and Grade
Every given classCode must be unique in the file, no duplicates are allowed
classCode may be blank, but on import it will create a new class the first time it is imported
Note that subjects for IB PYP classes, more complete subjects associations are expressed through the metadata.managebac.courseSourcedIds
Column and Program combinations not delineated above are not required and can be left blank.
If the title is blank, then the default naming convention is applied
All non-archived classes with terms within the current academic year are exported
All non-archived classes with terms within the current academic year that are associated to an active subject are exported with status of "active"
All archived classes with terms within the current academic year that are associated to an active subject are exported with status of "tobedeleted"
All non-archived classes with terms within the current academic year that are associated to an inactive subject are exported with status of "tobedeleted"
The following columns values depend on the import or export mode:
status
Must be present but emtpy
Must be present and either "active" or "tobedeleted"
dateLastModified
Must be present but empty
Must be present and a date
yes
no
Required by OneRoster
5
grades
yes
no
Required for new classes. If row is matched on classCode or sourcedId, is ignored
6
courseSourcedId
yes
no
Required by OneRoster
7
classCode
yes
yes
Optional in both ManageBac and OneRoster
8
classType
yes
no
Required by OneRoster
9
location
yes
yes
MB does not use this field
10
schoolSourcedId
yes
no
Required by OneRoster
11
termSourcedIds
yes.
no.
MB requires classes to be associated to academic year(s)
11
subjects
yes
yes
MB requires classes to be associated to subjects
12
subjectCodes
yes
yes
Optional in both OneRoster and MB
13
periods
yes
yes
MB does not use this field
14
metadata.managebac.courseSourcedIds
yes
no
Required only for PYP classes
Cannot be modified
metadata.managebac.courseSourcedIds
Applicable to PYP classes only: List of subject groups
Can this be modified?
Cannot be modified
subjects
The Subject associated to the Class, only one
Cannot be modified
30ff...3bec
Business & Management
11
63f6...3098
BUS-2-2025
scheduled
6a9d...2d8f
3099...ff8c, 3142...4644
Business & Management
c4bb...bfd0
Test
09
b65f...9e9f
scheduled
6a9d...2d8f
3099...ff8c, 3142...4644
English
6940...0a05
Ex Math
06
624d...941d
homeroom
3302...2a4e
b083...9ad7, ad73...0f0b
Homeroom, Mathematics, Personal social and physical education 1, Physical education 3, English, Science
dfe3...77e4
Math PYP 6
06
624d...941d
homeroom
3302...2a4e
a823...efdb
Homeroom, English, Music, Personal social and physical education 1, Physical education 3
, ks check, , ,
624d...941d, 3a46...842d, 9b12...fccc, 73a8...c76e,73a8...c76e
1
sourcedId
yes
no
Required by OneRoster
2
status
yes
must be blank for bulk, must be populated for delta
Follows OneRoster convention
3
dateModified
yes
must be blank for bulk, must be populated for delta
Follows OneRoster convention
4
enabledUser
sourcedId
Uniquely identifies the record
Used referentially
agentSourcedIds
Identifies parent / child relationship
Replaces all
Adds but does not remove
Each record must include a unique value for sourcedId
agentSourcedIds for student records can only point to parent records
agentSourcedIds for parent records can only point to Student records
When a new association between a student and parent is made on import, the default "Other Guardian" relationship is used by default. The relationship can be changed to "Mother", "Father", etc. after imoprt without being overwritten
Student user records contain all associated parents
Parent user records contain all associated children
identifier
Uniquely represents the user
Matches to Student ID, Parent ID, or Teacher ID
userMasterIdentifier
Same as identifier
Matches to Student ID, Parent ID or Teacher ID, if present
enabledUser
Archived users are FALSE, active users are TRUE
Sets archived status accordingly
username
Same as username
Users are matched in the following order: sourcedId, username, identifier
After the first import and sourcedId is known by MB, the user's MB email address can be changed by populating the new value in both username and email.
The grades column cannot be edited on import.
All users, even archived users, are always exported for both bulk and delta
userIds
Not used
Ignored
password
Not used
Ignored
preferredGivenName
Not used
Ignored
preferredMiddleName
Not used
The following columns values depend on the import or export mode:
status
Must be present but emtpy
Must be present and either "active" or "tobedeleted"
dateLastModified
Must be present but empty
Must be present and a date
yes
no
5
username
yes
no
Required in OR as a credential. In MB is used as the email
6
userIds
yes
yes
Optional in both OneRoster and MB
7
givenName
yes
no
Required by OneRoster
8
familyName
yes
no
Required by OneRoster
9
middleName
yes
yes
Optional in both OneRoster and MB
10
identifier
yes
yes
Optional in both OneRoster and MB
11
yes
yes
MB uses username instead
12
sms
yes
yes
Optional as MB does not use this field
13
phone
yes
yes
Optional as MB does not use this field
14
agentSourceIds
yes
yes
Optional in both OneRoster and MB
15
grades
yes
yes
Optional in both OneRoster and MB
16
password
yes
yes
Optional as MB does not use this field
17
userMasterIdentifier
yes
yes
Optional as MB does not use this field
18
preferredGivenName
yes
yes
Optional as MB does not use this field
19
preferredMiddleName
yes
yes
Optional as MB does not use this field
20
preferredFamilyName
yes
yes
Optional as MB does not use this field
21
primaryOrgSourcedId
yes
yes
Optional as MB does not use this field
22
pronouns
yes
yes
Optional as MB does not use this field
Used to match to user ManageBac's email.
email
Same as email
Ignored
givenName
First Name
Updates first_name
familyName
Last Name
Updates last_name
middleName
Middle Name
Updates middle_name
sms
Mobile phone number
Updates mobile_phone_number
phone
Home phone number
Updates home_phone_number
grades
Only for students, the grade the student is in
Cannot be updated via import
Ignored
preferredFamilyName
Not used
Ignored
primaryOrgSourcedId
Not used
Ignored
pronouns
Not used
Ignored
4d74...ed70
true
Happy
Student
ABC
ManageBac Subject Groups and Subjects are represented in courses.csv.
The columns of the classes.csv file must be in the following order:
ManageBac Subject Groups are associated to a Program, and the following describes the relationship:
orgSourcedId resolves to a type -> ext:program row in orgs.csv
All rows will include orgSourcedId value
Each row in courses.csv represents an individual Subject Group, and child Subjects are represented through lists across multiple columns. Details about Subjects are given listed via the subjects and subjectCodes, and applicable metadata.managebac.* columns.
The subjects column has different validations for Programs, since some programs allow for the creation of custom subjects (such as Middle School) and others do not (such as IB Diploma):
If subjectCodes is not blank, its contents must match subjects as a parallel array; the order and length are signficant.
The core metadata.* columns, if present, must also be a parallel array that matches subjects, where the order and length are signficant
The core metadata.*
Column and Program combinations not delineated above are not required and can be left blank.
In Bulk Import mode, all enabled subjects not listed in subjects for the associated Program, will be disabled
All enabled Subject Groups are exported
The following columns values depend on the import or export mode:
yes
MB does not use this field
4
title
yes
no
Required by OneRoster
5
courseCode
yes
yes
MB does not use this field
6
grades
yes
yes
MB does not use this field
7
orgSourcedId
yes
no
Required by OneRoster
8
subjects
yes
yes
Optional
9
subjectCodes
yes
yes
Optional
10
metadata.managebac.levels
yes
yes
Optional
11
metadata.managebac.selfTaught
yes
yes
Optional
12
matadata.managebac.languageLevels
yes
yes
Optional
13
matadata.managebac.phases
yes
yes
Optional
14
matadata.managebac.snsBasedOn
yes
yes
Only required by MB for IB PYP Subjects
metadata.managebac.selfTaught
Some subject groups have a self-taught option
metadata.managebac.snsBasedOn
Some subjects require Scope & Seq per subject
orgSourcedIdmetadata.managebac.levels
High School
Yes
"HL" | "SL"
metadata.managebac.levels
Middle School
Yes
"HL" | "SL"
metadata.managebac.levels
Primary School
Yes
"HL" | "SL"
metadata.managebac.levels
Pearson EdExcel Int'l GCSE
Yes
"Higher" | "Foundation"
metadata.managebac.levels
Pearson Edexcel Advanced
Yes
"A" | "AS"
metadata.managebac.levels
Cambridge IGCSE
Yes
"Extended" | "Core"
Language Levels
metadata.managebac.languageLevels
IB DP
Yes
"Literature" | "Language and literature" | "ab initio" | "B"
Phases
metadata.managebac.phases
IB MYP
Yes
"1" | "2" | "3" | "4" | "5" | "6"
Scope & Sequence
metadata.managebac.snsBasedOn
IB PYP
Yes
"phases" | "years"
Self-Taught
metadata.managebac.selfTaught
IB DP
Yes
"self-taught"
e1cb...18e5
Language and literature
6a9d...2d8f_myp
English
b65f...9e9f
1
sourcedId
yes
no
Required by OneRoster
2
status
yes
must be blank for bulk, must be populated for delta
Follows OneRoster convention
3
dateModified
yes
must be blank for bulk, must be populated for delta
Follows OneRoster convention
4
schoolyearSourcedId
sourcedId
Uniquely identifies the record
Used referentially
orgSourcedId
The associated Program or curriculum
Cannot be created or changed
title
The name of the Subject Group represented in this row
subjects
List of subjects names that are grouped under this Subject Group
subjectCodes
Optional list of subject codes, grouped under this Subject Group. May be empty.
metadata.managebac.levels
Some subject groups require a level value per subject
metadata.managebac.languageLevels
Some subject groups require a language level per subject
metadata.managebac.phases
Some subject groups require a phase per subject
IB DP
no
Each listed subject must match IB DP Subject title
Primary School
yes
Listed subjects that do not match are created
Middle School
yes
Listed subjects that do not match are created
High School
yes
Levels
metadata.managebac.levels
IB DP
Yes
"HL" | "SL"
metadata.managebac.levels
IB CP
Yes
schoolYearSourcedId
Subject Groups are not linked to Academic Years
Ignored
courseCode
Subject Groups do not have human-readable code
Ignored
grades
Grade is specified in classes.csv
Ignored
status
Must be present but emtpy
Must be present and either "active" or "tobedleted"
dateLastModified
Must be present but empty
Must be present and a date
yes
Listed subjects that do not match are created
"HL" | "SL"
Studies in language and literature
6a9d...2d8f_diploma
English
"HL,SL"
self_taught
"Literature,Language and literature"
9804...166b
Language acquisition
6a9d...2d8f_diploma
English
"HL,SL"
"ab initio,B"
7825...74c3
Language acquisition
6a9d...2d8f_myp
English
"1,2,3,4,5,6"
63f6...3098
Individuals and societies
6a9d...2d8f_diploma
Business & Management,Economics,Environmental Systems & Societies,Geography,History,Philosophy,Psychology,Social and Cultural Anthropology,World Studies
"HL,SL","HL,SL","HL,SL","HL,SL","HL,SL","HL,SL","HL,SL","HL,SL","HL,SL"
af0a...bb9e
Individuals and societies
6a9d...2d8f_myp
Business Management,Civics,Economics,Geography,Government,History,Individuals and Societies,Integrated Humanities,Philosophy,Political Science,Psychology,Sociology/Anthropology,World Religions
06aa...88f7
Sciences
6a9d...2d8f_myp
Biology,Chemistry,Earth Science,Environmental Science,Health Science,Life Science,Physical Science,Physics,Sciences,Sport Science
9afd...981e
Sciences
6a9d...2d8f_diploma
Biology,Chemistry,Computer Science,Design Technology,Environmental Systems & Societies,Food Science and Technology,Physics
"HL,SL","HL,SL","HL,SL","HL,SL","HL,SL","HL,SL","HL,SL"
0a0a...6197
Mathematics
6a9d...2d8f_myp
Extended Mathematics,Mathematics,Standard Mathematics
e1cf...aaf4
Arts
6a9d...2d8f_myp
Arts,Dance,Expressive Arts,Film,Media Arts,Music,Performing Arts,Theatre,Visual Arts
6311...3507
Arts
6a9d...2d8f_diploma
Dance,Film,Music,Other Elective,Theatre,Visual Arts
"HL,SL","HL,SL","HL,SL","HL,SL","HL,SL","HL,SL"
ab87...9eed
Physical and Health Education
6a9d...2d8f_myp
Physical and Health Education
73ca...301c
Core
6a9d...2d8f_diploma
Theory of Knowledge
7525...1d5b
Design
6a9d...2d8f_myp
Design,Digital Design,Product Design
The manifest file provides meta information about the contents of the source data, which is given in subsequent csv files. The properties describe versioning information and also describe files stored interally on the archive. This file is read and parsed prior to all other files.
There are only two columns in a manifest.csv file, and they must be in the following order:
Property Names and description are given below:
The following properties names need to be included in a unique row in the manifest file and represent metadata about the contents:
The special source.systemName and source.systemCode are required and must be populated for successful import. These values must remain consistent across imports. On export, ManageBac itself uses "ManageBac" and "MB" for those properties, respectively.
The Rostering Manager will prompt the user to enter the values for these properties manually if not provided in the manifest.csv file.
The following properties in the manifest specify how to resolve files other than the manifest, as well as specify the methodology used to select records when extracted:
The above properties must all be present. However, note that a value of "absent" indicates the respective file is not present in the archive. For example, it is possible to only include users in the users.csv and exclude any changes to Academic Terms by specifying "absent" for file.academicSessions and excluding academicSessions.csv file from the archive.
On import, the behavioral differences between "bulk" and "delta" will be respected for each specified entity. For example, if "bulk" is specified for file.users.csv but as "delta" for file.classes, then the users will be imported in bulk mode and classes imported in delta mode.
The "bulk" and "delta" values change requirements that occur for each file. When a value of "bulk" is provided, ManageBac will validate that status and dateLastModified are not present in the respective file. When a value of "delta" is provided, ManageBac will validate that status and dateLastModified are present and non-blank.
The formal OneRoster specification for manifest.csv includes additional properties not listed above, such as file.userProfiles, but are not supported by ManageBac. The manifest.csv file may optionally contain such properties with a value of "absent."
file.classes
yes
Must be one of "absent" | "bulk" | "delta"
file.courses
yes
Must be one of "absent" | "bulk" | "delta"
file.demographics
yes
Must be one of "absent" | "bulk" | "delta"
file.enrollments
yes
Must be one of "absent" | "bulk" | "delta"
file.orgs
yes
Must be one of "absent" | "bulk" | "delta"
file.roles
yes
Must be one of "absent" | "bulk" | "delta"
file.users
yes
Must be one of "absent" | "bulk" | "delta"
source.systemName
yes
Optional. If this field is blank, the user will be prompted to input in the UI
source.systemCode
yes
Optional. If this field is blank, the user will be prompted to input in the UI
file.demographics
"bulk" | "delta" | "absent"
file.enrollments
"bulk" | "delta" | "absent"
file.courses
bulk
file.courseResources
absent
file.demographics
bulk
file.enrollments
bulk
file.lineItemLearningObjectiveIds
absent
file.lineItems
absent
file.lineItemScoreScales
absent
file.orgs
bulk
file.resources
absent
file.resultLearningObjectiveIds
absent
file.results
absent
file.resultScoreScales
absent
file.roles
bulk
file.scoreScales
absent
file.userProfiles
absent
file.userResources
absent
file.users
bulk
source.systemName
ManageBac
source.systemCode
MB
propertyName
yes
no
Name of a property
value
yes
no
The value of the named property
manifest.version
yes
Must be "1.0"
oneroster.version
yes
Must be "1.2"
file.academicSessions
yes
Must be one of "absent" | "bulk" | "delta"
file.categories
yes
manifest.version
"1.0"
oneroster.version
"1.2"
source.systemName
<string>
source.systemCode
<string>
file.academicSessions
"bulk" | "delta" | "absent"
file.orgs
"bulk" | "delta" | "absent"
file.users
"bulk" | "delta" | "absent"
file.roles
"bulk" | "delta" | "absent"
file.classes
"bulk" | "delta" | "absent"
file.courses
"bulk" | "delta" | "absent"
manifest.version
1.0
oneroster.version
1.2
file.academicSessions
bulk
file.categories
absent
file.classes
bulk
file.classResources
absent
Must be one of "absent" | "bulk" | "delta"
base: file_mode_mismatch
%s file's mode is %s but the file is %<file_status>s
activerecord
manifest: blank
file is missing
activerecord
headers: missing
are missing '%s' header
activerecord
properties: duplicated
%s are duplicated
activerecord
properties: missing
%s are missing
activerecord
value: inclusion
'%s' must be one of 'absent', 'bulk', or 'delta'
activerecord
value: not_supported_yet
'delta' is not supported yet
activerecord
property_name: unknown_property
'%s' is unknown
activerecord
value: invalid_manifest_version
'%s' is not a valid manifest version. The manifest version must be '%<expected_version>s'
activerecord
value: invalid_oneroster_version
'%s' is not a valid OneRoster version. The OneRoster version must be '%<expected_version>s'
activerecord
invalid_oneroster_version
%{file_name}.csv file missing required headers. Missing headers list: %{missing_headers}
processors/file_processor
invalid_oneroster_version
%{file_name}.csv file features headers in an incorrect order
processors/file_processor
invalid_oneroster_version
%{file_name}.csv cannot be parsed: %{error_message}
processors/import_processor
invalid_oneroster_version
%{file_name}.csv records were not imported
processors/import_processor
invalid_oneroster_version
%{file_name}.csv contains invalid records
processors/validation_processor
invalid_oneroster_version
%{file_name}.csv records were not saved to ManageBac
processors/record_processor
duplicated_one_roster_record
%{file_name}.csv records were not saved to ManageBac
activerecord
file: incorrect_exchange_format
A zip file in the OneRoster data exchange format is required: %{messages}
model/import
file: content_type_invalid
a zip file is required
model/import
role: cannot_be_changed
cannot be changed for an existing record
model/role
role_type: only_primary_role
user must have one primary role
model/role
base: role_not_found
role cannot be found for this user
model/user
grades: cannot_be_matched
do not match the vocabulary. Conflict grades: %{items}
model/user
base: terms_blank
at least one term for each academic year is required
model/academic_session
base: not_all_term_align
not all terms align with existing Academic Year
model/academic_session
sourced_id: cannot_be_restored
the record has been deleted and cannot be restored
model/academic_session
status: cannot_be_deleted_with_active_terms
cannot be deleted with active terms
model/academic_session
start_date: not_match_term_date
does not match first term startDate
model/academic_session
end_date: not_match_term_date
does not match last term endDate
model/academic_session
title: cant_be_changed
can't be changed
model/course
base: uncommon_subject_group
adding new subject group to programme %{program_name} is restricted
model/course
base: uncommon_subjects
adding new subjects to programme %{program_name} is restricted. Conflict subjects: %{subject_names}
model/course
base: multiple_subjects_match
multiple subjects found with the same identifier, please ensure the subject is unique. Conflict subjects: %{subject_names}
model/course
base: invalid_subject
invalid subject %{name}. Reasons: %{messages}
model/course
subjects_length_mismatch
length must be the same as subjects list length
model/course
invalid_record
sourced record is invalid
model/enrollment
date_doesnt_match
doesn't match with class term
model/enrollment
cannot_be_changed
cannot be changed for an existing record
model/enrollment
mb_user_role_mismatch
doesn't match ManageBac's user role
model/enrollment
base: course_terms_org_sourced_id_mismatch
course and terms must belongs to the same orgSourcedId
model/school_class
base: course_meta_courses_org_sourced_id_mismatch
course and metadata.managebac.courseSourcedIds must belongs to the same orgSourcedId
model/school_class
term_sourced_ids: must_have_same_org_sourced_id
must belongs to the same orgSourcedId
model/school_class
term_sourced_ids: must_be_same_or_following_academic_year
must be in the same or following academic year
model/school_class
term_sourced_ids: must_be_same_academic_year
must be in the same academic year
model/school_class
term_sourced_ids: invalid_record
sourced record is invalid. Conflict terms: %{items}
model/school_class
term_sourced_ids: missing_covered_terms
list is incomplete. Some terms are missing
model/school_class
grades: not_included_in_the_program
cannot be matched with the %{program_code} program grades. Conflict grades: %{unmatched_grades}
model/school_class
grades: cannot_be_matched
do not match the vocabulary. Conflict grades: %{items}
model/school_class
subjects: cannot_be_matched
cannot be matched with the course subjects. Conflict subjects: %{unmatched_subjects}
model/school_class
subject_codes: cannot_be_matched
cannot be matched with the course subjectCodes. Conflict subjectCodes: %{unmatched_codes}
model/school_class
meta_course_sourced_ids: must_have_same_org_sourced_id
all values must be referenced to the courses with the same orgSourcedId as in courseSourcedId
model/school_class
meta_course_sourced_ids: invalid_record
sourced record is invalid. Conflict courses: %{items}
model/school_class
subjects_length_mismatch
length must be the same as subjects list length
model/school_class
invalid_record
sourced record is invalid
model/school_class
sourced_id: invalid
program code '%{program_code}' is unknown
model/org
sourced_id: mismatched
doesn't match school's Sourced ID '%{sourced_id}'
model/org
sourced_id: program_disabled
%{program_name} is not enabled, and so import cannot proceed. Please contact support to enable it
model/org
sourced_id: program_cannot_be_disabled
%{program_name} is enabled, and so import cannot proceed. Please contact support to disable it
model/org
parent_sourced_id: invalid
of the program must belong to a school
model/org
parent_sourced_id: not_found
doesn't match any sourcedId
model/org
type: taken
'school' is allowed only once
model/org