Exporting your CSV files
-
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
- orgs.csv (defines district and school entities)
- users.csv (defines family/staff/student entities)
- academicSessions.csv (defines the time periods of the academic cycle: school years, quarters, semesters, trimesters, etc)
- courses.csv (defines the basic class definitions of courses given at schools)
- classes.csv (defines specific instances of a course given at a school during a certain academic session)
- enrollments.csv (defines associations between student/staff users and which classes they attend/teach)
Optional files
- additional_staff.csv
- attendance.csv (if doing Attendance notifications)
-
transportation.csv
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:
|
| 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:
|
| 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. |
| 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. |
| 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:
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. |
| 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. |
| 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:
|
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. |