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.
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:
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, email@example.com) - 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
|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|
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.
Used to identify user's residency for tuition purposes.
|School ID||ID of the school. Your CS Consultant will provide this value to you.||No|
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:
Astrit,,Mehmeti,LOGIN766,firstname.lastname@example.org,71992,,,,,,,,sch.prog.BIS.,BIS22S766,1,0 Astrit,,Mehmeti,LOGIN766,email@example.com,71992,,,,,,,,sch.prog.BIS.,BIS22766,1,0 Nick,,Powers,LOGIN775,firstname.lastname@example.org,31993,,,,,,,,sch.prog.MGMT.,MGMT44S775,1,0 Nick,,Powers,LOGIN775,email@example.com,31993,,,,,,,,sch.prog.BUSN.,BUSN319S775,1,0 Nick,,Powers,LOGIN775,firstname.lastname@example.org,31993,,,,,,,,sch.prog.MATH.,MATH221775,1,0 Michael,,Vasilou,LOGIN746,email@example.com,31989,,,,,,,,sch.prog.ACCT.,ACCT346S746,1,0 Michael,,Vasilou,LOGIN746,firstname.lastname@example.org,31989,,,,,,,,sch.prog.BUSN.,BUSN42S746,1,0 Michael,,Vasilou,LOGIN746,email@example.com,31989,,,,,,,,sch.prog.ACCT.,ACCT21746,1,0 Josie,,Anagbogu,LOGIN822,firstname.lastname@example.org,71992,,,,,,,,sch.prog.CIS.,CIS45S822,1,0 Josie,,Anagbogu,LOGIN822,email@example.com,71992,,,,,,,,sch.prog.CIS.,CIS438S822,1,0 Gail,,Kroepel,LOGIN28,firstname.lastname@example.org,61981,,,,,,,,sch.prog.CIS.,CIS34928,1,0 Gail,,Kroepel,LOGIN28,email@example.com,61981,,,,,,,,sch.prog.CIS.,CIS4528,1,0 Veronica,,Noble,LOGIN3376,firstname.lastname@example.org,32,,,,,,,,sch.prog.CIS.,CIS2113376,1,0 Douglas,,Skinner,LOGIN3341,email@example.com,721,,,,,,,,sch.prog.MATH.,MATH13341,1,0 Paul,,Bierbauer,LOGIN189,firstname.lastname@example.org,9198,,,,,,,,sch.prog.ECT.,ECT261S189,1,0 Paul,,Bierbauer,LOGIN189,email@example.com,9198,,,,,,,,sch.prog.COMP.,COMP128S189,1,0 Paul,,Papaioannou,LOGIN34,firstname.lastname@example.org,11968,,,,,,,,sch.prog.EET.,EET22S34,1,0 Paul,,Papaioannou,LOGIN34,email@example.com,11968,,,,,,,,sch.prog.EET.,EET42S34,1,0 Paul,,Papaioannou,LOGIN34,firstname.lastname@example.org,11968,,,,,,,,sch.prog.EET.,EET44S34,1,0 Timothy,,Hart,LOGIN795,email@example.com,11996,,,,,,,,sch.prog.HUMN.,HUMN42S795,1,0
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.||
|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.||
|Invalid email address||Each user must have only one email address.||
|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.||
|Missing required field||Make sure all required fields contain data. A data column may contain the wrong type of data.||
|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.||
|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||
|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.||
|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.|