Skip to main content

Data export instructions

Updated
These instructions are specifically for your SIS/data admin to use in the preparation and export of the needed data. Once done, any changes made in the school's SIS will be reflected in SchoolNow after the daily sync.

Exporting your CSV files

It’s important that each file have a header row that matches each schema exactly. Please note that spaces and hyphens are not valid for the naming of column headers.
 
  • Note on column headers
    The column headers defined in this file are suggested headers that will speed up the analysis and initial setup of your data. However, depending on the tools available to you, it may be difficult to have the exported files use the exact headers that we have outlined.

    Our data processing engine can be configured to map headers in your files to our “expected” headers. So if it is not possible to export files using the headers defined in this doc, that does not create a problem. Just note that the initial review and processing of your data set may take slightly longer for us to accommodate.
     
  • Note on file names
    Similar to column headers, file names also do not need to match exactly what is defined here. Our system can be configured to use any filenames that come into the SFTP drop.  However, as with column headers, the closer the filenames match what is defined in this document, the faster the initial setup of your data will be.
 

Summary of data collected

  • PII Data: First name, last name, email address, phone number
  • Other recommended data: grades, course data, class data, enrollment
  • Other optional data: gender, language, attendance
 

Required files

  1. orgs.csv (defines district and school entities)
  2. users.csv (defines family/staff/student entities)
  3. academicSessions.csv (defines the time periods of the academic cycle: school years, quarters, semesters, trimesters, etc)
  4. courses.csv (defines the basic class definitions of courses given at schools)
  5. classes.csv (defines specific instances of a course given at a school during a certain academic session)
  6. enrollments.csv (defines associations between student/staff users and which classes they attend/teach)

Optional files

 

orgs.csv

Column Header Field Required Unique Value Notes
sourcedId Yes Yes A unique identifier for the org.
name Yes Yes Name/title of the org.
type Yes No

Denotes which kind of org the record is. Allowed types:

  • district (only on one record per data set)
  • school
parentSourcedId Yes* No The unique identifier for the org that this org belongs to. An org of type “district” should have a blank parentSourceId. Any org of a “school” type should always have a parent.

 


users.csv (all users in one file)

Column Header Field Required Unique Value Notes
sourcedId Yes Yes Unique identifier of the user in relation to all other users (of any type) in the system.
orgSourcedIds Yes No

The IDs of any orgs this user belongs to. Each record usually has at least one org. Blank values will be assumed to be tied to the “district” org in the data set.

Multiple values can be provided as a comma-separated list.
role Yes No

Denotes the kind of user the record is. Allowed values:

  • student
  • administrator
  • aide
  • proctor
  • teacher
  • staff
  • guardian
  • parent
  • relative
  • community
givenName Yes No First name of the user.
familyName Yes No Last name of the user.
middleName No No Middle name of the user.
identifier No* Yes

Alternate identifier for a user record. This usually only affects “student” type records, as systems have both a “database ID” in the SIS and then a “student ID” that is used throughout the school to reference students in day-to-day communications. If exporting additional data files from disparate systems (such as a lunch system), it is likely that data can only be exported using these “student IDs” as the other systems do not have any knowledge of the SIS “database IDs”.

In these cases, this data is needed so this disparate data can be linked together in the import.

When giving an identifier, the “sourcedId” field should still be given and the “sourcedId” should always reflect this “database ID” whenever possible.
email No No Primary email for the user.
phone No No Primary phone for the user.
sms No No Secondary phone for the user. While the field is marked as “sms”, the number doesn’t necessarily have to be a mobile number. Upon import, all numbers will be looked up in a database to determine their landline/mobile status and their carrier information.
agentSourcedIds Yes* No

Used to show parent/child relationships (so does not apply to any kind of staff or community role types and can be blank for those types of records). Multiple values can be provided as a comma-separated list.

Only one “direction” of the relationship is needed. Student records can have contact IDs in this field, or contact records can have student IDs in this field. Both do not need to be provided (as the opposite direction of the association can be assumed) but can be provided if the data comes that way.
grades Yes* No

Multiple values can be provided as a comma-separated list.

Any “student”-type record is required to have grade codes. For non-”student” records, these codes are not required but suggested when that data is available.

Values that align with the CEDS grade level codes is preferred, however, any grade codes can be used and a data specialist can map/convert the codes

as-needed.

https://ceds.ed.gov/CEDSElementDetails.aspx? TermId=7100
status No No

A truthy (1, true, t, yes, y) or falsey (0, false, f, no, n) value to express whether this record is currently active or inactive in the data set.

Ideally, if a record is inactive, it should be removed from the sheet, however, this field can be used to denote ignored/removed records if that is not possible.

If not given or blank, a record is assumed to be active.

 


academicSessions.csv (terms)

Column Header Field Required Unique Value Notes
sourcedId Yes Yes A unique identifier for the session.
title Yes No Descriptive name for the session.
type Yes* No

Allowed values:

  • gradingPeriod
  • schoolYear OR year
  • semester
  • term OR trimester
  • quarter

If no value can be given, the system will default to a “gradingPeriod” designation.
startDate Yes No Date stamp of the first day of the session (inclusive). Should match the format “month/day/year” or “year-month-day”. All values should be numbers (i.e. either “8” or “08” for the month of August).
endDate Yes No Date stamp of the last day of the session (inclusive). Should match the format “month/day/year” or “year-month-day”. All values should be numbers (i.e. either “8” or “08” for the month of August).
parentSourcedId Yes* No

The sourcedId of the session that this one belongs to. Usually sessions like semesters/trimesters/quarters belong to a school year.

Top-level sessions like school years don’t have a parent session.
schoolYear Yes No

School year to which the academic session contributes. This should be the last year the session is in effect, not the starting year (so a 2023-2024 school year would be 2024).

Value can be provided as a single year number (2024) or a school year range (i.e. 2023-2024).

 


courses.csv

Column Header Field Required Unique Value Notes
sourcedId Yes Yes A unique identifier for the course.
title Yes No

Descriptive name of the course.

Sometimes, if a more descriptive name cannot be given, then whatever value that could be used for the “courseCode” field can be used here instead.
courseCode No No Internal code/identifier used for this course (i.e. ENG-101).
grades No No

Multiple values can be provided as a comma-separated list.

Any “student”-type record is required to have grade codes. For non-”student” records, these codes are not required but suggested when that data is available.

Values that align with the CEDS grade level codes is preferred, however, any grade codes can be used and a data specialist can map/convert the codes as-needed.

https://ceds.ed.gov/CEDSElementDetails.aspx? TermId=7100
orgSourcedId Yes No The ID of an org (most likely of a “school” type) for which this course belongs.

 


classes.csv

Column Header Field Required Unique Value Notes
sourcedId Yes Yes A unique identifier for the class.
title Yes No

Descriptive name of the class.

Sometimes, if a more descriptive name cannot be given, then whatever value that could be used for the “classCode” field can be used here instead.
grades Yes No

Multiple values can be provided as a comma-separated list.

Any “student”-type record is required to have grade codes. For non-”student” records, these codes are not required but suggested when that data is available.

Values that align with the CEDS grade level codes is preferred, however, any grade codes can be used and a data specialist can map/convert the codes as-needed.

https://ceds.ed.gov/CEDSElementDetails.aspx? TermId=7100
courseSourcedId Yes No The ID of the course that this class is based on (classes are specific instances of courses).
classCode No No Internal code/identifier used for this class (i.e. ENG-101).
schoolSourcedId Yes No The ID of a “school” org for which this class belongs.
termSourcedIds Yes No

The IDs of any sessions this class belongs to. Each record has at least one session.

Multiple values can be provided as a comma-separated list.

 


enrollments.csv

Column Header Field Required Unique Value Notes
sourcedId Yes Yes A unique identifier for the enrollment.
schoolSourcedId Yes No The ID of a “school” org for which this enrollment belongs.
classSourcedId Yes No The ID of a class for which this enrollment is for.
userSourcedId Yes No The ID of a user for which this enrollment is for.
role No No

Specifies what kind of relationship this enrollment is for (whether it is a student attending the class or a teacher teaching the class).

Allowed values:

  • student
  • teacher

 


Optional Files 

additional_staff.csv

Your additional_staff.csv file should contain staff from an alternative source that exists outside your SIS.

For example, you might have staff that you want to import into SchoolNow that are not recorded in your SIS such as bus drivers, sports coaches, and cafeteria staff. While absent in your SIS, these staff members might be present in your HR or accounting software.

 

absences.csv (Attendance)

Attendance is supported by row, or by column. You may choose either version of the file and both support period attendance or daily attendance. The attendance.csv file may include attendance data for all schools in your district.

Check that the codes in the file match those listed in your settings; notification codes are case sensitive and must match exactly.

Attendance notifications will be sent at the time selected in SchoolNow and will use the most recent attendance.csv available. We recommend sending the file ~15 minutes before your notification time. If multiple attendance notices are scheduled throughout the day, multiple attendance.csv files must be sent.

Attendance by row (each student has as many rows as needed)

Column Header Field Required Unique Value Notes
studentSourcedId Yes No The ID of the student this attendance entry is associated with (ideally this will match the “sourcedId” of the “user” record for the student, however, the “identifier” can be used if necessary).
date Yes No Date stamp of the attendance entry. Should match the format “month/day/year” or “year-month-day”. All values should be numbers (i.e. either “8” or “08” for the month of August).
code Yes No

A “code” that designates the reason for the attendance entry (i.e. absent, tardy, etc).

These codes vary per customer and can be any values given in the sheet.
periods No No

The periods that this attendance entry covers. This is not needed if your school does not do period-based attendance notifications.

If a file has a mix of period-based and non-period-based attendance, this field can be left blank on the records that do not need it.

In this type of export, any periods here are assumed to use the same code. If needing to use different codes for each period, see the other file definition below.

Multiple values can be provided as a comma-separated list.
schoolSourcedId No No The ID of a “school” org for which this attendance entry belongs.



Attendance by column (each student has one row with codes in as many columns as needed)
 

Column Header Field Required Unique Value Notes
studentSourcedId Yes No The ID of the student this attendance entry is associated with (ideally this will match the “sourcedId” of the “user” record for the student, however, the “identifier” can be used if necessary).
date Yes No

Date stamp of the attendance entry.

Should match the format “month/day/year” or “year-month-day”. All values should be numbers (i.e. either “8” or “08” for the month of August).
code No No If the record is for an all day attendance entry, set the code for the day here.
period1 No No When breaking out specific codes for periods, use a column naming that attaches the period number/index to the base column name (i.e. “period1”, “period2”, etc).
... No No ...
periodN No No Use as many columns as necessary to match however many periods are in the school day. The system is not limited on how many periods can be used.
schoolSourcedId No No The ID of a “school” org for which this attendance entry belongs.

 


transportation.csv

Transportation data is set up to allow you to notify people of bus route delays, updates and information.

Column Header Field Required Unique Value Notes
studentSourcedId Yes Yes The ID of the student this transportation entry is associated with (ideally this will match the “sourcedId” of the “user” record for the student, however, the “identifier” can be used if necessary).
am Yes No The number/code of the bus the student rides in the morning (arrival).
pm Yes No The number/code of the bus the student rides in the afternoon (dismissal).
... No No If you have more transportation patterns other than morning/afternoon bussing, additional custom fields can be used as-needed.

Related articles

Powered by Zendesk