Difference between revisions of "Classlist Files"

From WeBWorK_wiki
Jump to navigation Jump to search
m (number fields in table of classlist file fields + use letters also as that is the standard in speadsheet software)
(10 intermediate revisions by 4 users not shown)
Line 1: Line 1:
The '''classlist file''' is the interchange format used by WeBWorK for user data. Classlist files end in <code>.lst</code> and reside in the course <code>templates</code> directory. Classlist files are a convenient way to add a large number of students to a course at once. The "import users from file" function of the '''Classlist Editor''' imports users from classlist files.
+
The '''classlist file''' is the interchange format used by WeBWorK for user data. Classlist files end in <code>.lst</code> and reside in the course <code>templates</code> directory. Classlist files are a convenient way to add a large number of students to a course at once. The "import users from file" function of the '''Classlist Editor''' imports users from classlist files and creates user accounts on the WeBWorK server.
   
 
When you use the '''Classlist Editor''' to export users to a file, a classlist file is created. You can also create classlist files with a spreadsheet such as Excel by saving the file as a "CSV (comma delimited)" file. Classlists can be transferred to and from your workstation using the '''File Manager'''.
 
When you use the '''Classlist Editor''' to export users to a file, a classlist file is created. You can also create classlist files with a spreadsheet such as Excel by saving the file as a "CSV (comma delimited)" file. Classlists can be transferred to and from your workstation using the '''File Manager'''.
Line 15: Line 15:
 
* Empty lines are ignored, as are lines that contain only whitespace.
 
* Empty lines are ignored, as are lines that contain only whitespace.
 
* Whitespace at the beginning and end of fields are stripped on import.
 
* Whitespace at the beginning and end of fields are stripped on import.
  +
* The first 9 fields are mandatory, and the last 2 are optional.
   
 
The order of the fields in a line is the order they appear in the following table, i.e.
 
The order of the fields in a line is the order they appear in the following table, i.e.
'''student_id''', '''last_name''', etc.
 
  +
'''student_id''', '''last_name''', etc. The numbers/letters are given to save on counting, with the letter to help with the standard for spreadsheet column labeling.
   
 
The fields are defined as follows:
 
The fields are defined as follows:
Line 23: Line 24:
 
{| border="1"
 
{| border="1"
 
|-
 
|-
| '''student_id''' || Normally a student's school ID or social security number. It is included in scoring output to help you correlate students with your institution's records. It is also used as an initial password if the '''password''' field is blank. It must either be unique or blank.
+
|1=A|| '''student_id''' || Normally a student's school ID or social security number. It is included in scoring output to help you correlate students with your institution's records. It is also used as an initial password if the '''password''' field is blank. It must either be unique or blank.
 
|-
 
|-
| '''last_name''' || Student's last name. Can be left blank.
+
|2=B|| '''last_name''' || Student's last name. Can be left blank.
 
|-
 
|-
| '''first_name''' || Student's first name. Can be left blank. Use this field for middle name or initial as well if desired.
+
|3=C|| '''first_name''' || Student's first name. Can be left blank. Use this field for middle name or initial as well if desired.
 
|-
 
|-
| '''status''' || An abbreviation denoting the student's status in the course. See below for more information on statuses.
+
|4=D|| '''status''' || An abbreviation denoting the student's status in the course. See below for more information on statuses.
 
|-
 
|-
| '''comment''' || A free-form field for comments. Not used by WeBWorK.
+
|5=E|| '''comment''' || A free-form field for comments.
 
|-
 
|-
| '''section''' || The name of the section the student is enrolled in. Can be left blank.
+
|6=F|| '''section''' || The name of the section the student is enrolled in. Can be left blank.
 
|-
 
|-
| '''recitation''' || The name of the recitation the student is enrolled in. Can be left blank.
+
|7=G|| '''recitation''' || The name of the recitation the student is enrolled in. Can be left blank.
 
|-
 
|-
| '''email_address''' || The student's email address. Used when sending mail to the class and as the sender address when the student sends feedback mail. Can be left blank.
+
|8=H|| '''email_address''' || The student's email address. Used when sending mail to the class and as the sender address when the student sends feedback mail. Can be left blank.
 
|-
 
|-
| '''user_id''' || Also know as the "login name". The identifier that the student uses to log in. This must be unique and can contain only letters, digits, hyphen (-), period (.), and underscore (_). Cannot be left blank.
+
|9=I|| '''user_id''' || Also known as the "login name". The identifier that the student uses to log in. This must be unique and can contain only letters, digits, hyphen (-), period (.), and underscore (_). Cannot be left blank.
 
|-
 
|-
| '''password''' || The ''crypted'' password for the student. If this field is blank, the '''student_id''' field will be used. See below for information on crypting passwords.
+
|10=J|| '''password''' || The ''crypted'' password for the student. If this field is blank, the '''student_id''' field will be used. See below for information on crypting passwords.
 
|-
 
|-
| '''permission''' || The permission level of the student. If this field is blank, the permission will be set to 0 (i.e. student). See below for information on permission levels.
+
|11=K|| '''permission''' || The permission level of the student. If this field is blank, the permission will be set to 0 (i.e. student). See below for information on permission levels.
 
|}
 
|}
   
Line 117: Line 118:
   
 
== Example classlist ==
 
== Example classlist ==
  +
  +
The fields for a classlist file appear in the order
  +
  +
<table border="1" cellspacing="0" cellpadding="5">
  +
<tr>
  +
<td>A = 1</td>
  +
<td>B = 2</td>
  +
<td>C = 3</td>
  +
<td>D = 4</td>
  +
<td>E = 5</td>
  +
<td>F = 6</td>
  +
<td>G = 7</td>
  +
<td>H = 8</td>
  +
<td>I = 9</td>
  +
<td>J = 10</td>
  +
<td>K = 11</td>
  +
</tr>
  +
<tr>
  +
<td><b>student_id</b></td>
  +
<td><b>last_name</b></td>
  +
<td><b>first_name</b></td>
  +
<td><b>status</b></td>
  +
<td><b>comment</b></td>
  +
<td><b>section</b></td>
  +
<td><b>recitation</b></td>
  +
<td><b>email_address</b></td>
  +
<td><b>user_id</b></td>
  +
<td><b>password (crypted)</b></td>
  +
<td><b>permission</b></td>
  +
</tr>
  +
</table>
   
 
In this example the '''password''' and '''permission''' fields are left blank (which is a standard practice for initial classlists). The student's initial password will be set to the '''student_id''' and their permission level will be set to 0 (student).
 
In this example the '''password''' and '''permission''' fields are left blank (which is a standard practice for initial classlists). The student's initial password will be set to the '''student_id''' and their permission level will be set to 0 (student).
Line 125: Line 157:
 
000-00-000d ,PRACTICE4 , ,C , , , , ,practice4
 
000-00-000d ,PRACTICE4 , ,C , , , , ,practice4
 
000-00-000e ,PROBLEM ,RANDOM ,C , ,Gage , , ,practice5
 
000-00-000e ,PROBLEM ,RANDOM ,C , ,Gage , , ,practice5
000-00-000f ,PRACTICE6 , ,DROP , ,Gage , , ,practice6
+
000-00-000f ,PRACTICE6 , ,C , ,Gage , , ,practice6
000-00-000g ,PRACTICE7 , ,DROP , ,Gage , , ,practice7
+
000-00-000g ,PRACTICE7 , ,C , ,Gage , , ,practice7
 
000-00-000h ,PRACTICE8 , ,D , ,Gage , , ,practice8
 
000-00-000h ,PRACTICE8 , ,D , ,Gage , , ,practice8
 
000-00-000i ,PRACTICE9 , ,D , ,Pizer , , ,practice9
 
000-00-000i ,PRACTICE9 , ,D , ,Pizer , , ,practice9
Line 133: Line 165:
 
333-33-3333 ,MOUSSA ,BASEM ,C , ,Pizer , Rec. 1 ,moussa@math.rochester.edu ,moussa
 
333-33-3333 ,MOUSSA ,BASEM ,C , ,Pizer , Rec. 1 ,moussa@math.rochester.edu ,moussa
 
444-44-4444 ,GAGE ,MIKE ,C , ,Gage , Rec. 1 ,gage@math.rochester.edu ,gage
 
444-44-4444 ,GAGE ,MIKE ,C , ,Gage , Rec. 1 ,gage@math.rochester.edu ,gage
010-01-0100 ,CABOTT ,JOHN ,DROP ,9/4/96 ,Gage , Rec. 2 ,jc001f@uhura.cc.rochester.edu ,jc001f
+
010-01-0100 ,CABOTT ,JOHN ,C ,9/4/96 ,Gage , Rec. 2 ,jc001f@uhura.cc.rochester.edu ,jc001f
020-02-0200 ,BONET ,JANE ,DROP ,9/11/96 ,Gage , Rec. 2 ,jb004f@uhura.cc.rochester.edu ,jb004f
+
020-02-0200 ,BONET ,JANE ,C ,9/11/96 ,Gage , Rec. 2 ,jb004f@uhura.cc.rochester.edu ,jb004f
030-03-0300 ,HOYER ,MARK ,DROP , ,Gage , Rec. 2 ,mh010f@uhura.cc.rochester.edu ,mh010f
+
030-03-0300 ,HOYER ,MARK ,C , ,Gage , Rec. 2 ,mh010f@uhura.cc.rochester.edu ,mh010f
040-04-0400 ,RICHARD ,JOAN ,DROP , ,Pizer , Rec. 2 ,jr001f@uhura.cc.rochester.edu ,jr001f
+
040-04-0400 ,RICHARD ,JOAN ,C , ,Pizer , Rec. 2 ,jr001f@uhura.cc.rochester.edu ,jr001f
060-06-0600 ,ROBERTS ,HAL ,DROP , ,Pizer , Rec. 3 ,hr002f@uhura.cc.rochester.edu ,hr002f
+
060-06-0600 ,ROBERTS ,HAL ,C , ,Pizer , Rec. 3 ,hr002f@uhura.cc.rochester.edu ,hr002f
070-07-0700 ,MUELSON ,JOY ,DROP , ,Pizer , Rec. 3 ,jm002e@uhura.cc.rochester.edu ,jm002e
+
070-07-0700 ,MUELSON ,JOY ,C , ,Pizer , Rec. 3 ,jm002e@uhura.cc.rochester.edu ,jm002e
050-05-0500 ,SAMSON ,WENDY ,DROP , ,Pizer , Rec. 3 ,wsamson@frontiernet.net ,050-05-0500
+
050-05-0500 ,SAMSON ,WENDY ,C , ,Pizer , Rec. 3 ,wsamson@frontiernet.net ,050-05-0500
 
080-08-0800 ,THOMAS ,SALLY ,audit , ,Gage , Rec. 4 ,st008c@uhura.cc.rochester.edu ,st008c
 
080-08-0800 ,THOMAS ,SALLY ,audit , ,Gage , Rec. 4 ,st008c@uhura.cc.rochester.edu ,st008c
 
090-09-0900 ,SMITH ,DAVID ,DROP , ,Gage , Rec. 4 ,dsoo9e@uhura.cc.rochester.edu ,ds009e
 
090-09-0900 ,SMITH ,DAVID ,DROP , ,Gage , Rec. 4 ,dsoo9e@uhura.cc.rochester.edu ,ds009e
Line 146: Line 178:
 
== Converting Rochester classlists for use with WeBWorK ==
 
== Converting Rochester classlists for use with WeBWorK ==
   
The perl script <code>webwork2/bin/readURClassList.pl</code> reads a semi-colon delimited file from the University of Rochester registrar and outputs a classlist file having the required format.
+
The perl script [https://github.com/openwebwork/webwork2/blob/master/bin/readURClassList.pl webwork2/bin/readURClassList.pl] reads a semi-colon delimited file from the University of Rochester registrar and outputs a classlist file having the required format.
   
 
[[Category:Instructors]]
 
[[Category:Instructors]]

Revision as of 15:10, 5 May 2021

The classlist file is the interchange format used by WeBWorK for user data. Classlist files end in .lst and reside in the course templates directory. Classlist files are a convenient way to add a large number of students to a course at once. The "import users from file" function of the Classlist Editor imports users from classlist files and creates user accounts on the WeBWorK server.

When you use the Classlist Editor to export users to a file, a classlist file is created. You can also create classlist files with a spreadsheet such as Excel by saving the file as a "CSV (comma delimited)" file. Classlists can be transferred to and from your workstation using the File Manager.

The nomenclature is somewhat confusing. Each WeBWorK course has an internal "classlist", which is stored in the WeBWorK database, not in a classlist file. So there are two things called "classlist" -- a course's internal "classlist", which is used by WeBWorK on a day-to-day basis to keep track of the users who are actually "in" the course, and zero or more "classlist files", which are kept in the templates directory and only used for import/export. (We are thinking of changing the name of the internal classlist to "roster". Thoughts?)

Format of classlist files

The class list file is an ASCII file whose structure structure is as follows:

  • Every line is a separate record with fields separated by a comma (",").
  • No field may contain a comma.
  • There are no header lines in the file.
  • Lines that start with a # sign are ignored.
  • Empty lines are ignored, as are lines that contain only whitespace.
  • Whitespace at the beginning and end of fields are stripped on import.
  • The first 9 fields are mandatory, and the last 2 are optional.

The order of the fields in a line is the order they appear in the following table, i.e. student_id, last_name, etc. The numbers/letters are given to save on counting, with the letter to help with the standard for spreadsheet column labeling.

The fields are defined as follows:

1=A student_id Normally a student's school ID or social security number. It is included in scoring output to help you correlate students with your institution's records. It is also used as an initial password if the password field is blank. It must either be unique or blank.
2=B last_name Student's last name. Can be left blank.
3=C first_name Student's first name. Can be left blank. Use this field for middle name or initial as well if desired.
4=D status An abbreviation denoting the student's status in the course. See below for more information on statuses.
5=E comment A free-form field for comments.
6=F section The name of the section the student is enrolled in. Can be left blank.
7=G recitation The name of the recitation the student is enrolled in. Can be left blank.
8=H email_address The student's email address. Used when sending mail to the class and as the sender address when the student sends feedback mail. Can be left blank.
9=I user_id Also known as the "login name". The identifier that the student uses to log in. This must be unique and can contain only letters, digits, hyphen (-), period (.), and underscore (_). Cannot be left blank.
10=J password The crypted password for the student. If this field is blank, the student_id field will be used. See below for information on crypting passwords.
11=K permission The permission level of the student. If this field is blank, the permission will be set to 0 (i.e. student). See below for information on permission levels.

Status details

The status field in a classlist file contains an abbreviation representing the student's status in the course. By default, the following abbreviation are defined in WeBWorK 2.2 and later:

C, c, current, and enrolled mean that the student is enrolled in the course.

A, a, and audit mean that the student is auditing the course. That is, the student is not included in scoring output.

D, d, drop, and withdraw mean that a student has dropped the course. The student is not allowed to log in, is not assigned homeworks, and is not included in sent email or scoring output.

Statuses are fully customizable in global.conf.

If the status abbreviation field is blank, behavior differs depending on the version of WeBWorK. WeBWorK 2.2.x will give an error when attempting to use the status. To fix this, change the field to C in the Classlist Editor. WeBWorK 2.3.x will set the status to C automatically when importing a classlist file.

Password details

The password field in a classlist file contains the crypted form of the password. crypt is a one-way hashing function that allows passwords to be stored more securely than if the plaintext version was stored. Since WeBWorK only stores crypted passwords, classlists exported by WeBWorK will contain crypted passwords. To make classlist importing compatible with exported classlists, the crypted form is required in imported classlists.

To crypt a password, use the following perl one-liner:

perl -e 'while(1){print"plaintext? ";<>;chomp;print"crypted: ".crypt($_,join"",(".","/",0..9,"A".."Z","a".."z")[rand 64,rand 64])."\n"}'

You can also create a classlist file with plaintext passwords, and then use the following perl one-liner to crypt them:

perl -pe '@a=split",";$a[9]and$a[9]=crypt($a[9],join"",(".","/",0..9,"A".."Z","a".."z")[rand 64,rand 64]);$_=join",",@a' < plaintext.lst > crypted.lst

The original classlist will be read from plaintext.lst, and the converted classlist will be output to crypted.lst.

If the password field is left blank, it will be set to the student_id.

Permission level details

The permission field in a classlist file is a number representing the operations that a user is allowed to perform. Permission levels are defined in global.conf. In WeBWorK 2.3.x and earlier, the default permission levels are:

-5 guest
0 student
2 proctor
5 ta
10 professor

In WeBWorK 2.4.0 and later they are:

-5 guest
0 student
2 login_proctor
3 grade_proctor
5 ta
10 professor

Take a look at the %permissionLevels hash in global.conf for details of the operations that can be performed at each permission level.

The proctor, login_proctor, and grade_proctor permission levels are used in gateway testing. For more information about proctors and gateway tests, see Gateway Tests and Quizzes.

If the permission field is left blank, it will be set to 0. (This is also configurable in global.conf.)

Example classlist

The fields for a classlist file appear in the order

A = 1 B = 2 C = 3 D = 4 E = 5 F = 6 G = 7 H = 8 I = 9 J = 10 K = 11
student_id last_name first_name status comment section recitation email_address user_id password (crypted) permission

In this example the password and permission fields are left blank (which is a standard practice for initial classlists). The student's initial password will be set to the student_id and their permission level will be set to 0 (student).

000-00-000a  ,PRACTICE1  ,        ,C      ,         ,Pizer  ,        ,                                ,practice1    
000-00-000b  ,PRACTICE2  ,        ,C      ,         ,Pizer  ,        ,                                ,practice2    
000-00-000c  ,PRACTICE3  ,        ,C      ,         ,Pizer  ,        ,                                ,practice3    
000-00-000d  ,PRACTICE4  ,        ,C      ,         ,       ,        ,                                ,practice4    
000-00-000e  ,PROBLEM    ,RANDOM  ,C      ,         ,Gage   ,        ,                                ,practice5    
000-00-000f  ,PRACTICE6  ,        ,C   ,         ,Gage   ,        ,                                ,practice6    
000-00-000g  ,PRACTICE7  ,        ,C   ,         ,Gage   ,        ,                                ,practice7    
000-00-000h  ,PRACTICE8  ,        ,D      ,         ,Gage   ,        ,                                ,practice8    
000-00-000i  ,PRACTICE9  ,        ,D      ,         ,Pizer  ,        ,                                ,practice9    
111-11-1111  ,PIZER      ,ARNOLD  ,C      ,         ,Pizer  , Rec. 1 ,apizer@math.rochester.edu      ,apizer       
222-22-2222  ,DOUGLASS   ,SCOTT   ,C      ,         ,Pizer  , Rec. 1  ,douglass@math.rochester.edu    ,douglass     
333-33-3333  ,MOUSSA     ,BASEM   ,C      ,         ,Pizer  , Rec. 1 ,moussa@math.rochester.edu      ,moussa       
444-44-4444  ,GAGE       ,MIKE    ,C      ,         ,Gage   , Rec. 1 ,gage@math.rochester.edu        ,gage         
010-01-0100  ,CABOTT     ,JOHN    ,C   ,9/4/96   ,Gage   , Rec. 2 ,jc001f@uhura.cc.rochester.edu  ,jc001f       
020-02-0200  ,BONET      ,JANE    ,C   ,9/11/96  ,Gage   , Rec. 2 ,jb004f@uhura.cc.rochester.edu  ,jb004f      
030-03-0300 ,HOYER ,MARK ,C , ,Gage , Rec. 2 ,mh010f@uhura.cc.rochester.edu ,mh010f
040-04-0400 ,RICHARD ,JOAN ,C , ,Pizer , Rec. 2 ,jr001f@uhura.cc.rochester.edu ,jr001f
060-06-0600 ,ROBERTS ,HAL ,C , ,Pizer , Rec. 3 ,hr002f@uhura.cc.rochester.edu ,hr002f
070-07-0700 ,MUELSON ,JOY ,C , ,Pizer , Rec. 3 ,jm002e@uhura.cc.rochester.edu ,jm002e
050-05-0500 ,SAMSON ,WENDY ,C , ,Pizer , Rec. 3 ,wsamson@frontiernet.net ,050-05-0500
080-08-0800 ,THOMAS ,SALLY ,audit , ,Gage , Rec. 4 ,st008c@uhura.cc.rochester.edu ,st008c
090-09-0900 ,SMITH ,DAVID ,DROP , ,Gage , Rec. 4 ,dsoo9e@uhura.cc.rochester.edu ,ds009e
009-09-0009 ,SMITH ,JUDY ,C , ,Gage , Rec. 4 ,js005e@uhura.cc.rochester.edu ,js005e

Converting Rochester classlists for use with WeBWorK

The perl script webwork2/bin/readURClassList.pl reads a semi-colon delimited file from the University of Rochester registrar and outputs a classlist file having the required format.