Course Administration

This document details how to create and delete courses, import and export course databases, and perform other administrative functions.

WeBWorK provides both command-line and web access to course administration tools.

The command-line utilities

The command-line utilities, addcourse, deletecourse, and wwdb, provide access to administrative functions. To use them, you must have write access to the courses directory and any course directories you wish to modify. You must also set the WEBWORK_ROOT environment variable and you may add the WeBWorK bin directory to your path. See the installation manual for more information.

These utilities are useful for batch processing. For day-to-day administration, the web interface is more user friendly.

Permissions issues

In order to be useful, the web server running WeBWorK must have read and write access to all course files. When you create a course using the command-line tools, there is potential for those newly-created course files to be non-writeable by the web server.

The easiest way to avoid permissions problems is to execute the command-line utilites as the same user the web server runs as. This is easily accomplised using the su or sudo commands. Assuming the web server runs as: www-data:

sudo -u www-data addcourse ...

Or, if sudo is not available:

su www-data -c 'addcourse ...'

If you do not have access to su or sudo, you can run these commands as yourself, as long as you have access to the course files. One way to do this is to make yourself a member of the web server's group. This gives you access to all the same files the web server has access to. You could instead create a new group called wwdata, containing both the WeBWorK administrators and the web server. See the installation manual for more information.

If you chose this method, switch to the web server's group (or the wwdata group) and change your file creation mask to allow group writeability before running the command-line utilities:

newgrp www-data
umask 2
wwdb course1 export ...
addcourse course2 ...
wwdb course2 import ...
...
exit

Creating courses on the command-line

The addcourse utility is used to create courses.

The simplest form of the command is:

addcourse COURSEID

However, you'll likely need to provide additional options.

The --db-layout=LAYOUT option allows you to override the database layout set in global.conf.

The --users=FILE option allows you to specify a classlist file from which users will be imported. The --professors=USERID,[USERID...] option allows you to denote one or more of the users in the file specified as professors. You should always make sure that at least one user is listed as a professor. Otherwise, you will not be able to edit your course.

The --templates-from=COURSEID option causes the contents of the templates directory of another course to be copied to the new course. You can set up a "template" course with the problem source files, macro files, and mail merge forms desired and then use this feature to copy them to each new course you create. Please note that only the templates directory are copied, not the classlist or problem sets.

Deleting courses on the command-line

The delcourse utility is used to delete courses.

The simplest form of the command is:

delcourse COURSEID

Be very careful with this command: the course will be deleted immediately -- no questions asked!

Exporting a database on the command-line

The wwdb utility is used to export course databases to an XML file.

The simplest export command is:

wwdb COURSEID export FILE

where COURSEID is the name of the course to export from, and FILE is the file to export to. If FILE is =-=, the data will be printed on the standard output stream.

You can additionally specify table names after FILE. If you do, only the data in those tables will be exported. For example, to export all user, password, and permission data from the course mth143:

wwdb mth143 export mth143-classlist.xml user password permission

Importing a database on the command-line

The wwdb utility is used to export course databases to an XML file.

The simplest import command is:

wwdb COURSEID import FILE

where COURSEID is the name of the course to import to, and FILE is the file to import from. If FILE is =-=, the data will be read from the standard input stream.

You can additionally specify table names after FILE. If you do, only the data for those tables will be imported. For example, to import all abstract set data to the course calc1:

wwdb calc1 import calc1-sets.xml set problem

The -f switch allows wwdb to overwrite records already in the database with the versions in the XML file. If this switch is not given, duplicate records are skipped.

Exporting and importing problem sets from the command-line

Together, the two wwdb modes provide a simple method for exporting all the homework sets in a course, and importing these sets into a new course. This is useful, for example, if you are creating a new course shell based on the sets in an existing course.

1. Export the homework set data from the existing course using wwdb OLDCOURSEID export FILE set problem
2. Import the homework set data into the new course using wwdb NEWCOURSEID import FILE set problem

In the commands above, the table "set" includes a list of all assignments in the old course, together with metadata about those assignments such as start date, end date, etc. The table "problem" lists, for each set, the problems that should be placed into that set. Note that if any homework problems were modified or written by the instructor of the old course, you will need to copy those .pg files into the new course, or you will see an error stating that the problem was not found.

The web interface

The web interface provides a user-friendly way to adminstrate courses. It also allows people who do not have accounts on the WeBWorK server to administrate. Because all actions are performed by the web server, there is no concern about permissions problems as there is with the command-line utilities.

The 'admin' course

Access to the web-based course administration tools is controlled by a special course named admin. The instructors in this course are permitted to perform administrative functions. If the admin course exists, a Course Administration link will appear on the WeBWorK home page (usually http://your.server.edu/webwork2).

Create the admin course using the command-line addcourse tool. The file adminClasslist.lst contains a single user, admin, with password admin.

If you are using WeBWorK 2.1 or later, we suggest you use the sql_single database layout (if you are using WeBWorK 2.2 or later, only sql_single is supported):

cd /opt/webwork2/courses
addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin

After you create the course, visit the WeBWorK home page on your server, usually located at http://your.server.edu/webwork2. Click on the Course Administration link. You can also access the admin course directly, at http://your.server.edu/webwork2/admin.

To log in, enter admin for your username and admin for your password. Once logged into the admin course, the first thing you should do is change the admin password. You can do this by clicking the Password/Email link on the links menu. After you do this, you may add accounts for any additional people who should have administrative access using the Class List Editor link.

Creating a course via the web

To create a course, visit the Course Administration page and select Add Course. Some notes about the creation process:

The Course Title and Institution fields are used to write an entry to the hosted_courses log, which is intended to help you keep track of created courses.

Add WeBWorK administrators to new course copies the users of the admin course to the new course. This can be useful if you need to later go in and modify something for the course's professor.

Note that the preferred database layout in WeBWorK 2.1 is sql_single. If you are running WeBWorK 2.0, select sql instead -- you will be able to convert the course to use sql_single when you upgrade to 2.1. Only use gdbm if compatibility with WeBWorK 1 is necessary.

Deleting a course via the web

To delete a course, visit the Course Administration page and select Delete Course. In the list of courses, each course's database layout is noted.

If the course you want to delete uses the sql database layout, you must enter an SQL Admin Username and SQL Admin Password for your SQL server. You may also have to specify the SQL Server Host or the SQL Server Port if your SQL server is running on a remote machine.

You will be asked to confirm deletion of the course before it occurs.

Exporting a database via the web

To export a course database, visit the Course Administration page and select Export Database. Select a course from the Course Name list. If you wish to only export a subset of the data in the database, you can deselect one or more of the tables in the Tables to Export list.

When you click Export Database, the database file will be sent to your browser.

Importing a database via the web

To import a course database, visit the Course Administration page and select Import Database. Select a file to upload in the Database XML File and select a course from the Course Name list. If you wish to only import a subset of the data in the XML file, you can deselect one or more of the tables in the Tables to Export list.

The Conflicts option allows you to chose what happens if a duplicate record (a record with the same ID) already exists in the course database. If you select Skip duplicate records, the version in the database will be preserved. If you select Replace duplicate records, the version in the XML file will replace the version in the database.

When you click Import Database, the database file will be uploaded from your computer and imported.

Other administrative functions

Converting an existing course from 'sql' to 'sql_single'

The sql_single database layout, new in WeBWorK 2.1, stores course data for multiple courses in a single SQL database. This makes for more efficient database access and avoids exhausing SQL connection handles.

The command-line utility sql2sql_single can convert existing courses from the sql database layout to the sql_single database layout. As with the other command-line utilities, you must set the WEBWORK_ROOT environment variable and you may add the WeBWorK bin directory to your path.

To convert a course, the existing course database must be on the same database server as the database used by the sql_single layout. It requires the username and password of an administrative account on the SQL server.

To convert a course database:

sql2sql_single course_name webwork root SeCrEt

Where course_name is the name of an sql course to convert, webwork is the name of the sql_single database, and root and SeCrEt are respecively the username and password of the SQL admin account.

After running the command, you will need to modify the course's course.conf to set the database layout to sql_single. sql2sql_single will give you the path to the course's course.conf file, but becasue the format of that file is not altogether predictable, you must make the change yourself.

In course.conf, there should be lines like:

$dbLayoutName = 'sql';
*dbLayout = $dbLayouts{$dbLayoutName};

You must change these lines to:

$dbLayoutName = 'sql_single';
*dbLayout = $dbLayouts{$dbLayoutName};

The following sed(1) command may be of use:

sed 's/sql/sql_single/' < course.conf > course.conf.new
mv course.conf course.conf.old
mv course.conf.new course.conf

Adding indexing to an existing course

SQL servers have the ability to maintain indices, to speed access to data. Courses created with the sql_single database layout have indices set up automatically, but if you convert a course from the sql to the sql_single layout, you have to add indexing yourself.

The wwaddindexing utility adds indices to sql_single courses. As with the other command-line utilities, you must set the WEBWORK_ROOT environment variable and you may add the WeBWorK bin directory to your path.

This utility is not supported in WeBWorK 2.3 or later.

To add indices:

wwaddindexing course_name