OneRoster File Specifications: users.csv

This article explains the users.csv file specification for OneRoster v1.1 customers.

If this is your first time using bulk-formatted OneRoster v1.1 CSV files, we recommend using the 1EdTech CSV ZIP File Validation tool to check your files for formatting and data errors prior to sending them via SFTP to Great Minds.

In order to use this tool, you must log into an active 1EdTech account. If you do not have a 1EdTech account, you can sign up for a free account.

This may take up to 24 hours. If you need additional assistance with your 1EdTech account or the CSV Zip File Validation tool, contact 1EdTech directly.

File Requirements

In order for your file to process successfully, your file must meet the following criteria:

Must be in .csv format named “users.csv” within your OneRoster zip file
Must contain all column headers listed in the order shown below (even if you intend to leave the column blank)
Must not be empty
Contains data in all required columns

See 1EdTech's website for the full specification for the users.csv file. The specification has been modified below to reflect Great Minds support.

Column Field Header	Required	Supported Format	1EdTech Description	Great Minds Data Requirements	Example Data
sourcedId	Yes	GUID	Unique ID for the user. SourcedId is used in other files and must be unique across all users.	Must be unique to the district Must contain 100 or fewer characters Supported characters: [a-z]  [A-Z]  0-9  hyphen, underscore, dot	112582
status	No	Enumeration	The status of the record. Note: Leave this column blank. Great Minds supports bulk mode only and does not read data in this column.
dateLastModified	No	dateTime	The date that this record was last modified. Note: Leave this column blank. Great Minds supports bulk mode only and does not read data in this column.
enabledUser	Yes	Enumeration	Permitted values: true, false		true
orgSourcedIds	Yes	List of GUID References	SourcedIds of the Orgs to which this user belongs. (Note: In most cases, users will belong to a single school).	Must belong to an existing org with the correct type: student, teacher, administrator, and school_admin roles must be connected to an org with type “school” district_admin or administrator roles may be connected to an org with type “district”	1888
role	Yes	Enumeration	Permitted values: administrator, aide, guardian, parent, proctor, relative, student, teacher	Must be “administrator”, “teacher”, or “student”	teacher
username	Yes	String	Username.	Must be unique to the district  Cannot be an email address  Minimum of 5 characters  Maximum of 100 characters  Supported characters:  [a-z]  [A-Z]  0-9  hyphen, underscore, plus, dot	jonathonrogers
userIds	No	String	External machine-readable ID (e.g. LDAP id, LTI id) for the user. The ID must be accompanied by a type to indicate the nature of the Identifier. The Type and ID values are enclosed in '{}' with a colon used to separate the values. If more than one userId is needed, use double quotes and separate with commas (per RFC 4180). Examples: {LDAP:Id} "{LDAP:Id},{LTI:Id},{Fed:Id}"		{LDAP:22841}
givenName	Yes	String	User’s first name.	Must contain 250 or fewer characters	Jonathon
familyName	Yes	String	User's last name.	Must contain 250 or fewer characters	Rogers
middleName	No	String	User’s middle name(s). If they have more than one, separate them using a space.	Must contain 250 or fewer characters	Paul
identifier	No	String	Identifier for the user with a human readable meaning.		9898-PJN
email	No	String	Email address for the User.	Must be unique to the platform  Must be in email address format (name@domain.com)  Supported characters:  [a-z]  [A-Z]  0-9  hyphen, underscore, plus, dot, @	jonathon.rogers@greatmindsdemo.org
sms	No	String	SMS address for the User.		5559190099
phone	No	String	Phone number for the User.		5559190099
agentSourcedIds	No	List of GUID References	SourcedIds of the Users to which this user has a relationship. If multiple IDs are required, use double quotes and separate with commas. Note: In most cases, this is used to indicate parental relationships.
grades	No	String	Grade(s) for which a user with role 'student' is enrolled. The permitted vocabulary is from CEDS (Version 5) for the 'Entry Grade Level' element.	Only supported for users with a role of “student” Must be exactly one of the following values: IT, PR, PK, TK, KG, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, PS, UG, Other
password	No	String	The password for the user. This may or may not be an encrypted string. If encrypted, the systems processing must be aware of the encryption method.	Minimum of 8 characters  Must contain at least 1 lowercase letter  Must contain at least 1  number	JonathonRogersGM22
metadata.gm.additionalroles	No	Enumeration	Permitted values: district_admin, school_admin, teacher	Must be “administrator”, “district_admin”, “school_admin”, or “teacher”	school_admin
metadata.gm.reset.password	No	String	Use to reset a user's password. When a password is present in this column, the user's previous password will be overwritten. Once the user's password is reset, be sure to remove the value before the next overnight sync or the user's password will be reset again.	Minimum of 8 characters  Must contain at least 1 lowercase letter  Must contain at least 1  number

Tips

Great Minds can support users with multiple roles through the use of a custom metadata field "metadata.gm.additionalroles" column. For users that should have an additional role, add the desired additional role into this field: district_admin, school_admin, or teacher. Student users cannot have multiple roles.

Great Minds does not support the following roles:

aide
guardian
parent
proctor
relative

The following fields are not currently utilized in Great Minds products:

userIds
identifier
sms
phone
agentSourcedIds

Format Definitions

Format Type	Definition
GUID	'GUID' denotes some form of globally unique identifier (this must be less than 256 characters). This is not restricted to the 128 bit UUID format.
GUID Reference	'GUID Reference' denotes the GUID of an object defined in some other CSV data file.
List of GUID Reference	'List of GUID Reference' denotes a comma-delimited list of GUID References of objects defined in another CSV data file.
String	'String' denotes a sequence of characters that should follow the description. Generally this is aimed to be human-readable, e.g., "Science Lesson.”
Enumeration	'Enumeration' denotes a fixed set of values that will be referred to in the description. In the case of fields which are not required, an empty field denotes no value.