Freckle_logo

Preparing Files for Data Import with Freckle

Who can do this with default capabilities?

School Network Administrators

Getting Started

  1. Log into your Home Page.
  2. Select Import Class List at the top of your Home:

  3. Download the Freckle Class List Template files. This zip file contains templates for:

    • classes.csv
    • enrollments.csv
    • pupils.csv
    • teachers.csv

Preparing Your Class List Files

  • All four .csvs are required, every time you upload data.
  • All fields within each .csv are required.
  • For every school you wish to update, the data set must be complete and include all pupils, teachers and classes that should have access to Freckle.
  • You can create your own .csv files by exporting from your Student Information System or you can update our template files.

Step 1—Prepare the classes.csv file

This file contains a single row for each class that will use Freckle.

  • Teachers can own more than one class.
  • If a class has a co-teacher, duplicate columns A and B (class_sis_id and name) in a new row and input the co-teacher's email in Column C (teacher_email).
Header Required Description
class_sis_id YES Unique identifier for this class. If your SIS uses the same Class ID for multiple classes, add a tag to distinguish each class from the rest.
name YES Name for the class that will appear on the teacher's class list
teacher_email YES Email address of one of the teachers associated with this class.

Example:

Step 2—Prepare the enrollments.csv file

This file ties pupils to the classes in which they are enrolled.

  • Pupils can belong to multiple classes.
  • Pupils who belong to a class will be shared across ALL teachers who have access to that class.
  • All pupils in students.csv must be assigned to at least one class in enrollments.csv.
Header Required Description
pupil_sis_id YES Must match a pupil SIS ID that appears in the students.csv file.
class_sis_id YES Must match a class SIS ID that appears in the classes.csv file.

Example:

Step 3—Prepare the pupils.csv file

This file contains exactly one row for each pupil who needs access to Freckle.

Header Required Description
pupil_sis_id YES Unique identifier assigned by the school network to each pupil.
first_name YES First name of the pupil associated with this SIS ID.
last_name YES Surname of the pupil associated with this SIS ID.
year YES Year of the pupil associated with this SIS ID. Use the following format: [R, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13]
or [R, Y1, Y2, Y3, Y4, Y5, Y6, Y7, Y8, Y9, Y10, Y11, Y12, Y13].
language NO Language set for the pupil: en-GB (British English), en (American English) or es (Spanish). Note: If you are using an older template without a language column, or if you do not want to change the language of any of your pupils, you can remove this column. If language data is not included for a pupil, the pupil's language will be set to the same language as their teacher.

Example:

Step 4—Prepare the teachers.csv file

This file contains exactly one row for each teacher who needs access to Freckle.

Header Required Description
school_sis_id YES Unique identifier for the primary school this teacher belongs to. If the teacher belongs to multiple schools, pick just one for this file.
first_name YES First name of the teacher associated with this email address.
last_name YES Surname of the teacher associated with this email address.
teacher_email YES Email address this teacher will use to log into Freckle.

Example:

Uploading Your Class List Files

Make sure your files are saved as .csvs and formatted as UTF-8. If you are using Excel with Windows, follow these instructions to export your files in the correct format: https://www.webtoffee.com/how-to-save-csv-excel-file-as-utf-8-encoded/#save-csv-microsoft-excel

Review your class list. To avoid common errors, check that:

  • You have created all four .csvs.
  • For every school you wish to update, the data set is complete and includes all pupils, teachers and classes that should have access to Freckle.
  • First names and surnames are listed in the correct columns.
  • The year field in the Pupils tab follows this format: R, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13
    or R, Y1, Y2, Y3, Y4, Y5, Y6, Y7, Y8, Y9, Y10, Y11, Y12, Y13.
  • Every pupil is enrolled in at least one class.
  • In the Pupils tab, you have exactly one row for each pupil.
  • In the Teachers tab, you have exactly one row for each teacher.
  • The Courses tab excludes classes that will not use Freckle (e.g. PE).
  • The School SIS IDs in the teachers.csv file refer to schools that you have permission to update.

Upload all four .csvs into Freckle.

Merging Duplicates (recommended)

Your teachers may have already created Freckle accounts for some of your pupils. To maintain pupil data while removing duplicates from your class list, we recommend that you tick the Merge Duplicates option in Class List Sync:

Two pupil records will be merged into one record if ALL of the following are true:

  • They both have the same first and surnames.
  • They both belong to the same school.
  • They are within one year of each other.
  • One of the records is "trusted". In other words, one of the pupils must have been created during an admin-led class list sync in Freckle.

After the merge:

  • Course memberships are retained.
  • Practice data is retained.
  • In cases where information conflicts between the two records (i.e. name or year), we trust the admin-created record.

Resolving Errors

To import your class list files, select Start Import. First, the system will merge duplicate pupil records in your schools (if selected). Then, the system will perform a dry run of the class list sync so you can review your updated class list before confirming the changes.

You may have errors in your .csv files that prevent you from reaching the Summary screen. For example:

  • The system might not have School SIS IDs for all of your schools. If this is the case, you will have the opportunity to match your schools to the SIS IDs in your .csv.
  • Your .csvs may have formatting issues. If this is the case, Freckle will identify the changes you need to make before you can proceed.
Error Message/Type Action Step
Pupil not enrolled All pupils must belong to at least one class. Add the pupil ID in question to enrollments.csv or remove the pupil ID from pupils.csv.
Duplicate email A teacher appears multiple times in teachers.csv. Teacher emails can only appear once. If the teacher appears twice because they belong to multiple schools, pick one and remove the other entry.
Enrolment Pupil Not Found Add the pupil ID to pupils.csv or remove the pupil ID from enrollments.csv, because they are out of sync.
Enrolment Class Not Found Add an entry for this class ID to classes.csv or remove the entry for this class ID from enrollments.csv.
Class Teacher Not Found Add an entry for this teacher email to teachers.csv or remove the entry for this teacher email from classes.csv.
ID Duplicated in Row This unique identifier for pupils appears twice in the pupils.csv file. Remove one entry.
Email Duplicated in Row This unique identifier for teachers appears twice in the teachers.csv file. Remove one entry.
School Not Found Remove this School ID from teachers.csv.
Missing School Network Contact your Account Manager so that your school can be affiliated with a School Network ID.
Missing Header Check to make sure all headers are present in your .csvs and they match the template headers (the system is case-sensitive!) If this does not work, make sure you have saved your files in UTF-8 format.

Once you have fixed all .csv errors, you will reach the Class List Sync summary. If applicable, you can see how many duplicate pupils were found and merged and confirm that the Class List Sync summary is updating the number of records you expect.

Confirming your Class List

  1. Use the drop-down list to confirm that the schools you are about to update are the correct ones.
  2. Confirm that the Class List Sync is updating, adding and archiving the right number of pupil, teacher and class records.
  3. Select Sync Class List and Finish to finalise the sync. You must select this button to finish loading your data.

After the Sync

  • New teachers (teachers who appeared in your .csv files but did not already have a Freckle account) will receive an email prompting them to log-in and choose a password.
  • Teachers can continue to edit their class lists and add new pupils manually after you have synced class lists with Freckle.
  • Teacher class lists may have a combination of pupils that came from an admin sync and old pupils that were teacher-created. If you want to get rid of outdated records in bulk, visit this support link.
  • Otherwise, teachers will be able to merge admin and non-admin pupil records when they log in for the first time.