All Collections
ClassTag Connect API Integrations
ClassTag SFTP Connection for SIS
ClassTag SFTP Connection for SIS

Technical Support Documentation

Andrew M. avatar
Written by Andrew M.
Updated over a week ago

Schools often want to import their student information into ClassTag from their Student Information System (SIS). This allows schools to keep ClassTag synchronized with their student rosters, saving time and reducing the risk of errors.

ClassTag supports multiple connection methods for synchronizing with a school’s SIS data, including connecting to Clever and ClassLink. If the school does not use either of these methods, they can use the ClassTag SFTP connection. The SFTP connection can also sync Guardian data that cannot be easily synced through Clever or ClassLink.

ClassTag supports the OneRoster format for SFTP sync. OneRoster is the most widely supported format for all SIS systems, and can be easy to adopt even when it’s not explicitly supported.

OneRoster allows importing and updating:

  • Users (students, parents, teachers and administrators)

  • Classrooms

  • Enrollments

Import File Formats

The SFTP connection uses .csv files to import and update your data. These files should follow the OneRoster format. You can look at the OneRoster example to see how the files are ideally formatted. Also, please review Appendix B for more examples and requirements.

ClassTag offers a custom Guardians File for schools that have difficulty creating the OneRoster file format. Your Customer Success Manager may suggest using this file depending on your SIS configuration.

For manual uploads, ClassTag supports CSV files with ASCII and UTF-8 encodings. For automated sync, we can also support ISO-8859-1 encoding. But if you choose to use it, please notify your Implementation Engineer.

ZIP Files

OneRoster files can be placed inside a ZIP archive. ClassTag will open any ZIP archive it finds regardless of the name. If using a ZIP archive, please include the guardian file in the archive.

Letter Case in File Name

Files name should always be in lowercase, i.e.: users.csv, classes.csv, guardians.csv.

Treating Lists as Single Entities in CSVs

Comma-separated lists of items in a CSV file must be double-quoted to ensure that the item is read in its intended column. For example, in the Users file where a student may have multiple agentSourcedIds, any list of Ids ("agentSourcedId1,agentSourcedId2") must be set in double quotes in order for the list of Ids to be processed in its column. Double quotes are ASCII 0x22.

Please note that double quotes do not otherwise affect the value of any column, so can be included even around single entities.

Unescaped Commas

Commas in field data need to be enclosed in double quotes. For example, a person’s name with a suffix that uses a comma, like John Smith, Jr., will cause an error if the field with the comma is not enclosed in double quotes. In the file, the record should appear as

...,"Smith, Jr.",...

You may add double quotes to any or all fields, whether they have a comma or not. But please note that a user name with a comma is considered invalid.

Letter Case

While header formats are specified with camel-case capitalizations, ClassTag processes the headers case-insensitively (e.g., sourcedId and SourcedID are considered acceptable).

sourcedIds

One of the most important pieces of data in the SIS is the unique identification code (sourcedId) that allows the system to uniquely identify each User and each Classroom.

Every SIS provides a unique identification code for each User and each Classroom. This identification code is critical for maintaining data integrity. For example, if a student’s name changes, or they are moved to a different classroom, the system uses the sourcedIds to ensure that the right student is updated and put in the correct classroom.

Your Customer Success Manager will work with you to ensure that you are using the appropriate ID from your SIS as the sourcedId.

SFTP Shared File Location

Files need to be deposited somewhere safe and secure for ClassTag to read them.

You can choose to use ClassTag’s SFTP server or use an SFTP server provided by your SIS system. Your Customer Success Manager will help you choose and work with your data team to set up secure credentials.

Using ClassTag’s SFTP Server

ClassTag’s SFTP server host name is

static-sfs-us-east-1.docevent.io

Please specify port 22.

Your Customer Success Manager will provide you with credentials for the ClassTag SFTP service.

Using Your Own SFTP Server

If your SIS files are created on your own SFTP server, ClassTag can access that server on a regular basis to perform synchronization.

Please provide your Customer Success Manager with the location and credentials for your SFTP service.

Overwriting Files

Please make sure that you overwrite the existing files when uploading to the SFTP server.

Privacy and Security

Please note that educational data is confidential and protected by federal and state regulations. ClassTag goes to great lengths to ensure that data is handled properly and that all parties’ rights are protected.

Please make sure that you follow your Educational Institution’s internal procedures for handling sensitive information.

Please do not send student data via email. Email is not a secure transfer method.

Users File

The users.csv file is used to provide details about each student, guardian, teacher and administrator.

File Format

sourcedId*

The unique identifier provided by your SIS for the User

orgSourcedIds†

sourcedIds of the Orgs to which this user belongs

role*

Please pick one of student, guardian, parent, relative, teacher, administrator, aide, and proctor. If a user has multiple roles, he should be represented by multiple user records with different roles

givenName

The person’s first name

familyName

The person’s last name

email**

Person’s email address

sms**

A SMS-enabled cell number. Because we send messages to this number, please use the “phone” field if you are unsure if the number is SMS-enabled

phone

Any telephone number. It can be a cell or a landline

agentSourcedIds

The sourcedIds of a student’s parents (or a parent's students) separated by commas and wrapped by double quotes, e.g., "sourcedId1,sourcedId2"

grades

Grade(s) for which a user with role 'student' is enrolled. Please see the Grade Level Codes to find the supported Grades. Currently ClassTag only accepts the “youngest” grade on the list

language

Please see the Language Codes table

* - required

** - one of the two is required

† - required for the district-wide rostering, ignored for the school-wide rostering which results in all records being added to the school

Notes

Adding Guardians

To avoid “unassociated” users, guardians are not added if they are not referenced with an agentSourcedId in a student record. If you are unable to provide this reference, we suggest you use the Guardians File.

Adding guardians to students can be tricky for some SIS that don’t natively and fully support the OneRoster format. For this reason, we offer a few different methods for importing guardians.

  • Standard OneRoster Method: You can add guardians for students in the Users file by providing agentSourcedIds (the sourcedId for their guardians).

  • Using the Guardians File. You can add guardians via the Guardians File. You will work with your Customer Success Manager to determine if this approach is right for you.

  • Adding Guardians Manually. Your teachers can add Guardians from their classroom, through the school directory or via printed invitations.

A Student can have a maximum of 6 Guardians on ClassTag.

Contact Information

ClassTag requires users to have either an email address or an SMS-enabled phone number. ClassTag supports a maximum of one email address and one phone number for each user.

If you have more than one email address for a parent, you must choose only one. If you have more than one SMS-enabled phone number, similarly, you must choose one.

ClassTag also provides an optional Home Phone Number for informational purposes.

Teacher/Administrator Contact Information (email)

Because of the volume of communication, we require that teachers and administrators use an email address.

Classes File

The classes.csv file is used to provide details about each classroom or section in which a student or teacher can be enrolled.

File Format

sourcedId*

The unique identifier provided by your SIS for the Classroom

title*

Name of the class

grades*

Please see the Grade Level Codes. The list is comma-separated if a classroom has more than one grade. Currently, ClassTag only accepts the “youngest” grade on the list. Empty grade transforms into IT - Infant/toddler. Invalid grade prevents a class from being created

location

A room number

schoolSourcedId†

sourcedId of the Org that teaches this class of OrgType "school"

periods

This is the time slots in the day that the class will be given. If more than one period is needed, use double quotes, and separate with commas.

* - required

† - required for the district-wide rostering

Notes

Classroom Title must be between 2 and 50 characters long. Longer titles will get cropped during the sync.

Enrollments File

The enrollments.csv file is used to connect students and teachers to classes.

File Format

classSourcedId*

The unique identifier provided by your SIS for the Classroom

schoolSourcedId†

sourcedId of an Org with type “school”

userSourcedId*

The unique identifier provided by your SIS for the User

role*

student or teacher

* - required

† - required for the district-wide rostering

Notes

Only students and teachers are associated with classrooms. Guardians are associated indirectly with the classroom through their students.

Guardians File

The guardians.csv file is used to add guardians and connect them to their students.

File Format

studentSisId*

Same as student sourcedId

guardianSisId*

Same as guardian sourcedId

guardianFirstName

The person’s first name

guardianLastName

The person’s last name

guardianEmail**

Person’s email address

guardianPhone**

A SMS-enabled cell number. Because we send messages to this number, please use the “guardianHomePhone” field if you are unsure if the number is SMS-enabled

guardianHomePhone

Any telephone number. It can be a cell or a landline

guardianLanguage

Language code. Please see the Language Codes table. Empty value sets user’s language to English

* - required

** - one of the two is required

Notes

The Guardians File is a custom file designed to make it easier to import guardians when a school’s SIS does not natively support the OneRoster format, or when there are other configuration issues.

The Guardians File is processed after the Users File.

When using the Guardians File in addition to Clever synchronization, please make sure that the studentSisId in the Guardians File has the same values as the sis_id or student_number (please decide what ID works best for you and use it for all students) for students on Clever.

Self-Check Checklist

Please review and answer the questions below to speed up the setup process for your organization.

  1. Do the files you plan to use have the correct names: users.csv, classes.csv, enrollments.csv, guardians.csv, student_attributes.csv.

  2. Does your users.csv file include agentSourcedIds? If not, do you plan to use the Guardians File for importing guardians?

  3. Do the guardians in your SIS have their own SIS IDs?

  4. If not using Guardian files, please confirm your users.csv includes all roles (administrators, teachers, students, guardians and/or parents)

  5. If using the Guardians file, please confirm your users.csv includes all roles but guardians (administrators, teachers, students)

  6. Please confirm your users.csv, classes.csv, enrollments.csv and (optional) guardians.csv are in .csv format (not .xls, .xlsx or anything else.)

  7. Please confirm that the first row in each of the files has the correct name, as shown in the file tables displayed in this document.

  8. Please confirm that each of the required fields has values.

  9. Does the number of records in each file look reasonable? Do you have the right number of students, parents, teachers, classes, etc.?

  10. Please double-check file names and format:

    1. Do files have the correct names? Check for typos, letter case.

    2. Do files have the “.csv” format?

    3. Do files use UTF-8 or ASCII encoding? If your file uses another encoding (e.g. ISO-8859-1) and cannot be converted to UTF-8, please let us know about it at support@classtag.com. If you’re not sure about the file encoding, you may feel free to proceed with the setup. We’ll be able to help you at a later stage if encoding-related issues arise.

    4. Please make sure the double quotes are used correctly. See this section.

  11. Did you put the SMS-compatible phone numbers in the proper columns: SMS column in the users.csv and/or guardianPhone column in the guardians.csv file?

  12. If using Guardians File in addition to Clever sync, please confirm that studentSisId in the Guardians File is the same as sis_id or student_number for students on Clever.

  13. Please make sure that Student IDs in users.csv, enrollments.csv and guardians.csv files are identical.

  14. Please make sure that Teacher IDs in users.csv and enrollments.csv files are identical.

  15. If using the users.csv file to add guardians, please make sure that guardian IDs are identical with agentSourcedIds on students, or, that student IDs are identical with agentSourcedIds on guardians.

  16. If using the guardians.csv file, please make sure that student IDs in guardians.csv file are identical to student IDs in the users.csv file.

  17. Please make sure that the Language column only includes the supported values. Please find the spec in this section.

  18. Please make sure that there are no unescaped commas in user names. Please see this section.

Have any questions? Please contact your Customer Success Manager or our support at support@classtag.com

Appendix A: Guardians Without IDs

In some systems, guardians are not “first class objects”. In this case, the guardians are represented as email addresses associated with the student.

A “first class” object has its own ID - in this case, the guardian has an ID, email and phone addresses, a name, etc. The guardian is associated with the student by their ID, not their addresses.

If your SIS does not have Guardian IDs, please expect the following limitations:

  1. The system will not update an existing guardian’s email address or phone number.

  2. If you change a guardian’s email address or phone number, a new guardian user account will be created for that student. Note that if you change a phone number for a guardian that already has an email address, the user’s phone number will not be updated.

  3. The old guardian account will not be removed automatically. That account will continue to be connected to the student and that address will continue to receive notifications.

  4. You will need to remove old guardian accounts manually through the Directory.

  5. If a guardian changes their email address on ClassTag but not in the SIS, the next sync will create a new account with the SIS email address.

We recommend that you manually upload guardian data when you do not have guardian IDs. We do not recommend automating your guardian data. Our customers usually perform a one-time guardian upload manually at the beginning of the year, and make manual updates as the year progresses.

Appendix B: Related Documents

Users File: File example, Help article

Guardians File: File example, Help article

Classes File: File example, Help article

Enrollments File: File example, Help article

Student Attributes File: File example

EXPLORE MORE:

Did this answer your question?