Roster Import Guide. Document version 3.1

Transcription

1 Roster Import Guide Document version 3.1

2 Document version number Date of revision Version 2.0 August 15, 2007 Version 2.1 August 28, 2007 Version 2.2 October 9, 2007 Version 2.3 December 16, 2007 Version 3.0 August 15, 2008 Version 3.1 August 18, 2008 Riverside Publishing Customer Support: phone: hours: Monday-Friday 7:00 a.m. to 9:00 p.m. EST Page 2 of 23

3 Roster Import Guide The Online Assessment System (OAS) allows school coordinators and/or system level administrators to import student, teacher, and class data into OAS through the web interface. Three steps are required to import roster information to OAS: (1) create the import files in the proper format and layout (2) upload and verify the import files (3) schedule the actual importing of the import files Import Files: Format and Layout Three separate files must be created: one each for students, teachers (including administrators), and classes. These 3 files are then combined into one import job. Each file must be a text file, with a delimiter that separates fields. You can use commas or tabs as delimiters. Comma-delimited text files have extensions of.csv or.txt. Tab-delimited text files have extensions of.txt. WARNING: If you use commas as the delimiter, make sure that no fields have a comma in them (e.g., names must not include commas: Smith, Bill or Bill Smith, Jr. Both would cause errors.) Every student logon ID, teacher logon ID, and class record ID should be unique. There can be no duplicate IDs. Note: Use students Georgia Test ID (GTID) in the student logon ID and in the Unique Student Identifier field. Rosters are listed alphabetically by name (for teachers and students) or title (for classes) and are shown exactly as entered in the relevant fields. In most cases, it is more useful to have teachers and students listed alphabetically by their last name. NOTE: The 3 files (class, teacher, and student) can be imported at the same time. If, however, the 3 files are being imported separately, be sure to import the class file first, then the teacher file, and then the student file Page 3 of 23

4 Class Import File Layout: Field Name Field Data Type (Max. length) Example Required Values Restrictions/Comments Class_ID 1 Varchar (25) Yes Alphanumeric; allows hyphens Must be unique. Cannot contain and underscores but not spaces special characters. NO: asterisks, commas, parentheses, single or double quotes, periods, exclamation marks, or spaces. Class_Title 2 Varchar (50) Geometry 201 Yes Alphanumeric; allows hyphens, Spaces are the only allowed special underscores, and spaces characters. NO: asterisks, commas, parentheses, single or double quotes, periods, or exclamation marks. Begin_Date 3 Date (10) 01/05/2008 No The beginning of the class or Not required but recommended. May semester (mm/dd/yyyy). specify a date prior to the current date or beginning of class or semester. End_Date 4 Date (10) 06/30/2009 No The end of the class or semester Not required but recommended. Must (mm/dd/yyyy). specify a date later than the current date. May specify a date after the end of the class or semester. Active 5 Long Integer (1) 1 No 1 = Active (default) Not required, but if left blank, the 0 = Inactive system inserts a default value of active and generates a warning. Grade 6 Integer (2) 2 No K, 1 12, HS Not required but if not selected, grade level will not be included on reports. Test_ID 7 Varchar (25) Geo1 No Alphanumeric; allows hyphens Not required. and underscores but not spaces Notes: If you do not put any tests in the class file, that class will have zero tests (however, teachers and coordinators can manually assign tests to classes). If you want to assign more than one test to a class through the import process, list all the tests at the end of the record, with a delimiter between each test Page 4 of 23

5 Teacher Import File Layout: Field Name Field Data Type Example Required Values Restrictions (Max. Length) Logon_ID 1 Varchar (25) Wil9234 Yes Alphanumeric; characters allowed: Underscore [ _ ], Must be unique; can contain letters, numbers, and a few special characters. Hyphen [ - ], Period [. ] At CHARACTERS ALLOWED: Underscore [ _ ], symbol ] Hyphen [ - ], Period [. ] At symbol ] Teacher_Name 2 Varchar (50) Williams Kelly Yes Alphanumeric; allows hyphens, underscores, and spaces Password 3 Varchar (6-25) 9234 No Alphanumeric; allows hyphens and underscores but not spaces Spaces are the only allowed special characters. NO: asterisks, commas, parentheses, single or double quotes, periods, or exclamation marks. Password must be a minimum of six (6) characters. School_Identifier 4 Varchar (100) Grant Elementary Yes Alphanumeric; allows hyphens, underscores, and spaces MUST MATCH A SCHOOL LOCATION FIELD IN THE SYSTEM. (See Note below) Active 5 Integer (1) 1 No 1=Active (default) 0=Inactive Account_Type 6 Varchar (1) A No A=Administrator PT=PowerTeacher T=Teacher (default) Class_ID 7 Varchar (25) Math407 No Alphanumeric; allows hyphens and underscores but not spaces Not required, but if left blank, the system inserts a default value of Active and generates a warning. Not required, but if left blank, the system inserts a value of Teacher and generates a warning. Not required. Additional classes can be listed in fields 8 and higher. (See Note below) Notes: School_Identifier generally consists of the 7-digit (3-digit system + 4-digit school) GDOE code for the school, followed by the full name of the school (e.g., Peachtree County Elementary School). Teachers will import into OAS without being assigned to a class. However, you will have to manually assign each teacher to a class if you do not make this assignment through the import process. If you want a teacher assigned to a specific student, the School_Identifier and the Class_ID specified for that teacher must be the same as those specified for that student. Otherwise, when the teacher logs on, they will not see that student in the class. To assign a teacher to more than one class, list all the classes at the end of the record, with a delimiter between each class Page 5 of 23

6 Student Import File Layout: Field Name Position/ Data Type (Max. Example Required Values Restrictions Field Length) Logon_ID 1 Varchar (25) Yes Alphanumeric; allows hyphens and underscores but not spaces Use student s 10-digit GTID. Cannot contain special characters. NO: asterisks, commas, parentheses, single or double quotes, periods, exclamation marks, or spaces. Student_Name 2 Varchar (50) Travis Miller Yes Alphanumeric; allows hyphens, underscores, and spaces Spaces are the only allowed special characters. NO: asterisks, commas, parentheses, single or double quotes, periods, or Password 3 Varchar (25) student No Alphanumeric; allows hyphens and underscores but not spaces School_Identifier 4 Varchar (100) Adams Middle School Yes Alphanumeric; allows hyphens, underscores, and spaces Grade_Level 5 Integer (2) 6 Yes K, 1 12 Gender 6 Varchar (1) M No F, M NOT REQUIRED Ethnicity 7 Varchar B No (See codes in Appendix A) NOT REQUIRED (1-2) Birth_Date 8 Date (10) 10/01/1993 No mm/dd/yyyy NOT REQUIRED Active 9 Integer (1) 1 No 1=Active (default) 0=Inactive Unique_Student ID (must be same as Student Logon_ID) 10 Varchar (25) No Alphanumeric; allows hyphens and underscores but not spaces exclamation marks. Not required, but if left blank, the system inserts student as a default value and generates a warning. MUST MATCH A SCHOOL LOCATION FIELD IN THE SYSTEM. (See Note below) Not required, but if left blank, the system inserts a default value of Active and generates a warning. Use student s 10-digit GTID. (This is not required, but if left blank, the system inserts Student_ID as a default value and generates a warning.) Page 6 of 23

7 (Fields continued from previous page) Field Name Position/F Data Type Example Required Values Restrictions ield (Max. Length) SES (Special Education 11 Varchar (1) Y No Y or N NOT REQUIRED Service) PD (Primary Disability) 12 Varchar (2) 01 No (See codes in Appendix B) REQUIRED IF SES = Y S504 (Section 504) 13 Varchar (1) Y No Y or N NOT REQUIRED ELL (English Language 14 Varchar (1) Y No Y or N NOT REQUIRED Learner) FRL (Free or Reduced 15 Varchar (1) F No F=Free, R=Reduced, N=No NOT REQUIRED Lunch) GT (Gifted and Talented) 16 Varchar (1) Y No Y or N NOT REQUIRED MG (Migrant Student) 17 Varchar (1) Y No Y or N NOT REQUIRED T1 L (Title 1 Language) 18 Varchar (1) Y No Y or N NOT REQUIRED T1 M (Title 1 Math) 19 Varchar (1) Y No Y or N NOT REQUIRED Other1 20 Varchar Any text up to No Any alphanumeric text up to 80 NOT REQUIRED (80) 80 characters characters Other2 21 Varchar Any text up to No Any alphanumeric text up to 80 NOT REQUIRED (80) 80 characters characters Class_ID 22 Varchar (25) Math407 No Alphanumeric; allows hyphens and underscores but not spaces Value not required (See Note below). Additional classes can be listed in fields 23 and higher. Notes: School_Identifier generally consists of the 7-digit (3-digit system + 4-digit school) GDOE code for the school, followed by the school s name (e.g., Peachtree County Elementary). In such an instance, using or Peachtree County Elementary or Peachtree Cnty Ele or PEACHTREE COUNTY ELEMENTARY will all be considered invalid, and the import will fail. Students will import into OAS without being assigned to a class. However, you will have to manually assign each student to a class if you do not make this assignment through the import process. If you want a student assigned to a specific teacher, the School_Identifier and the Class_ID specified for that student must be the same as those specified for that teacher. Otherwise, when the teacher logs on, they will not see that student in the class. To assign a student to more than one class, list all the classes at the end of the record, with a delimiter between each class Page 7 of 23

8 Sample Files in Microsoft Excel Class File example: Class ID Class Title Begin Date End Date Active Grade Test1 Test2 A B C D E F G H P S Math /01/ /15/ D S English /01/ /15/ Grade 1 Harris 08/01/ /15/2009 Teacher File example: Logon ID Teacher Name Password School Active Account Type Class1 Class2 Class3 A B C D E F G H I DANSCO1 DANIELS SCOTT Harper Valley Middle 1 D S P S HARRIS JUDY Park Elementary 1 T Student File example: Logon ID Name Password School Grade Gender Ethnic B-date Active A B C D E F G H I SMITH KELLY eagles Harper Valley Middle 7 F H 11/1/ JOHNSON JAMAL eagles Harper Valley Middle 7 M B WILLIAMSON TREY Park Elementary 1 M B 1 Student file con t Unique ID SES PD 504 ELL FRL GT MG T1L T1M Other1 Other2 Class1 Class2 Class3 Class4 J K L M N O P Q R S T U V W X Y D S D S P S Page 8 of 23

9 Comments and issues with sample Excel files on page 8: Default values: Several fields in the sample files above are not populated in some records. In some cases (e.g., the SES field in the student file), these fields are optional and do not raise any issues. In other cases (e.g., the password field in the teacher and student files), leaving a field blank is not fatal (because the system will supply a default value), but it will cause the system to generate a warning during the verification step. The warning will indicate that no value was given in the field and that a default value will be assigned during the import process. In the sample files above, the following default values would be assigned to the fields that were left empty: The Status field (column E in the class file example above) for the class Grade 1 Harris has been left blank. Grade 1 Harris will be assigned Active status by the system. The Account Type field (column F in the teacher file example above) for teacher Scott Daniels is blank, so the system will assign Teacher status to him. The Unique ID field (column J in the student file example above) for student Jamal Johnson is blank, so his Unique ID will be the same as the value given for his Student_ID (in this case, ). The Password field (column C in the student file example above) for student Trey Williamson is blank, so he will be assigned the password student. After importing the three sample files shown above, the following associations will be made: The classes English-102 and Math 101 are assigned to Harper Valley Middle School because both classes are associated with teacher Scott Daniels, who is assigned to Harper Valley Middle School. The class Grade 1 Harris is assigned to Park Elementary School, because the class is associated with teacher Judy Harris, who is assigned to Park Elementary School. Teacher Scott Daniels is assigned to two classes, Math 101 and English-102, at Harper Valley Middle School. When he logs on, he will be able to assign tests to, and view results from, all students in both classes, including Kelly Smith and Jamal Johnson. Teacher Judy Harris is assigned to the class Grade 1 Harris at Park Elementary School. When she logs on, she will be able to assign tests to, and view results from, all students in that class, including Trey Williamson Page 9 of 23

10 Step 1: Create Import Files Files of any size: School systems can download their data directly into an ASCII or text file from their student data management system. Precautions: All columns should be left-aligned (not middle- or right-aligned). All columns should be formatted as text before saving the file as a.txt or.csv file. Do not save the column headers in your file. Files smaller than 65,000 records: A spreadsheet program (e.g., Microsoft Excel) can be used to create smaller import files (fewer than 65,000 records). Create three different files, as shown in the samples above. All columns should be left-aligned (not middle- or right-aligned). All columns should be formatted as text before saving the file. Using File/Save As in the file menu, save the file as a.txt file (Tab Delimited) or a.csv file (Comma Delimited). CAUTION: If any fields contain a comma (e.g., Matthews, Sarah) or double quote ( ) this will cause problems in a spreadsheet program and with the import Page 10 of 23

11 Step 2: Upload and Verify the Import Files Once the three files have been created, they must be uploaded into OAS and then verified. This is carried out by the import verification function of OAS. 1. Log on with a RESA, system, or school coordinator ID and password. 2. Select the Administration tab. 3. Select Import Center. 4. Click Create a New Import Job Page 11 of 23

12 Note: You can modify an existing import job by clicking Modify an existing import job. 5. Select the type of file you are importing from the drop down menu: Classes, Teachers, or Students Page 12 of 23

13 6. Select the type of delimiter used in your files (CSV for comma or TXT for tab) from the File Type drop-down menu. 7. Click Browse to search for your file. 8. Locate the file on your computer and double-click it or click once and click Open. The file path is now in the Browse field Page 13 of 23

14 9. If a class file was selected, click Add Class File; if a student file was selected click Add Student File and if a teacher file was selected, click Add Teacher File. Note: Files are immediately checked for errors. If an error exists in a file, notification as to the cause of the error will be given. 10. Select the type of file to import and the file format for the next file. 11. Repeat steps 5 though 10 until all files that you want to import (classes, teachers, and/or students) have been added to your verification job. 12. If a problem exists with any file, a View Log link will be given Page 14 of 23

15 13. Click on View Log for information on the problem with the file. 14. In the column entitled Verified without errors, you will either have the message true (in green), indicating that your files will import without fatal errors, or false (in red), indicating that the files will not import. If you receive a green true message, but the View Log link is active, a warning has been generated. The file will still import successfully, but the system will make some assumptions about your file and insert some default values Page 15 of 23

16 15. If the View Log link is active, click on it. This will allow you to see the error or warning message(s) generated during the verification process. If you receive the False message, click on View Log to determine the type or error. Files will not import if the False message is received. A file can receive the True message, but still have errors. These errors will not prevent the file from importing but may affect how the file imports or how the data is viewed within OAS. Click View Log to determine what errors are in the file and what impact those errors will have. 16. If one or more of the files in your job needs to be revised, click on Back and then click Remove to remove the file(s) from the job. 17. To confirm that you want to remove the files, click Yes Page 16 of 23

17 18. Make the needed changes to the files, and then repeat the verification process. Note: The table below summarizes possible outcomes from the verification process: Verified without error View Log link column entry Status Next action(s) red false active errors found; files will not import view log, remove file from job, revise file green true active non-fatal errors; will import with default values view log, decide whether to revise file green true not active will import schedule import Import Errors As stated above, a file will NOT import if you receive a red false message for that file in the Verified without error column of the verification report. When that occurs, you should click on the View Log link to see which record(s) have what kind of error(s). If a file receives a green true message, it will successfully import. (However, remember that if the View Log link is active when you have a green true, the system has generated a warning about one or more records in the file.) Most of the error messages you may receive when verifying a file are self-explanatory. For example, verifying a student file resulted in this message: 1: Invalid characters in logon ( ), 2: Invalid characters in logon (*), This message indicates that in record 1, the Student_ID field has a space, and in record 2, the same field has an asterisk. Other messages may be a little more cryptic. One of the most common is: 1: School Harper Valley Middle could not be found, You do not have access to add users to school: Harper Valley Middle Page 17 of 23

18 There are actually two errors being indicated in this message (separated by the black comma): First, OAS does not have Harper Valley Middle in its list of locations. It is critical that you use the school identifier exactly as it appears in OAS: if the school is listed as Harper Valley Middle in the location list in OAS, then it must be entered exactly that way in the School_Identifier field when importing. The system is case sensitive and does not accept abbreviations. Second, this message indicates that you do not have administrative privileges for Harper Valley Middle. That is, even if you had entered Harper Valley Middle in the School_Identifier field, and that location existed in the system, you would get the second part of the message if you were logged on as the building administrator of Park Elementary, or the system administrator of a system that does not include Harper Valley Middle. Transferring Students from other systems/schools: When importing a student if there is an exact match on the Student_ID, Unique_Student_Id, and the Student_Name is at least at 90% match then OAS will automatically transfer the student. The 90% check on the Student Name verifies that 90% of the characters in the Student Name match. The order the characters appear in does not matter. Therefore, Ray Mackie, Mackie Ray, or Riay kmace would be found as a 100% match since all the characters are identical. The following three scenarios will generate an error message which will require action by the user. 1. If the Student_Id matches but the Unique_Student_Id doesn't match, you will receive the message: The Student_ID ( PM9) is already in use by the student: Scott Johnson Riverside Elem. School (School) Riverside City Schools (District) RPC RESA (Region). If the student located at Riverside Elem. School should be enrolled at a different location he/she can be transferred using the Transfer Students screen., 2. If the Unique_Student_Id matches but the Student_Id doesn't match, you will receive the message: The UniqueID PM8 is already in use by the student: Scott Johnson Riverside Elem. School (School) Riverside City Schools (District) RPC RESA (Region). If the student located at Riverside Elem. School should be enrolled at a different location he/she can be transferred using the Transfer Students screen., 3. If the Student_Id and the Unique_Student_Id matches but the Student_Name is less than a 90% match, you will receive the following message: The UniqueID PM8 is already in use by the student: Scott Johnson Riverside Elem. School (School) Riverside City Schools (District) RPC RESA (Region). If the student located at Riverside Elem. School should be enrolled at a different location he/she can be transferred using the Transfer Students screen., Step 3: Schedule Import files Once all the files in your job have received the verification of true (in green) in the Verified without errors column, you are ready to schedule your import. Once you schedule your import, you are free to do other work or shut down your computer; the actual integration of your roster data into OAS database takes place on the Riverside Publishing servers (the files in your job were uploaded to the servers for the verification process). However, because the import process is CPU intensive, it would be useful to schedule imports to begin at night, when fewer users are on the system creating and taking tests Page 18 of 23

19 Note: If your import job has more than 1000 entries, the OAS will require you to schedule the import. 1. To schedule the import of your files, click on the Schedule link on the validation report page to set up the date/time for your import. 2. Determine the date/time (including time zone) that you want the import to run. 3. Click OK. Modifying an Import job: Until the scheduled import job is run, it can be modified. 1. Click on the Administration tab. 2. Click Import Center. 3. Click Modify an existing import job Page 19 of 23

20 4. Click on Change Schedule, Edit Job (to add or delete individual files), or Delete Job as needed. 5. If you click Edit Job, you will be able to change the date and/or time for the import. If you click Delete Job, you will be asked to confirm that you want to delete the scheduled job Page 20 of 23

21 Appendix A Ethnicity Codes Ethnicity Codes Code AI/AN A B HA H NH/PI W O TW U Description American Indian and Alaska Native Asian Black or African American Haitian Hispanic or Latino Native Hawaiian and Other Pacific Islander White Other race Two or more races Unknown Page 21 of 23

22 Appendix B Primary Disability Codes Note: A Primary Disability code is required if the Special Ed. Service (SES) is listed as Yes. Primary Disability Code Description 00 None 01 Visual Impairment 02 Deafness or Hard of Hearing 03 Deaf/Blind 04 Specific Learning Disabilities 05 Mild Intellectual Disabilities 06 Traumatic Brain Injury 07 Moderate/Severe/Profound Intellectual Disabilities 08 Autism 09 Orthopedic Impairments 10 Speech-Language Impairments 11 Emotional and Behavioral Disorders 12 Other Health Impairments 13 Multi-handicapped Page 22 of 23

23 Appendix C Import Dos and Don ts Import Dos and Don'ts Incorrect Correct 1. DO: Left-align text and dates especially; left alignment for all Travis Miller Travis Miller fields causes fewer problems in importing 2. DO: Use mm/dd/yyyy date format (month/day/year :00:00 01/02/2005 separated by slashes, with no spaces). DO NOT: include time 3. DO: Bear in mind how Excel treats leading zeros (if you use becomes 400 if formatted in Remains if formatted as text Excel to create your files) excel as number 4. DO NOT: Include leading spaces in fields Travis Miller Travis Miller 5. DO NOT: List First and Last Names in 2 columns Travis Miller Travis Miller 6. DO NOT: Use commas within fields Miller, Travis Miller Travis 7. DO NOT: Leave out columns that you do not populate Deleting unused columns from spreadsheet Keep columns even if blank 8. DO NOT: Put spaces between test IDs test1, test2, test3, test4 test1,test2,test3,test4 9. DO NOT: Put spaces between class IDs Class1, Class2, Class3, Class4 Class1,Class2,Class3,Class Page 23 of 23