Always Learning

The delimited file format is one of two file types that support asynchronous ("batch") creation or modification of user and enrollment information in LearningStudio. See Batch File Rules and Batch File Submissions for an overview of Batch Enrollment File processing, such as required configurations, high-level data flow, file naming conventions, etc. See XML Files for a description of the other supported file type.

A delimited text file is a file in which each new data record is separated by a line break character (such as a hard return). Within each record, the individual data values are separated by a delimiter character. The delimiter character is not part of the data value, but only serves to designate where each data value begins and ends. For example, a comma-delimited file uses a comma between each data value and ends each record with a hard return. The data values must not contain the delimiter character (for example, within a comma-delimited file, a data value cannot include a comma within its string). Be sure to use a delimiter character that would not be included as part of any of your data values.

Each data record within the file has the same fixed number of data values. The order of the data values designates the type of data in each position (also known as a column). If there is no data for a specific data type, a delimiter is still added to define that position, but no data is provided (an "empty" delimiter); this ensures that the positioning of subsequent data in the record remains correct.

Important: Every delimited file submitted to the Batch File system must follow this file format or the file will not be processed.

Note: Commonly, delimited files use the first row as a "header" row where a descriptive title for each data type is provided (for example, "FirstName", "LastName", etc.). The Batch File system does not support having a header row in the delimited file and assumes that the first row contains real data. If the first row has header information, the batch data file processing will fail.

Delimiter Characters

The system supports the following delimiter characters to separate data values within each record:

  • \t - tab delimited
  • , (a comma) - comma delimited
  • | - pipe delimited

Note: Only one type of delimiter character can be used within a file (they cannot be used in combination within a single file).

Each record within the file must be ended with a hard return. If you are coding the hard return, you will need to include an End of Line String variable at the end of each record as a carriage return( \r ) followed by a line feed (\n). Always create the hard return in the Windows style. For example: \r\n.

See Batch File Rules for a description of the file naming convention required for the delimited files.

Delimited files can be easily created using a spreadsheet like Microsoft Excel or a text editor like Notepad. Just be sure to save the file as *.txt, without embedded formatting.

Note: You may need to insert hard returns at the end of each record.

Note for Excel Users: By default, Excel's comma-delimited export format does not conform to the Batch File specifications and should therefore not be used. If you want to use a spreadsheet to create your file, you should (1) make sure the upper-leftmost cell (cell A1 in Excel) contains only the letter T and (2) export using the Tab-delimited format. Files created in this manner are compatible with the Batch File system if the system is configured to use the tab-delimited file type.

Delimited File Layout

Each delimited file must have 17 columns. Be sure to provide the appropriate data value in each column within the file.

If you are modifying existing user information, you must provide the login ID exactly as it appears in the LearningStudio system. For example, if the users' login IDs include hyphens and hyphens are required when they log into the system, you must include the hyphens in the delimited data file.

Important: The login ID is the primary identifier for the user in the LearningStudio system.

If you are adding new user records, a Yes in the Required for New User? heading indicates that you must provide data for that specific data value/column; a No indicates that the data is optional and you can use an empty delimiter if you do not want to add the data.

The following table outlines the required file format and columns:

Name Description Required for New User?
First Name User's first name Yes
Middle Name User's middle name No
Last Name User's last name Yes
Login ID (Username) Primary identifier for the user in LearningStudio. Login IDs must be unique for each user within your campus. Also called a username. Note that this field cannot be updated or changed.

If the Login ID exists in LearningStudio, the user's information will be updated with the information in this file. If it does not already exist, a user account will be created.

Email Address User's fully-qualified email address (for example, - Each user can have only one email address. Yes
Password The user's LearningStudio password. Provide a password if you are adding a new user record; otherwise, the new user record creation will fail. Note, the following special characters are not allowed in the password field: % ] [ + < > " ; ' = : / | \ _ ; Yes
Daytime phone number User's daytime phone number No
Evening phone number User's evening phone number No
Street Address Street address of the user's primary address No
City City of the user's primary address No
State/Province State or province of the user's primary address No
Postal Code Zip code of the user's primary address No
Country Country of the user's primary address No
Node Sort String Client sort string for the enrollable node where this user will be enrolled. For example, if this is in the business school node at Strata University, this value may be (in Client Sort Strings, always include the final period). Users must be enrolled in a node to be enrolled in any of the courses in that node. Yes
Course Call Number Your system's identifier for a course section in LearningStudio. Required to process section or course enrollments. Each instance of a cross-listed course must have its own unique identifier. It is possible for a single section or course slot in LearningStudio to be assigned multiple call numbers. If a user is enrolled into the same section using more than one call number, the API will enroll the user multiple times in that section. This is usually an error. Yes
Role ID LearningStudio defines roles in a very granular fashion, tailored to the needs of each EP and the standard role types for role are not specific enough. Your Strategic Customer Operations team can provide the specific role IDs to use for your campus.

If you want to unenroll a user from a course or node, you use this same approach, but set the Role ID to the "Dropped User" value for your campus. Your SCO team will provide this.

Instate Used to identify user's residency for tuition purposes.
 1 = User lives in-state.
 0 = - User lives out-of-state.
School ID ID of the school. Your CS Consultant will provide this value to you. No

Sample File

The following is an example of a comma-delimited text file format. Each value is separated by a comma, and if a non-required value is not present, then empty delimiters act as placeholders. For example, the file does not contain day phone, evening phone, street address, city, state, postal code, or country; however, the fields for each of these values are still marked by a delimiter:


Common File Errors

The following are some of the more common errors encountered when submitting a delimited data file. This is a good reference prior to submitting a file or when there have been issues with a file.

Error Possible Causes Suggested Solutions
Incorrect delimiter The delimiter is not a comma, pipe, or tab.
  • Confirm that each data value is separated by one of the approved delimiter characters.
  • Confirm that the correct number of empty delimiters are used to indicate no data for a specific column.
  • Confirm that none of the data values contain the delimiter character.
  • If you used another application (such as Microsoft Word or Excel) to create the delimited data file, be sure to save as unformatted *.txt file. Many applications insert control characters, embedded formatting, etc., that may confuse the API process, causing it to fail.
Special characters in file name The file name should be formatted as: ClientString_DD_MM_YYYY.txt. The file name cannot contain special characters such as ( ) , " " & @ and so on. Confirm file name is properly formatted and does not contain special characters.
Invalid file extension The delimited data file must have a *.txt extension. Save file in correct format and with correct extension.
Extra column Every delimited file must have either 17 (if no Division Tools are used) or 18 (if Division Tools are used) columns only.
  • Confirm each data record has the appropriate number of columns.
  • Confirm that there are the correct number of empty delimiters (a common mistake is to add too many or too few).
Invalid email address Each user must have only one email address.
  • Confirm that no more than one email address has been added for a user.
  • The email address must be fully qualified (for example, ""). The API will check for a valid email format.
  • The email address column cannot be left blank for a new user.
Large batch data file or cumulative file Large or cumulative files that are formatted correctly should process successfully; however, they are prone to errors and system-time outs. Batch File Submission for suggestions/rules to help ensure proper processing of large data files or cumulative files.
File upload timed out File is too large or too complex. Connectivity may have been lost during transfer.
  • Break up large data files into more manageable sizes.
  • for more information).
  • Confirm that there were no issues with your network or connectivity during the file transfer.
  • for suggestions/rules to help ensure proper processing of large data files or cumulative files.
Missing required field Make sure all required fields contain data. A data column may contain the wrong type of data.
  • .
  • If you are modifying an existing user's information, the login ID is required.
  • Confirm that the appropriate data is placed in the appropriate column/position within the data record.
Missing password and auto-generate passwords is not enabled  API configuration is not set to Yes, you must provide a password for each new user.
  • Provide a valid password for each new user.
  • API configuration to Yes to auto-generate passwords for new users.
Invalid Login ID The login ID cannot contain any of the following special characters: % ] [ + < > ; " ' = : / | \ _ Confirm the login ID does not contain special characters.
Invalid Password The password cannot contain any of the following special characters: % ] [ + < > ; " ' = : / | \ _ Confirm the password does not contain special characters.
Invalid Role ID  for more information. Confirm the Role ID is set to one of the approved ennumerable values.
Specified Node Sort String is unenrollable Users cannot be enrolled in node unless the node is configured to be enrollable
  • Confirm node is enrollable.
  • Change value to enrollable node.
Failed attempt to drop user from node with section enrollments A user can only be dropped from a node when (1) they are not enrolled in any sections within that node, and (2) they are enrolled in at least one other node. Confirm user is not enrolled in any of the node's sections and/or is enrolled in another node.
Failed attempt to drop user from last enrollable node Dropping users from their last node causes them to no longer be associated with the Educational Partner. The API cannot drop a user from their last enrollable node.  
Login ID is not unique for explicit user creation The user has already been created in LearningStudio; the login ID in the data file is already in use and cannot be assigned to a new user.
  • Confirm that the login ID does not already exist in LearningStudio for another user.
  • Confirm that the user does not already have information in LearningStudio and thus should not be added as a new user.
Failed to drop a user who is not enrolled in the section The user is not enrolled in the section and a DROP (Role ID: 5) action is passed for the user. Confirm the correct section number was provided.
Failed to enroll a user when the add date is in the past tab in the Administrative Pages UI.  
Failed to drop a user when the drop date is in the past  tab in the Administrative Pages UI.  
Professor enrollment attempted for a user already enrolled as a Student on the node For security purposes, a user that is enrolled in a node as a Student cannot be enrolled in a section as a Professor. Change the enrollment role for the user to the appropriate Role ID.
Failed to enroll a user in a section where the enrollment max has been reached  section of the Administrative Pages UI.  
Failed to enroll a user as a waitlist student where the waitlist max has been reached  section of the Administrative Pages UI.  
Failed attempt to add/update an Admin role type For security purposes, the API will not create, enroll, or update an Administrator account. Confirm that the correct Role ID was used.
2857 reads
Always Learning