OneRoster™ Imports

Click on a topic for more information.

OneRoster™ Overview

Import with FTP

ClassLink Integration

Import with FitnessGram®

File Templates

Before You Import & Troubleshooting Tips

Additional Resources

OneRoster™ Overview

The OneRoster™ standard has been developed by IMS Global Learning Consortium® to facilitate the exchange of roster information and grades between an educational organization and a software vendor. OneRoster™ is a trademark of IMS Global Learning Consortium, Inc. (www.imsglobal.org). FitnessGram® supports importing roster data, including classes, users, and enrollments, using OneRoster™ v1.1 compliant CSV files transferred within a zip file. FitnessGram® does not currently support importing or reading rostering data via a OneRoster™-compliant REST API.

The OneRoster™ specification allows for two types of processing: bulk (full) and delta (incremental). Both of these are supported by FitnessGram®.

Bulk imports will essentially override the roster data for your entire district to match the file; i.e. adding new records, updating existing records, and inactivating missing records. FitnessGram® requires 7 OneRoster™ CSV files for bulk processing: manifest.csv, orgs.csv, users.csv, classes.csv, enrollments.csv, academicSessions.csv, and demographics.csv. FitnessGram® does not use and therefore does not require any additional CSV files to perform a bulk import. The OneRoster™ specification lists courses.csv as an additional requirement; however, since FitnessGram® does not use or store any course data, this file may be safely omitted.

Delta imports only specify records that should be updated. This functions much like the standard FitnessGram® import process, where records not included in the file are left alone. There are no required files other than manifest.csv, but the files that are included must meet all validation requirements (detailed under the File Templates section). If records are marked as “To Be Deleted”, then validation requirements are ignored, other than columns with the requirement indicated as Always or Only for Delta.

Bulk or delta processing for files is specified for each individual file in the manifest.csv.

Import with FTP

OneRoster™ zip files can be imported via the SFTP or FTPS protocols. Data is encrypted in transit and at rest throughout the import process.

This option is recommended for districts that will be doing frequent data imports or have a SIS vendor or other service (such as ClassLink) that enable automatic FTP transfers. This option allows you to schedule files for automatically processing (outside of the FitnessGram® system).

District-specific FTPS credentials are available by selecting the “View FTP credentials for automated imports” link on the Import page.

view ftp

In order to transfer files over SFTP instead, use the same credentials but change the port to 6389.

For FTP troubleshooting tips, please refer to the tips from the standard FitnessGram® import process.

ClassLink Integration

For districts leveraging ClassLink, FitnessGram® is now available in the OneRoster App Library. Follow the instructions in the previous section regarding SFTP imports and ClassLink’s instructions for exporting data to automate imports from ClassLink into FitnessGram®.

You must select OneRoster v1p1 as the Export Template; FitnessGram® does not support version 1.0 of the OneRoster™ specification.

Import with FitnessGram®

OneRoster™ zip files can also be uploaded through the import page FitnessGram® website. Please follow the “Import a File directly in FitnessGram®” instructions in Step 4: Import File for details on how to import files with FitnessGram®.

This option is good for districts that only do data imports occasionally or cannot install a File Transfer Protocol (FTP) client for security or protocol reasons.

Note that it may take a couple of minutes for the import preview screen to validate large files.

File Templates

Download OneRoster™ v1.1 Templates

The following tables detail the CSV file specifications for bulk and delta imports. As mentioned previously, fields listed with a requirement of “Yes” may be left blank ONLY for records marked to be deleted within a delta import. For all other cases, these values must be specified.

All fields are case-sensitive and order-specific in adherence with the OneRoster™ standard. In addition, all fields other than those prefixed with “metadata.” must be specified in the appropriate file, even if all the values will be blank or the description indicates the column is not used by FitnessGram®.

If your Student Information System (SIS) exports data according to the OneRoster™ 1.1 standard, you do not need to format these files yourself, and can skip to the Before You Import & Troubleshooting Tips section.

FitnessGram® requires additional data, not necessarily required in the OneRoster™ standard. Please review the CSV specifications and examples below and note additions. A summary of items you should check is listed under the Before You Import & Troubleshooting Tips section.

Jump to a specific table:

manifest.csv

The manifest.csv file will consist of two columns: propertyName and value. The table below shows the following properties required to be listed under the propertyName column in the file. The rest of the file templates will show Column Name instead of Property Name.

This file is required for every import.

Property Name (one per row) Required Description
manifest.version Always Version of the manifest. Fitnessgram® does not use this value.
oneroster.version Always Must be “1.1”; version 1.0 files are not supported.
file.academicsessions Always Value should be one of the following:

  • “bulk”: corresponding csv file contains data for
    bulk importing 
  • “delta”: corresponding csv file contains data for delta importing
  • “absent”: csv file is not supplied in the zip file
Note that nothing will be imported for categories, classresources, courses, courseresources, lineitems, resources, or results, even if “bulk” or “delta” is specified and the corresponding file is provided.
file.categories Always
file.classes Always
file.classresources Always
file.courses Always
file.courseresources Always
file.demographics Always
file.enrollments Always
file.lineitems Always
file.orgs Always
file.resources Always
file.results Always
file.users Always
source.systemname Always Name for the system producing the set of files. FitnessGram® does not use this value.
source.systemcode Aways Identification code for the system producing the set of files. Fitnessgram® does not use this
value.

Example:

manifest example

academicSessions.csv

The academicSessions.csv file lists various academic terms (such as school years, semesters, etc.). FitnessGram® requires that academic sessions connected to classes have a Start Date and End Date within the current school year, determined by the School Year specified on the Districts & Schools page.

Column Name Required Description
sourcedId Always Unique ID for the academic session.
status Only for Delta Bulk imports: must be blank.
Delta imports: enter active, inactive, or toBeDeleted. However, since academic sessions are not directly stored, no update will occur.
datelastModified Only for Delta Bulk imports: must be blank.
Delta imports: date record was last modified.
title Yes Name of the academic session. FitnessGram® does not use this value.
type Yes Enter term, gradingPeriod, schoolYearSemester. FitnessGram® does not use
this value.
startDate Yes Start Date for the academic session. Fitnessgram® requires that this date be within the current school year (inclusive) as defined by the School Year Start Date under Districts & Schools if it has any classes that reference it.
enddate Yes End Date for the academic session. FitnessGram® requires that this date be within the current school year (inclusive) as defined by the School Year Start Date under Districts & Schools if it has any classes that reference it.
parentSourcedId No SourcedId of the parent of this academic session.  FitnessGram® does not use this value, but it must be valid if specified.
schoolYear Yes The school year to which the academic session belongs. FitnessGram® does not use this value, but instead verifies that the Start and End Dates are within the current school year as defined by the School Year Start Date under Districts & Schools.

Example:

academicsession example

orgs.csv

The orgs.csv file contains different types of organizations (“orgs”) that are part of the district, such as departments, schools, districts, and states. FitnessGram® expects each school specified to have a SourcedId matching an existing School Local Identifier for your district that’s on an active license. All other types of orgs other than schools are ignored. The district is determined by either the logged-in user who uploads the zip file or the FTP credentials used to transfer the file, not by anything specified in orgs.csv.

FitnessGram® will not create or update schools using this mechanism, as schools must be licensed by U.S. Games; the schools are used only to determine appropriate relationships for classes, users, and enrollments.

Column Name Required Description
sourcedId Always Unique Id for the organization; for orgs specified as schools, this matches the School Local Identifier within FitnessGram®.
status Only for Delta Bulk imports: must be blank.
Delta imports: enter active, inactive, or toBeDeleted. However, no action will occur since school status is determined by the FitnessGram® license.
dateLastModified Only for Delta Bulk imports: must be blank.
Delta imports: date record was last modified.
name Yes Name of the organization. This value is not used by FitnessGram®.
type Yes Enter department, school, district, local, state, or national. Schools
should have a SourcedId that matches an active School Local Identifier.
identifier No NCES ID for the organization. This value is not used by FitnessGram®.
parentSourcedId No SourcedId of an org representing the parent organization. This value is not used by FitnessGram®.  but must be valid if present.

Example:

org example

classes.csv

The classes.csv file contains the full list of classes within the current school year that should exist within FitnessGram®.

Column Name Required Description
sourcedId Always Unique Id for the class; mapped to the Class Local Identifier within FitnessGram®.
status Only for Delta Bulk imports: must be blank.
Delta imports: enter active, inactive, or toBeDeleted.
Inactive/to be deleted classes will be flagged as “to be deleted”. Administrators can filter classes based on this status from the Manage Classes page.

dateLastModified Only for Delta Bulk imports: must be blank.
Delta imports: date record was last modified.
title Yes Class name which will be shown as the title of the class within FitnessGram®.
grades No Comma separated list of grades that apply to the class. FitnessGram® does not use this value.
courseSourcedId Yes SourcedId for the course of which this class is an instance. FitnessGram® does not use
this value, but it must not be blank.
classCode No Code used to help identify class. FitnessGram® does not use this value.
classType Yes Enter homeroom or scheduled. FitnessGram® does not use this value.
location No Description of where the class is physically located. FitnessGram® does not use this value.
schoolSourcedId Yes SourcedId of the Org that teaches this class of OrgType “school” (see
orgs.csv); interpreted as the School Local Identifier within FitnessGram®.
termSourcedIds Yes Comma separated list of the academic sessions in which the class is taught. FitnessGram®
will use the first listed TermsSourcedId to determine the class start and end dates, as such it is strongly recommended that only one TermSourcedId be specified.
subjects No Comma separated list of subject names for the class. FitnessGram® does not use this value.
subjectCodes No Comma separated list of subject codes for the class. FitnessGram® does not use this value.
Periods No Comma separated list of class periods. FitnessGram® does not use this value.

Example:

classes csv example

users.csv

The users.csv file will import students, teachers, and administrators into FitnessGram®. Before importing, please verify:

  1. All existing user Local Identifiers within FitnessGram® match the SourcedIds in the users.csv file; otherwise, duplicates will be created. If you have a large number of Local Identifiers that need to be updated within FitnessGram®, send an Excel file with the “Old IDs” specified in the first column and the “New IDs” specified in the second column (with column headers indicating which is which) to the FitnessGram® Help Desk.
  2. If you do not wish usernames/passwords to be updated for existing users, make sure to check the “Do Not Update Username and Password on Import” checkbox on the Districts & Schools page.
Column Name Required Description
sourcedId Always Unique ID for the user; mapped to the User Local Identifier within FitnessGram®.
status Only for Delta Bulk imports: must be blank.
Delta imports: enter active, inactive, or toBeDeleted. Inactive/To Be Deleted users will be deactivated from FitnessGram.
dateLastModified Only for Delta Bulk imports: must be blank.

Delta imports: date record was last modified.

enabledUser Yes Enter true if the user is active, otherwise enter false. FitnessGram® will activate/deactivate users based on this value.
orgSourcedIds Yes Comma separated list of Org Sourced IDs to which this user belongs. In most cases, this will be a single School ID. FitnessGram® uses this value to associate users with schools.
role Yes Enter student, teacher, administrator, aide, guardian, parent, proctor, or relative. Only users in the roles of student, teacher, and administrator will be imported into FitnessGram®; the others will be ignored.

If the specified role is administrator, the import process will import the user as a District Administrator if the orgSourcedIds value includes a district ID; otherwise they will be imported as a School Administrator.

username Yes Enter the desired username for the user. If you do not want the import to update usernames for existing users, make sure to check the “Do Not Update Username and Password on Import” checkbox on the Districts & Schools page.

It is strongly recommended that the user’s email address is specified as the username.

userIds No Comma separated list of machine-readable IDs (LDAP ID, LTI ID, etc.). FitnessGram® does not use this value.
givenName Yes User’s first name
familyName Yes User’s last name
middleName No User’s middle name
identifier No Human-readable identifier for the user. FitnessGram® does not use this value.
email No Email address for the user. It is strongly recommended that this value is specified for teachers and administrators.
sms No SMS address for the user. FitnessGram® does not use this value.
phone No User’s phone number
agentSourcedIds No Comma separated SourcedIds of the users to which this user has a relationship. FitnessGram® does not use this value.
grades No Comma separated SourcedIds of the users to which this user has a relationship. FitnessGram® does not use this value.
password No User’s password. FitnessGram® does not accept encrypted password values. If the password is not specified and the user does not already exist, a random password will be supplied.
metadata.fitnessgram.address1 No Optional “Address 1” value for the user. This column is not required to be present in the file.
metadata.fitnessgram.address2 No Optional “Address 2” value for the user. This column is not required to be present in the file.
metadata.fitnessgram.city No Optional “City” value for the user. This column is not required to be present in the file.
metadata.fitnessgram.stateAbbreviation No Optional “State Abbreviation” value for the user; if specified, this field expects the two-character state abbreviation, not the full name. This column is not required to be present in the file.
metadata.fitnessgram.postalCode No Optional zip/postal code for the user. This column is not required to be present in the file.
metadata.fitnessgram.parentEmail1 No Optional parent email for students. This column is not required to be present in the file.
metadata.fitnessgram.parentEmail2 No Optional secondary parent email for students. This column is not required to be present in the file.
metadata.fitnessgram.printBodyComposition No Optional field indicating whether body composition should be printed for students on reports. Enter Y (for yes) or N (for no). The default value for students is Y unless specified otherwise. This column is not required to be present in the file.
metadata.fitnessgram.printInSpanish No Optional field indicating whether students should show up on the Spanish Student Report. Enter whether students should show up on the Spanish Student Report. Enter Y (for yes) or N (for no). The default value for students is N unless specified otherwise. This column is not required to be present in the file.
metadata.fitnessgram.permanentExemptionCode No Optional exemption code if students should be permanently exempted from test events. This column is not required to be present in the file.

Example:

users csv example

demographics.csv

The demographics.csv file contains additional user information such as birthdate, sex, and ethnicity. FitnessGram® requires each student in the users.csv file has a corresponding record in demographics.csv specifying BirthDate and Sex.

Column Name Required Description
sourcedId Always SourcedId of the user to which the demographics refer. Only one demographics record should be specified per user.
status Only for Delta Bulk imports: must be blank.

Delta imports: enter activeinactive, or toBeDeleted.

dateLastModified Only for Delta Bulk imports: must be blank.

Delta imports: date record was last modified.

birthDate Yes (students) User’s birthdate; required for students.
sex Yes (students) Enter male or female; required for students.
americanIndianOrAlaskaNative No Enter true or false; indicates students who are American Indian or Alaska Native.
asian No Enter true or false; indicates students who are Asian.
blackOrAfricanAmerican No Enter true or false; indicates students who are Black or African American.
nativeHawaiianOrOtherPacificIslander No Enter true or false; indicates students who are Native Hawaiian or Other Pacific Islander.
white No Enter true or false; indicates students who are White.
demographicRaceTwoOrMoreRaces No Enter true or false; indicates students who are two or more races
hispanicOrLatinoEthnicity No Enter true or false; indicates students who are Hispanic or Latino Ethnicity.
countryOfBirthCode No Country where user was born. FitnessGram® does not use this value.
stateOfBirthAbbreviation No State where user was born. FitnessGram® does not use this value.
cityOfBirth No City where user was born. FitnessGram® does not use this value.
publicSchoolResidenceStatus No Indication of the location of the user’s legal residence relative to the boundaries of the public school attended and its administrative unit. FitnessGram® does not use this value.

Example:

demographics csv example

enrollments.csv

The enrollments.csv file contains the full set of student and teacher class enrollments for a school year that should exist within FitnessGram®.

 Column Name  Required Description 
sourcedId Always SourcedId of the user to which the demographics refer. Only one demographics record should be specified per user.
status Only for Delta Bulk imports: must be blank.

Delta imports: enter activeinactive, or toBeDeleted.

dateLastModified Only for Delta Bulk imports: must be blank.

Delta imports: date record was last modified.

classSourcedId Yes Class SourcedId
schoolSourcedId Yes School SourcedId
userSourcedId Yes User SourcedId
role Yes Enter student, teacher, administrator, aide, guardian, parent, proctor, or relative. Only enrollments with the roles of student, teacher, and administrator will be imported into FitnessGram®; the others will be ignored.
Primary No Enter true or false if the enrollment is for a teacher; indicates the teacher that should be considered the “primary” one for a class. FitnessGram® does not use this value.
beginDate No Start date for the enrollment; must be bounded by the Start/End dates from the corresponding Academic Session. If not specified, the enrollment will be imported with the Class Start date.
 endDate No End date for the enrollment; must be bounded by the Start/End dates from the corresponding Academic Session. If not specified, the enrollment will be imported with the Class End date.

Example:

enrollment csv example

Before You Import & Troubleshooting Tips

In order to avoid errors an unexpected results, please review the following before importing a OneRoster™ file.

  • Does my file meet all OneRoster™ v1.1 requirements? FitnessGram® does not support v1.0 of the OneRoster™ standard.
  • Are all the schools I’m importing actively licensed within FitnessGram®? Every school included in the import must already exist within FitnessGram®, have a Local Identifier that matches the school ID, and be assigned to an active license.
  • Do the user and class IDs match the existing user/class Local Identifiers within FitnessGram®? Any user or class IDs that are not found in FitnessGram® during the import will be created. In order to avoid creating duplicate records, it’s important to ensure that these identifiers are set correctly prior to the import. If your district requires a “mass update” of Local Identifiers (for instance, if you recently changed SIS vendors), please send an Excel file with the old (existing) and the new Local Identifiers to the FitnessGram® Help Desk, with both columns clearly labelled.
  • Do all students have demographics specified with Birth Date and Sex? FitnessGram® requires these values for all students since they are necessary to calculate scores based on their test event results.
  • Is my district’s School Year Start Date set correctly? The import validation will require every academic session with dependent classes to a Start Date no earlier than the School Year Start Date specified for your district, and an End Date no later than one year after the School Year Start Date.
  • Do I want to override existing users’ usernames and passwords? If no, then ensure that the “Do Not Update Username and Password on Import” setting is selected on the Import page under the Settings tab. If you do want to override these values, then check the box for the duration of that specific import.

Additional Resources

Back to Top