Twig: Rostering with Twig Science Formatted (TSF) CSV files

 In this guide, you'll learn how to create, upload, and manage your TSF CSV files to ensure an error-free rostering process. Tailored specifically for District Admins, this guide is here to help you easily navigate all the ins and outs of rostering.

Step 1: Create your CSV files

We require a users.csv file and a classes.csv file to roster all users. Download the file templates to add your district information. 

Download file templates

The sections below provide detailed guidance on how to fill out each CSV, including required fields, formatting tips, and important notes to help you avoid common errors.

Creating users.csv

The users.csv file must include all users who need access to Twig Science; students, teachers and school administrators. Each time you upload, ensure the file contains a complete list of everyone who needs access. If a user is removed from future uploads, their account will be archived and their access revoked.

 Caution

When updating your roster via CSV uploads, ensure that all active users remain listed in the users.csv file. Any users omitted from this file during an upload will be automatically removed from the Twig Science platform. To maintain user access and data integrity, always include all currently active users in each users.csv upload.

Your users.csv file should look something like this: 

Screenshot 2021-08-03 at 15.40.14.png

 

Notes on completing your users.csv file

This table outlines the required structure for your users.csv file. Be sure to include all required fields and follow the formatting notes to ensure an error free upload.

Heading Notes Required
user_id Each user must have a unique and permanent case-sensitive identifier. This user_id will be used in the classes.csv file as the teacher_id, student_id. YES
first_name First name YES
last_name Last name YES
username A unique and permanent identifier NO
password Data is optional, but the header must be present NO
role Should contain one of the following values to specify the user's role:
  • student
  • teacher
  • administrator
YES
email Data is optional, but the header must be present NO
school_names Data is optional; however, to ensure administrators have access to specific school reports, school_names should be included for any users with the administrator role. NO

 Note

District admin accounts are provided by us, and the term administrator in this document refers to a school administrator account. For more information on available user roles, please refer to Twig Available User Roles.

 Caution

Important: Do Not Reuse User IDs

Each user_id must be unique and permanently assigned to a single user. These IDs should never be reused or reassigned—even if a student has left the school or district, or after a school year rollover. Reusing IDs can lead to serious issues with data integrity, user accounts, and access within the Twig Science platform. Our system does not support ID reuse under any circumstance.

 

Creating classes.csv

The classes.csv file should list the schools and classes each student and teacher belongs to. Every teacher and student referenced in the classes.csv file must also be listed in the users.csv file.

Be aware that any errors in the classes.csv file could result in teachers or students being rostered in the wrong school or class.

Your classes.csv file should look like this:

Screenshot 2021-07-22 at 14.38.47.png

Notes on completing your classes.csv file

Use this table to check the structure and required fields for your classes.csv file. Following the correct format helps prevent sync errors and ensures your data is processed correctly.

Heading Notes Required
class_id Should be a unique and permanent identifier for each class. YES
class_name The name of the class "Room 1" etc. YES
school_name   YES
teacher_id This is the user_id of any teacher listed in the users.csv YES
student_id This is the user_id of any student listed in the users.csv YES
grade The grade associated with the class. Must be one grade from the CEDS grade list. YES
Optional: Enabling Google Classroom Single Sign-On

You can enable users to sign in with their Google credentials by including their Google email addresses in your users.csv file.

To log in using single sign-on (SSO), users should visit login.twigscience.com and click Log in with Google.

rtaImage.jpeg

 Note

If your district uses Google Workspace for Education, you will need to approve the Twig Science app in your Google Console first. Please read Google's guide:  Control which third-party & internal apps access Google Workspace data

CSV Upload Checklist

This checklist is designed to help you finalize your data, and ensure your CSV is correctly formatted to avoid upload errors. Review each section carefully and complete all checks to prevent disruptions.

Check Details
Ensure there are no duplicated entries in the users.csv file. Top tip: Sort the column by alphabetical order to make it easier to spot duplicates. 
Every user should have a unique and permanent user_id If someone leaves, archive their ID. New users should always be provisioned with a new ID.
Verify spelling of school and class names to prevent duplicates or errors.
Confirm both files contain the required headers for proper processing. Download our file templates here which contain the correct headers. 
All users in classes.csv must also appear in users.csv.
Files uploaded to the SFTP folder must be named exactly users.csv and classes.csv. This naming convention is mandatory. Files with incorrect names will cause errors and prevent successful rostering.

 

Step 2: Choose your CSV upload method

You can upload your rostering files using one of two methods: Twig Science Website Self-Service or SFTP Upload. Each option offers a different level of flexibility and setup depending on your district’s needs.

  • Website Self-Service is our recommended method. It’s fast, user-friendly, and provides instant feedback so you can resolve issues right away.
  • SFTP Upload is best suited for districts with existing secure file transfer processes and automated workflows.

The sections below walk you through how each method works, what you’ll need to get started, and how to ensure your uploads are successful.

CSV upload via Twig Science Website Self-Service (Recommended)

This is the easiest and most flexible way to upload and manage your rostering files.

How it works:

  • Use your District Admin login details to access the Twig Science Admin Dashboard (contact your Customer Success Manager if you need your username or password).
  • Upload your users.csv and classes.csv directly through the dashboard.
  • Access real-time updates and error messages through the import log.
  • Check the status of your upload and resolve any issues promptly.

Why we recommend this option: 

It’s fast and flexible, with no need for SFTP setup, and provides immediate feedback to reduce sync delays, making it easy to troubleshoot and re-upload without waiting.

CSV upload via Twig Science Website Self-Service interactive guide

Follow our interactive, step-by-step guide to learn how to upload rostering files to Twig Science using our self-service dashboard.

 Note

Access to our self-service dashboard requires a District Admin account. If you do not have one, please contact your CSM.

CSV upload via SFTP server

This method is suitable for districts with established SFTP workflows.

How it works:

  • Ensure your SFTP client is configured correctly with the provided credentials.
  • Upload your users.csv and classes.csv to the designated SFTP folder.
  • Monitor the upload status and check for any error messages.

Uploading the CSV files to our SFTP server

After you create the CSV files in the required Twig Science format, please upload them to the Twig Science SFTP account. Credentials will be supplied during initial setup with your CSM, and will look like the following:

  • Hostname: sftp-rostering.twigscience.com
  • Port: 22
  • Username: [district specific]
  • Password: [district specific]
  • Folder path: [not required]

If you need to download an SFTP client, we recommend FileZilla.

Your update will be processed overnight and you will receive an email to confirm that the update has been successful.

 

Step 3: Sync and test

After each upload, you’ll receive a sync confirmation, either through the admin dashboard or by email (if using SFTP). If there are any issues, you can check the import log on the dashboard or contact support@twigeducation.com.

You can update your district data at any time using your chosen upload method. SFTP uploads are processed nightly, and you’ll receive an email once the overnight sync is complete.

Once the sync is complete, the rostering database will be updated based on the contents of the users.csv and classes.csv files:

  • New records in the CSV will result in new users being created.

  • Missing records (compared to the previous upload) will result in those users being archived. Archived users can be reactivated by including their original ID in a future upload.

  • Existing records with updated information will modify the corresponding user accounts.

After syncing, you can log in as a teacher or student to verify the updates. Credentials will be listed in your users.csv file.

Troubleshooting sync errors

Having trouble with your upload? It’s usually something simple. Use the tabs below to spot and fix common issues like duplicate users or file name mistakes. If you're still stuck, reach out to your CSM for help.

Duplicate Users User ID Issues Typos & Headers File Naming & References

Duplicates in your users.csv file can prevent proper syncing. To check for these quickly, sort your file by name or email. Removing any repeated entries should help resolve the issue.

How do users log in after syncing?

All users can log in at app.twigscience.com/login using:

  • Google SSO

  • Twig username or email and password (specified in users.csv)

Useful downloads and further reading

 

Back to Top