Click on a topic for more information.
Before You Import & Troubleshooting Tips
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.
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.
Note: There is no upload path required to import into ClassLink via FTP/SFTP.
ClassLink Frequently asked Questions and Answers:
What will happen to our existing accounts? Will existing data merge to new accounts?
If the IDs do not match what is currently in FitnessGram, accounts will be duplicated, which will separate past data from the users. To avoid this, before sending any files, you should check the school and student IDs in the FitnessGram software. To avoid duplication, the IDs in the ClassLink files will need to match the local user IDs in FitnessGram. If you need to overhaul the IDs in FitnessGram to match the ClassLink IDs, email support@fitnessgram.net.
How long will it take for accounts to be created?
As soon as data is sent to FitnessGram it usually takes between 5-60 minutes to appear in FitnessGram. View the import history tab to monitor progress.
How do Admin accounts get created and how will admins login?
Admins are managed within the FitnessGram software by a current administrator.
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:
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:
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, schoolYear, Semester. 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:
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:
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:
users.csv
The users.csv file will import students, teachers, and administrators into FitnessGram®. Before importing, please verify:
- 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.
- If you do not wish usernames/passwords to be updated for existing users, make sure to check “No” for the Update Username and Password setting on the Import Settings tab within FitnessGram®.
| 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.
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. |
| 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. However, if a value is present it must have references in the users.csv file. We recommend leaving this field empty. |
| grades | Yes | Grade(s) for which a user with role ‘student’ is enrolled. FitnessGram® imports any grade other than KG-13 as “unknown”. |
| 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:
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 active, inactive, 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:
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 active, inactive, 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:
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 Update Usernames and Passwords setting is set to “No” 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.
FitnessGram Software Help 