Difference between revisions of "Classlist Files"
m (number fields in table of classlist file fields + use letters also as that is the standard in speadsheet software) |
(Remove Rochester-specific info) |
||
| (8 intermediate revisions by 3 users not shown) | |||
| Line 7: | Line 7: | ||
== Format of classlist files == |
== Format of classlist files == |
||
| − | The class list file is |
+ | The class list file is a text file whose structure is as follows: |
* Every line is a separate record with fields separated by a comma (","). |
* Every line is a separate record with fields separated by a comma (","). |
||
| 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. |
||
| Line 24: | Line 23: | ||
{| border="1" |
{| border="1" |
||
|- |
|- |
||
| − | |1=A|| '''student_id''' || Normally a student's school ID |
+ | |1=A|| '''student_id''' || Normally a student's school ID. 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. |
|2=B|| '''last_name''' || Student's last name. Can be left blank. |
||
| Line 30: | Line 29: | ||
|3=C|| '''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. |
||
|- |
|- |
||
| − | |4=D|| '''status''' || An abbreviation denoting the student's status in the course. See below for more information on |
+ | |4=D|| '''status''' || An abbreviation denoting the student's status in the course. See below for more information on allowed values. |
|- |
|- |
||
| − | |5=E|| '''comment''' || A free-form field for comments. |
+ | |5=E|| '''comment''' || A free-form field for comments. Will be stored and displayed in the Classlist Editor. |
|- |
|- |
||
|6=F|| '''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. |
||
| Line 49: | Line 48: | ||
== Status details == |
== 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. |
+ | 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.18 and later: |
<code>C</code>, <code>c</code>, <code>current</code>, and <code>enrolled</code> mean that the student is enrolled in the course. |
<code>C</code>, <code>c</code>, <code>current</code>, and <code>enrolled</code> mean that the student is enrolled in the course. |
||
<code>A</code>, <code>a</code>, and <code>audit</code> mean that the student is auditing the course. That is, the student is not included in scoring output. |
<code>A</code>, <code>a</code>, and <code>audit</code> mean that the student is auditing the course. That is, the student is not included in scoring output. |
||
| + | |||
| + | <code>O</code>, <code>o</code>, and <code>observer</code> mean that the user is active, but should not be graded in the course. This should be used for all users other than students (e.g. instructors, TAs, librarians, etc.). These users will not be included in scoring output, but can still have access to all aspects of the course (depending on their permission level). |
||
<code>D</code>, <code>d</code>, <code>drop</code>, and <code>withdraw</code> 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. |
<code>D</code>, <code>d</code>, <code>drop</code>, and <code>withdraw</code> 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 <code>global.conf</code>. |
||
| + | <code>P</code>, <code>p</code>, and <code>proctor</code> |
||
| − | 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 <code>C</code> in the '''Classlist Editor'''. WeBWorK 2.3.x will set the status to <code>C</code> automatically when importing a classlist file. |
||
| + | Statuses are fully customizable in <code>localOverrides.conf</code>. |
||
| + | |||
| + | If the status abbreviation field is blank, WeBWorK will set the status to <code>C</code> automatically when importing a classlist file. |
||
== Password details == |
== Password details == |
||
| − | The password field in a classlist file contains the ''crypted'' form of the password. <code>crypt</code> 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. |
||
| + | The password field in a classlist file contains the ''crypted'' form of the password. |
||
| + | |||
| + | If the password field in a classlist file is left blank, it will be set to the student_id. |
||
| + | |||
| + | <code>crypt</code> 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. |
||
| + | |||
| + | '''WARNING''': The lines below were apparently valid until WeBWorK 2.9. From WeBWorK 2.10 and on - the manner in which passwords are encrypted was changed (https://github.com/openwebwork/webwork2/commit/5226b4d9c4644de47cc549429eb627517857707b) and the code below will '''not''' create valid passwords. |
||
| − | To crypt a password, use the following perl one-liner: |
+ | '''OUTDATED''': To crypt a password, use the following perl one-liner: |
<code>perl -e 'while(1){print"plaintext? ";<>;chomp;print"crypted: ".crypt($_,join"",(".","/",0..9,"A".."Z","a".."z")[rand 64,rand 64])."\n"}'</code> |
<code>perl -e 'while(1){print"plaintext? ";<>;chomp;print"crypted: ".crypt($_,join"",(".","/",0..9,"A".."Z","a".."z")[rand 64,rand 64])."\n"}'</code> |
||
| − | You can also create a classlist file with plaintext passwords, and then use the following perl one-liner to crypt them: |
+ | '''OUTDATED''': You can also create a classlist file with plaintext passwords, and then use the following perl one-liner to crypt them: |
<code>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</code> |
<code>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</code> |
||
| Line 75: | Line 84: | ||
The original classlist will be read from <code>plaintext.lst</code>, and the converted classlist will be output to <code>crypted.lst</code>. |
The original classlist will be read from <code>plaintext.lst</code>, and the converted classlist will be output to <code>crypted.lst</code>. |
||
| − | If the password field is left blank, it will be set to the student_id. |
||
| + | '''New script''': A new script to encrypt classlist files which should work with current versions is available at https://raw.githubusercontent.com/openwebwork/webwork2/82052465024ba9ea27dba62cc604f92294501105/bin/crypt_passwords_in_classlist.pl and was submitted to the project codebase in |
||
| + | https://github.com/openwebwork/webwork2/pull/1461 . The script and was written to be usable without needing to install WeBWorK, and should work anywhere Perl in installed. |
||
== Permission level details == |
== Permission level details == |
||
| − | The permission field in a classlist file is a number representing the operations that a user is allowed to perform. |
+ | The permission field in a classlist file is a number representing the operations that a user is allowed to perform. The default permission levels are defined in <code>defaults.config</code>. |
| − | |||
| − | {| border="1" |
||
| − | |- |
||
| − | | -5 || guest |
||
| − | |- |
||
| − | | 0 || student |
||
| − | |- |
||
| − | | 2 || proctor |
||
| − | |- |
||
| − | | 5 || ta |
||
| − | |- |
||
| − | | 10 || professor |
||
| − | |} |
||
| − | |||
In WeBWorK 2.4.0 and later they are: |
In WeBWorK 2.4.0 and later they are: |
||
| Line 95: | Line 105: | ||
|- |
|- |
||
| 10 || professor |
| 10 || professor |
||
| + | |- |
||
| + | | 20 || admin |
||
|} |
|} |
||
| − | Take a look at the <code>%permissionLevels</code> hash in <code> |
+ | Take a look at the <code>%permissionLevels</code> hash in <code>defaults.config</code> for details of the operations that can be performed at each permission level. Both the list of roles and the associated permissions can be customized by editing the <code>localOverrides.conf</code> file. |
| − | The |
+ | The login_proctor, and grade_proctor permission levels are used in proctored tests. For more information about proctors and tests, see [[Gateway Tests and Quizzes]]. |
If the permission field is left blank, it will be set to <code>0</code>. (This is also configurable in <code>global.conf</code>.) |
If the permission field is left blank, it will be set to <code>0</code>. (This is also configurable in <code>global.conf</code>.) |
||
| Line 161: | Line 173: | ||
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 |
||
009-09-0009 ,SMITH ,JUDY ,C , ,Gage , Rec. 4 ,js005e@uhura.cc.rochester.edu ,js005e</pre> |
009-09-0009 ,SMITH ,JUDY ,C , ,Gage , Rec. 4 ,js005e@uhura.cc.rochester.edu ,js005e</pre> |
||
| − | |||
| − | == Converting Rochester classlists for use with WeBWorK == |
||
| − | |||
| − | 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]] |
||
| + | [[Category:Classlists]] |
||
Latest revision as of 11:10, 12 July 2023
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?)
Contents
Format of classlist files
The class list file is a text file whose 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 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. 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 allowed values. |
| 5=E | comment | A free-form field for comments. Will be stored and displayed in the Classlist Editor. |
| 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.18 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.
O, o, and observer mean that the user is active, but should not be graded in the course. This should be used for all users other than students (e.g. instructors, TAs, librarians, etc.). These users will not be included in scoring output, but can still have access to all aspects of the course (depending on their permission level).
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.
P, p, and proctor
Statuses are fully customizable in localOverrides.conf.
If the status abbreviation field is blank, WeBWorK 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.
If the password field in a classlist file is left blank, it will be set to the student_id.
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.
WARNING: The lines below were apparently valid until WeBWorK 2.9. From WeBWorK 2.10 and on - the manner in which passwords are encrypted was changed (https://github.com/openwebwork/webwork2/commit/5226b4d9c4644de47cc549429eb627517857707b) and the code below will not create valid passwords.
OUTDATED: 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"}'
OUTDATED: 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.
New script: A new script to encrypt classlist files which should work with current versions is available at https://raw.githubusercontent.com/openwebwork/webwork2/82052465024ba9ea27dba62cc604f92294501105/bin/crypt_passwords_in_classlist.pl and was submitted to the project codebase in https://github.com/openwebwork/webwork2/pull/1461 . The script and was written to be usable without needing to install WeBWorK, and should work anywhere Perl in installed.
Permission level details
The permission field in a classlist file is a number representing the operations that a user is allowed to perform. The default permission levels are defined in defaults.config.
In WeBWorK 2.4.0 and later they are:
| -5 | guest |
| 0 | student |
| 2 | login_proctor |
| 3 | grade_proctor |
| 5 | ta |
| 10 | professor |
| 20 | admin |
Take a look at the %permissionLevels hash in defaults.config for details of the operations that can be performed at each permission level. Both the list of roles and the associated permissions can be customized by editing the localOverrides.conf file.
The login_proctor, and grade_proctor permission levels are used in proctored tests. For more information about proctors and 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
