Back to Chapters


Welcome to the ATutor Administrator Documentation! This documentation is intended for those who manage ATutor systems. Also see the Instructor Documentation for more about creating and managing courses.


This section describes the requirements and important considerations needed for running ATutor. It also details the steps involved in installing and upgrading an installation.

Requirements & Recommendations

The first step when installing or upgrading ATutor is to check if the minimum requirements are met. The following describes those checks.

File Integrity

The Case Sensitivity check verifies that file names were not converted to lower-case during the extraction process. This is not an issue on case-insensitive operating systems like MS Windows, but is an issue on case-sensative ones like Linux.

Web Server

The ATutor development and testing processes are done primarily on Apache 1.3 and Apache 2 (using pre-forking), and as such we strongly recommend them for production environments. ATutor has been successfully installed on other web servers, including, Zeus, lighttpd, Abyss, Zazou Mini Web Server, Microsoft IIS, and Jana-Server.

The web server can be configured with SSL for added security or to use a non-standard port and ATutor will function without modification.


ATutor is written in the PHP language. The PHP configuration file contains many configuration settings that can be changed. The following are the minimum requirements needed to install and use ATutor.

PHP 5.0.2+
Version 5.2.0 or higher is recommended.
Zlib support must be enabled in PHP; It is used for compressing and uncompressing ZIP files.
MySQL support must be enabled in PHP.
MBstring support must be compiled into PHP to support UTF-8 lamguage characters.
curl (optional)
Curl support must be compiled into PHP for ATutor Social (Networking) .
safe_mode = Off
safe_mode must be disabled in PHP. ATutor cannot function with the restrictions enforced when safe_mode is enabled.
file_uploads = On
File uploads support must be enabled in PHP.
upload_max_filesize >= 2 MB
This option specifies the maximum size of files that can be uploaded to ATutor.
post_max_size >= 8 MB
This value must be larger than the upload_max_filesize.
Sessions support must be enabled in PHP.
session.auto_start = 0
session.auto_start must be disabled in PHP.
session.save_path must be set to a real path that can store session data.
. in include_path
. must be in the list of paths in the include_path option.

Additionally, the following php.ini configuration settings are recommended:

display_errors          = Off
arg_separator.input     = ";&"
register_globals        = Off
magic_quotes_gpc        = Off
magic_quotes_runtime    = Off
allow_url_fopen         = On
allow_url_include       = Off
register_argc_argv      = Off
zlib.output_compression = On
session.use_trans_sid   = 0


Currently ATutor only supports the MySQL database. MySQL 4.1.10 or higher is required.

A database user account with database creation privileges is required if your database does not already exist. That same user will then need table creation privileges for the chosen database. See the MySQL chapter How the Privilege System Works [] for additional information.

Web Browser

ATutor makes use of many new HTML features that are only supported in recent web browsers. Though ATutor is designed to function effectively in older browsers we strongly recommend using the latest version of your favorite browser. We recommend FireFox [] for either Windows, *nix or Mac OS X.

New Installation

Please review the requirements section before attempting to install ATutor. The latest version of ATutor can always be found on the downloads [] page.

Windows Considerations

To extract the ATutor .tar.gz archive you will need an application like WinZip [] or WinRar [].

Unix Considerations

To extract the ATutor .tar.gz archive, use the command tar -zxvf ATutor-version_number.tar.gz, which will create a directory called ATutor in your current working directory.

Extracting the files on a Windows machine and then uploading them via FTP is not recommended, as it may not preserve the case-sensitive file names.

Installing on a Unix machine requires some knowledge of file and directory permissions. You will be required to create a content directory and set permissions for that directory and for the include/ file, so that the web server can write to them. The installation will not be successful if the permissions are not correctly set on that file and directory.

Changing Unix file permissions from the shell prompt: chmod a+rw filename or chmod a+rwx directoryname.

Changing Unix file permissions from an FTP client: Many FTP clients allow you to change a file's permissions. The option may be labled as "Unix Permissions", "CHMOD", or simply as "Properties" or "Attributes" and will display a window with Read, Write, and Execute checkboxes for Owner, Group, and World; checking the appropriate boxes will change that file's permissions. In our case we need the include/ to be Readable and Writeable by World, and the content directory to be Readable, Writeable, and Executable by World.

Installation Procedure

Extract the downloaded archive using the method specified for your system (either Windows or Unix). Open a web browser and enter the address to your new ATutor installation,, then follow the step-by-step instructions:

  1. Terms of Use
    The usage of ATutor is restricted by the GNU General Public License (GPL). Your agreement with the GPL is required if you wish to use ATutor. See the Licensing section [] for more details.
  2. Database
    Enter the required details needed to connect to your MySQL database. The optional Table Prefix (e.g. "AT_") allows ATutor to share an existing database with other applications and tables. The ATutor installation script will attempt to create the database specified, if it does not already exist. This requires that your MySQL user account has permission to create databases and permission to create tables. If this step fails, contact your system administrator to have your MySQL account upgraded to allow creation of new databases, or ask your administrator to create the database for you.
  3. Accounts & Preferences
    The Super Administrator account is used for managing your ATutor installation. The Super Administrator can also create additional Administrators each with their own privileges and roles once ATutor is installed. The personal account can be used to enroll in or create courses.
  4. Content Directory
    Create a content directory, preferably outside your web server's document directory for added security, and set permissions as described above. On a Unix machine you will need to manually change the permissions on the listed files and directories in this step. No action is usually required on a Windows server, though in some circumstances Windows users may need to adjust the properties of the specified files and directories to make them writable. Copy the path of the created directory into the text box provided. Ensure that there are no shortcuts or symbolic links in the path.
  5. Save configuration
    Before reaching the final step the include/ file needs to be writable, otherwise an error will appear. Follow the instructions on the screen if the file permissions need to be changed. If the file does not exist in the include/ directory, then you will need to create an empty text file with the filename
  6. Anonymous Usage Collection
    To assist the development team in serving the ATutor community, you can anonymously submit basic system information to the server.
  7. Done!
    ATutor installation has been successful and you may now log-in with your personal account or the administrator account created in Step 3.

Upgrading an Existing ATutor Installation

Considerations Before Upgrading

Note that Release Candidates (RC) and nightly build upgrades are not supported using this method and that depending on the size of the old courses, some steps of the upgrade may require considerable time to complete (in particular steps 2 and 6).

Be sure that Language Packs [] you have installed on your old version of ATutor are available for the new version, or be prepared to translate the missing language. The old language will be removed during upgrade. If they are not available, you might volunteer to help finish any remaining language that needs to be translated for these languages. See the Translator Documentation [] for more details. If you have made custom changes the the language, you may wish to export the customized language using the language manager.

If you have Custom Themes [] created, export those before upgrading, then import them back into the new version of ATutor after the upgrade is complete (you may need to make a few adjustment after reimporting the custom themes if there have been changes in the ATutor)

If you have Extra Modules installed, be sure the modules are either compatible, or are available for the new version. Modules must be reinstalled after an upgrade.

Also be sure the System Requirements are still met.

Before upgrading, rename your old ATutor directory. Download the latest version of ATutor and extract the new version into the same directory that the old one was in. Example: If the old ATutor installation was in /htdocs/ATutor and renamed to /htdocs/ATutor_old, then the new ATutor installation should be in /htdocs/ATutor, such that both the old and new installations are at the same directory level. On Windows you may use WinZip or WinRar, while on Unix use the command tar -zxvf ATutor-version_number.tar.gz. Once extracted, an ATutor directory will be created alongside your old ATutor directory. Open a web browser and enter the address to your new installation,, then follow the step-by-step instructions.

Steps for Upgrading ATutor

Important: It is highly recommended that you backup your old ATutor database before attempting an upgrade.

The following eight steps describe the upgrade process as they are presented by the ATutor installer:

  1. Locate Old Version
    Specify the directory name of the old ATutor installation you wish to upgrade (e.g. ATutor_old). The new and old ATutor directories must be at the same directory level.
  2. UTF-8 Conversion (1.6+)
    If you have not already, you are strongly advised to backup you database before completing this step. If ATutor is being upgraded from a previous version that was not using UTF-8 language packs, options will be provided to convert the database to UTF-8 all-at-once, used for single language ATutor installations, or to convert on a course-by-course basis, used if courses in different languages are present on the system. If the system is already setup with UTF-8, you'll skip this step. NOTE: This step can take a very long time for installations with many courses
  3. Database
    The upgrade will use the old version's settings to connect to the database and then update the old database tables with any changes to bring them up to date with the new version.
  4. Preferences
    In some cases, the newer version will introduce new configuration options and preferences that have to be set or confirmed. Review the Preferences and modify them if necessary.
  5. Directories
    Create a content directory , preferably outside your web server's document directory for added security, and set permissions to make the content directory writable (chmod a+rwx content). On a Unix machine you will need to manually change the permissions on the content directory during this step, if you are using a directory other than the one used in the version of ATutor being upgraded. No action is usually required on a Windows server, though in some circumstances Windows users may need to adjust the properties of the specified files and directories to make them writable. Copy the path of the directory into the text box provided. Ensure there are no shortcuts (Windows), or symbolic links (Unix) are contained in the path. The path can be the same as that to the content directory use in the version being upgraded from if the directory is outside the old ATutor installation.
  6. Save configuration
    Before reaching the final step the include/ file needs to be writable, otherwise an error will appear. Follow the instructions on the screen if the file permissions need to be changed (chmod a+rwx include/ Once your upgrade is complete and you have confirmed it was successfuly, you should set the configuration file back to read only to secure it (chmod a-w include/
  7. Content Files
    All the old course content files and chat messages will be copied over to the new installation. Depending on the size of your old installation, this process may take a few seconds to several minutes or more to complete.
  8. Submit Usage Information
    To assist the development team in serving the ATutor community, submit some basic information collected about the system you are running. All information is private. Though you are encouraged to list the location of your ATutor installation, you may remain anonymous by choosing not to submit the URL to your ATutor server along with the system information during this step.
  9. Done!
    ATutor upgrade has been successful and you may now log-in with your personal account or your administrator account.

Administrator Home

The Administrator Home page is the first screen after logging in. It displays a linked list of the administrative tools, shows new and pending Instructor Requests, provides the ability to check for the latest version of ATutor by connecting to the website, and basic installation statistics and information.

My Account

My Account allows the Administrator to change his/her account password, name, or email address.

System Preferences

Site Name
The name of the course server's website. This name will appear at the top of all the public pages, in the web browser's title bar, and as the From name when sending non-personal emails.
Home URL
This will be the web address for the 'Home' link in the public area. Leave empty to remove this link.
Default Language
The default language to use if the client's browser settings cannot be detected. Must be one of the languages already installed. See the Languages section on installing and managing existing languages.
Contact Email
The reply address used for emails sent for instructor requests and other system emails.
Time Zone Offset
Add or subtract hours from the times and dates displayed in ATutor, so they match the local time for the ATutor installation. Valid values range from -12 to 12. The positive sign is not required when adding hours. The minus sign is required when subtracting hours. Individual users may also modify their own Time Zone Offset setting, if their local time differs from that of the ATutor installation.
Maximum File Size
Maximum allowable file size in Bytes that can be uploaded to the course's File Manager. This does not override the value set for upload_max_filesize in php.ini.
Maximum Course Size
Total maximum allowable course size in Bytes. This is the total amount of space a course's File Manager can use.
Maximum Course Float
How much a course can be over its Maximum Course Size limit while still allowing a file to upload or import. Makes the course limit actually be Max Course Size + Max Course Float. When Max Course Float is reached, no more uploads will be allowed for that course until files are deleted and the course's space usage falls under the Maximum Course Size.
Maximum login attempts
The amount of times the user can attempt logging in before the system freeze the account for an hour. Enter 0 for infinite times.
Display Name Format
The Display Name Format option controls how non-administrator users' names appear. This option is available in ATutor 1.5.4+.
Authenticate Against A Master Student List
Whether or not to enable Master Student List authentication. If enabled, only new accounts that validate against the master list will be created. See the Master Student List section for additional details on using this feature.
Allow Self-Registration
If enabled, users can self-register. Disable to remove registration functions
Allow Instructors to enroll users from the system registration list.
If enabled, instructors are allowed to enroll users from the system registration list.
Allow the use of CAPTCHA
This requires the GD library installed (FreeType library is recommanded to have for better effect). If enabled, users will be asked to enter an additional field for the alphanumeric sequence of the CAPTCHA image. The CAPTCHA image can be mended in various ways depending on your need, please visit phpCaptcha [] for more details.
Allow Students to Unenroll
If enabled, students can unenroll themselves from courses. If disabled, the Unenroll functions are removed.
Require Email Confirmation Upon Registration
If email confirmation is enabled, before they can login, registrants must confirm their registration by replying to a message sent to the email address they registered with.
Allow Instructor Requests
If enabled, students will be allowed to request that their account be upgraded to an instructor account. Instructor account requests must be approved by administrators using the Instructor Requests section. If disabled then the Create Course link used for requesting an instructor account will be removed and only the administrators will be able to create instructor accounts.
Instructor Request Email Notification
If enabled, and if Allow Instructor Requests is enabled, then an email notification message will be sent to the Contact Email each time a new instructor account request is made. This does not affect whether or not instructor requests can be made, only whether or not a notification message is sent out each time.
Auto Approve Instructor Requests
If Allow Instructor Requests is enabled, then existing students requesting instructor accounts will be upgraded automatically, bypassing the approval process. Additionally, any newly created accounts will be created as instructors rather than as students. Useful for setting up a demo version of ATutor.
Theme Specific Categories
Theme specific categories allows for the association between themes and categories. Courses belonging to a specific category will always be presented using that category's associated theme. This option disables the personalised theme preference. Use the Categories section to create and manage course categories, and the Themes section to install and manage themes.
User Contributed Handbook Notes
If enabled will allow anyone viewing the Handbook to contribute notes. User contributed notes must then be approved by an administrator by logging in on the main Handbook page. This option is available in ATutor 1.5.1+.
Illegal File Extensions
A list of all the file types, by extension, that are not allowed to be stored on the server. Any file that is being imported or uploaded with an extension in the specified list will be ignored and not saved. The list must contain only the file extensions seperated by commas without the leading dot.
Cache Directory
Where cached data is stored. On a Windows machine the path should look like C:\Windows\temp\, while on Unix it should look like /tmp/cache/. On some Linux/Unix based systems, a shared memory device can also be used /dev/shm/ if it is available. Leave empty to disable caching.
LaTex Server
The URL of the mimeTex server. A public ATutor mimeTex web service is currently available at ''. For production use, please do not use the public mimeTeX web service. Install mimeTeX on your own server instead. Please read [] for installation details.
Course Backups
The maximum number of backups that can be stored per course. The stored backups do not count towards the course's Max Course Size.
Number of Days to Keep Copied Sent Messages for
All sent messages are copied to the sender's Sent Messages area. This option specifies the number of days old a copied message has to be before it is automatically deleted. The recipient's message is not affected.
Check for ATutor Updates Automatically
If enabled, ATutor will check the web site for updates whenever the administrator logs in. This option is available since ATutor 1.5.2.
Maintain File Storage Version Control
If enabled, every file revision in the File Storage area will be saved. If space is a concern, the administrator may wish to disable this feature.
Enable Mail Queue
The administrator may wish to set up a cron job (automated event scheduler) for email. If enabled, and if the cron has been set up, system email will be sent out at a certain time instead of immediately. This can help speed up email capable features where a slower mail server is being used.
Automatically Install New Language Packs
If enabled, and if the cron job (automated event scheduler) has been set up, new language packs published on will be imported automatically This option is available in ATutor
Pretty URL
If enabled, all the public accessible pages will automatically converts their URLs to "pretty url". Pretty URL will remove the traditional URL query stirngs, and replace them with slashes (/). This option is available in ATutor 1.6.1+.
Course Directory Name
If enabled, and only if the Pretty URL is enabled. The course id in the pretty URL will be replaced by a custom course directory name. This name can be setup individually and uniquely in the course property. This option is available in ATutor 1.6.1+.
Apache mod_rewrite
Allows ATutor to use the Apache mod_rewrite function. The mod_rewrite module must be loaded in the conf/httpd.conf file in order for this to work. Please contact your server administrator for more details. If enabled, the accessible pages will be shortened to the predefined rules. Generally, go.php will be taken out.

Default Preferences

The default preferences are applied to newly created accounts at the time of their creation, and to guests when accessing public courses. Members may alter their settings once they have logged in by going to the Preferences area in the main navigation. For more information, see Preferences in the general help area.


ATutor can be displayed in many different languages! Through the Langauge Manager completed languages packs can be selected and imported directly from the website.

Managing Existing Languages

Installed languages can be edited, deleted or exported as an ATutor language pack for redistribution. When exporting a language, a download prompt will appear asking to download a zip file of the language pack.

Editing the language properties allows you to change the following:

Note that the default language (as specified in the System Preferences Default Language) cannot be disabled or deleted unless another language has been installed.

Importing Languages

Language packs can be imported either manually by retreiving the package and then importing it into ATutor, or automatically by having ATutor connect to the language repository directly.

To manually import a new language pack:

  1. Visit [] to download one of the available language packs for your version.
  2. Use the Browse... button to find the downloaded language pack.
  3. Use the Import button to import the language.

If your ATutor installation is connected to the Internet and can contact the website, then it will try to retrieve the list remotely. To automatically import a new language pack from within ATutor:

  1. Select the language you want to import from the drop down.
  2. Use the Import button to import the selected language.

If your installation cannot retrieve the language list from, a message indicating so will be presented rather than a drop down list. In this case you will have to use the manual method described above.

Translating ATutor

Administrators have the ability to customize an installation's language. In order to translate a language,

  1. Set the AT_DEVEL_TRANSLATE constant in /include/ to '1'
  2. Set the session language to the language you wish to translate by using the language selector at the bottom of the screen.
  3. Use the Translate button to pop up a translation window.

You can contribute to the ATutor community by exporting a language pack from your ATutor installation, and attaching it to a message in the Translation Forum []. Also see the Translator Documentation [] for further details about translating ATutor.


Themes are used for changing the look and feel of an ATutor installation. Themes can be set as a personal preference or forced to display by default using the System Preferences Theme Specific Categories option.

ATutor's architecture allows for the separation of presentation elements from code or logic elements. As a result, it is easy for any XHTML and CSS proficient person to create customized themes and layouts without having to know anything about PHP or the inner workings of ATutor itself.

Importing/Exporting Themes

Themes can be imported into, or exported from, ATutor using the Themes manager in the ATutor administrators' configuration tools. An existing theme can be exported, then imported back into an ATutor installation to create a copy, after which the copy can be modified to create a new theme. Themes can be exported and shared with others. See the Themes page on [] for a list of available themes, and for a place to share your themes.

To import a theme the ./themes/ directory must be writable. On Windows machines using multiple user accounts, that directory will have to be shared to provide write access to it. On Unix machines the command chmod a+rw themes should be used to make the directory writable.

Managing Existing Themes

All available themes on an ATutor system are listed in the Administrator's Themes section.

Use the Preview button to test the theme to make sure it doesn't break. If a previewed theme breaks, simply log-out and login again to restore the default theme. The Preview button can also be used to preview disabled themes. This feature is available in ATutor 1.5.1+.
Enabled themes are available to users in their Preferences. Themes can be disabled, helpful if you are modifying a theme. If a student's preferred theme is disabled, the system default theme will be used in its place.
Set as Default
If a theme is set as the Default Theme, it will display for students who have not selected a prefered theme, and it will be displayed on public pages, such as the Login screen or Registration screen.
Any theme can be exported from an ATutor installation to share with others. It can also be imported back into an ATutor installation as a copy, available to be modified for creating a new theme.
A theme is removed from the system if the Delete button is used. The Default theme can not be deleted.

Category Themes

If there are Course Categories defined and the System Preferences Theme Specific Categories has been enabled, themes can be assigned to categories of courses so they are all displayed with the same look and feel. When defining course categories while Category Themes is enabled, a list of available themes will appear to select from, and assign to each category.

Note that when Category Themes has been enabled, users will no longer be able to select themes from their personal preference settings.

Creating Themes

The process for creating a theme is basically to export an existing theme from ATutor, import it back into ATutor, then modify the files of the copied theme. Details about creating themes can be found in the themes_readme.txt file found in the /themes directory of your ATutor installation. Also see the comments included in the files of the Default ATutor theme for additional details.

Error Logging

Error logging is available to administrators as a trouble shooting tool. Should the system be giving error messages, a daily list of these errors are collected and available for review or to be bundled up and sent to the ATutor team for investigation. When using the support forums, attaching any error logs may be helpful in finding solutions to problems on your system.

News Feeds

Instructors may display syndicated feeds in the side menu of their courses. The choice of feeds available to them is controlled by the administrator. Feeds may be managed by going to the News Feeds link under the System Preferences tab.

Google Key

For the Web Search module to function, an administrator must first create an account and obtain a license key at [] and enter it on this page. The google web search can then be used by students as an external embedded service within ATutor.

Cron Set-Up

ATutor operates best with the help of an automated event scheduler, commonly known as a cron job. The cron interval should be set at between 5-30 minutes, depending on server resources. Setting the cron to 10-15 minutes is recommended.

The cron is run by requesting a specific ATutor page, and can be initiated by any machine that has an Internet connection and access to the ATutor installation.

Notice that the URL being used will be unique for each installation and that for security reasons the requested URL includes a secret six-character alpha-numerica authentication key. The cron will not run if the key is incorrect or missing.

The Mail Queue feature requires the cron to be set-up and running correctly before it can be enabled.

Unix Setup

  1. Enter your hosts cron utility, either using an existing web interface or from the shell with the command crontab -e.
  2. To run the cron every 10 minutes enter one of the following lines into the crontab editor:
    */10 * * * * wget -q -O /dev/null
    */10 * * * * lynx -dump > /dev/null

    Replace with the full server and path to your ATutor installation.

    Replace SECRET-KEY with the key provided on the Cron Configuration page in your ATutor Administration section.

    Replace 10 with the desired interval.

Note: If your site uses SSL then replace http with https and you may also need to add --no-check-certificate to wget.

Windows et al Setup [] offers free web-based cron services and is available in multiple languages.


The Enrollment list for a particular course determines which of your students have access to the course content and course management tools. Instructors can create, import and export student lists.

To administer members of a course, select the Enrollment tab, then select a course and press the Filter button.


Students who are enrolled in a course can be assigned course administrative privileges. This allows students to perform actions like managing content, creating and marking tests, managing groups, or moderating forums or the chat. This tool is useful for creating teaching assistants, or for creating multiple instructors for a course. Select the users you wish to give privileges to, and use the Privileges button. Then choose which tools you want each user to have access to and use the Save button.


The Users section allows managment of students, instructors, and administrators. Note that administrators are not considered regular users of the system; an administrator account can not normally be used to login to a course. They can however login temporarily as the course instructor, using the View button in the administrator's Courses listing. For the purposes of documentation the term "users" will be reserved for any account type that is not an administrator.

There are four types of user accounts that can exist in an ATutor installation, as defined by their Status:

Only administrators may disable an account. Disabled accounts cannot login to the ATutor installation, and will not appear in a course's Enrollment Manager.
Unconfirmed accounts are created only when the System Preferences Require Email Confirmation Upon Registration option is enabled.
A regular account which can enroll, but not create courses.
A regular account which can enroll as well as create courses.

Creating User Accounts

Administrators can manually add users to the system by using Create User Account. Manually created accounts are automatically confirmed and the account status is set to Student, Instructor, or disabled as choosen in the Account Status field of the user account creation form.

User accounts can also be created by individuals using the Registration form available through the public pages of ATutor. Instructors can also generate user accounts by importing a course list in the Enrollment Manager.

Instructor Requests

If the System Preferences Allow Instructor Requests option is enabled and the Auto Approve Instructor Requests option is disabled, then pending instructor account requests will be listed on this page.

Using the Deny or Approve buttons after selecting an entry will remove it from the list and take the appropriate action. An email message will be sent to the account holder notifying them of the change.

Note that the number of pending Instructor Requests is always listed on the Administrator Home page.

Master Student List

If the System Preferences Authenticate Against A Master Student List option is enabled, this page will allow an administrator to manage that list. If enabled, only new registrations that validate against the master list will be successful. The master list is flexible and can be used to validate any two fields, one of which is publicly viewable to Administrators, while the other is hidden. A common use of this feature would be to authenticate students using a previously assigned Student ID & Birth Date combination. Two extra fields will appear on the Registration screen when master list authentication is enabled.

Subsequently, when a student registers for an ATutor account on the system, he/she must provide this authenticating information (such as their student ID and Birth Date). Once an account is authenticated and created, the user will then be associated with the appropriate entry in the Master Student List. If Require Email Confirmation Upon Registration is enabled in System Preferences, the user must confirm his/her account using that email before the account is activated.

Viewing the Master Student List shows Student ID-Username pairs. Student IDs in the Master Student List that are not associated with any student account are considered to not have been created.

Importing Student IDs

Importing Student IDs into the Master Student List requires a specifically formatted file. This file can be uploaded under the "Upload List" heading.

The master list must be imported from a plain text file, where each row in the file contains two fields seperated by a single comma. The first field will be used as the Student ID. The second field will be the PIN or Password which will be encrypted by the ATutor system, once the list is uploaded, so that it cannot be viewed and read by anyone. Those two fields together will be used to authenticate students when creating new accounts. The fields may optionally be enclosed by double quotes. Such a file is known as a CSV file and can be generated manually using a text editor, or by any spreadsheet application (such as MS Excel).

In the example below, a student number and a birth date are used to construct a master list:

"12345", "10/07/54"
"12346", "23/04/76"
"12347", "30/05/68"

Email Users

The Email Users feature allows an administrator to send an email to all students, instructors, or both. Unconfirmed and Disabled accounts are not included in the mailing. The email address specified in the System Preferences is used as the reply-to address for the email(s).


An ATutor installation can be maintained by multiple administrators, each with their own privileges. The three kinds of administrator accounts are described below.

Super Administrator
This administrator has no restrictions and has access to all of the administrator options. This is the only administrator type that can create and delete other administrator accounts. There must always be at least one Super Administrator account.
Active Administrator
An administrator account whose access is limited. This administrator only has privileged access to sections that they were assigned to when their account was created by the Super Administrator.
Inactive Administrator
An administrator account that has not been assigned any access privileges. As a result, this administrator cannot login.

Create Administrator Account

To make a new administrator, follow the Create Administrator Account link, enter the login name, password, real name and email and select the appropriate administrative privileges to be assigned to this account.

Administrator Activity Log

The Administrator Activity Log lists all actions made to the ATutor database tables. Viewing a log entry will give detailed information about the selected activity. The log can be reset by using the Reset Log feature.


An administrator can create and manage courses, shared forums, and course categories without having to login as a course instructor.

Creating Courses

See Creating Courses documentation for Instructors.

In addition, administrators have access to the following properties:

Course Quota
Defines the maximum size of a course. That is, the amount of space each course's file manager can have.
Max File Size
Defines the maximum size allowed for a file being uploaded to a course's file manager.

Note that Max File Size limitations can not be set higher than that allowed in the PHP settings for the system. The maximum allowable upload size can be increased by editing the values of upload_max_filesize and post_max_size in the system's php.ini configuration file.

Default Course Tools

Administrators are able to set the tools that will appear in the main navigation and the home page for newly created courses by specifying student tool defaults. Instructors can alter these settings after a course is created by going to Course Tools area under the Manage tab.

Default Side Menu

Administrators are able to set the side menu dropdowns for newly created courses by specifying side menu defaults. Instructors can alter these settings after a course is created by going to Properties under the Manage area. For more information, see Side Menu in the instructor help area.


A course backup includes all available course material as an archive in a format specific to ATutor. Backups are forwards compatible with future versions of ATutor but may not be backwards compatible with previous versions of ATutor. Once a backup is created, it can be downloaded for safe-keeping, imported into another ATutor installation, used as the basis for a newly created course, and available in the originating course's Backup Manager. Instructor can also create their own course backups from within a course.

Creating Backups

To create a backup, use the Create Backup link in the sub-navigation. The number of backups a single course can keep on the server is defined by the System Preferences Course Backups option.

Administrators can create backups for any course, while instructors can only create backups of courses they own.

Restoring Backups

Restoring a backup as an administrator is similar to restoring a backup as an instructor, with the added option of being able to select which course the backup should be restored into.

For details on restoring a backup into a course, see the Backup Manager's Restoring Backups section in the Instructor Documentation.

Managing Backups

Backups can be downloaded to the administrator's hard-drive for safe-keeping by using the Download button. Backups can also be edited or deleted.


This section allows administrators to create regular course-specific forums as well as shared cross-course forums. A shared forum is available to all courses specified to use it, allowing users from different courses to communicate with eachother in one forum. Only administrators can create shared forums, though instructors or privileged users in any of the courses sharing a forum can manage its messages.

Auto-Enroll at Registration

Administrators can use this tool to generate a unique URL for the ATutor registration screen, so that when new users follow the link and register, they are automatically enrolled in a specified number of courses. Once the URL is generated, make it available to perspective students so they can register, enroll, and login in one easy step. When students access the registration form using the link, the selected courses will be listed on the form, and when the registration is complete, those courses will be added to the student's My Start Page, and he or she will be logged in.

Click on Create/Edit Auto Enrollment to create an auto-enroll URL

This should be a general reference that encompasses the grouping of courses. For example, if students will be enrolled in introductory Boilogy 101, Botany 101, and Zoology 101, the title might be "First Year Natural Science" .
Courses to Enroll
Select from the available courses on the system to have them added to the auto-enroll grouping of courses for the title described above. Once all the required courses have been choosen, press the Save button to generate the link

Course Categories

Categories are used for grouping related courses. This is helpful when viewing courses in the course browser. Courses can be associated with categories when they are created, or at a later time by editing their properties. Course categories can also be associated with Themes if the System Preferences Theme Specific Categories option is enabled.


Import Modules

As of version 1.6.2 the preferred method of installing modules is by importing modules from using the Module Manager. Read the descriptions for modules you want to install to be sure all prerequisites are met, and note the version numbers the module has been tested with. Though in most cases older modules will function without any trouble in newer versions of ATutor, occassionally they need to be updated to work with a current version. Please report any problems you experience with modules to the Modules Forum on []

Uninstalling Imported Modules

Modules that have been installed using the Import method above, can be uninstalled using the Module Manager's Uninstall button. After pressing the Uninstall button you will be given the option to remove the data and the directories associated with the module. Select from the checkboxes, and press continue. If you are removing the module completely, you will probably want to delete the data and directories. If you are upgrading or reinstalling a module, you will want to save the data and directories so they can be reused with the upgraded or reinstalled version of the module.

Upload Module

Modules can be downloaded uploaded through the Module Upload form at the top of the Install Modules screen. Uploaded modules must be in ZIP format, so if you have older modules, they may need to be axtracted from the tar.gz format, then re-archived in ZIP format before uploading.

Missing Modules

When an ATutor system is upgraded modules need to be reinstalled. Those modules will be listed as missing in the Module Manager.

Partially Installed Modules

When a module is uninstalled, but its data and/or directories are saved, it will be listed as Partially Uninstalled. The same status will appear for modules for which the uninstall process was not completed for one reason or another. To remove these modules completely, they must either be reinstalled then uninstalled once more, or they must be removed by deleting the database tables and/or directories manually.

Manual FTP Module Install

In most cases you should use the Import method described above. Manually installing a module through an FTP client is useful if you are installing a third party module not available from Or, if you are a module developer and need control over the module files for editing etc. you will want to use the manual FTP method. Manually installed modules must be uninstalled manually if they need to be removed.

To install a module manually it must first be extracted into a unique subdirectory within the ./mods directory of your ATutor installation. It will then be listed on the Install Modules page where more details can be viewed, and the module installed.

After extracting a module, see the readme file in the module's top directory for any additional installation instructions or requirements.

Creating Modules

See the ATutor Module Development Documentation for information about creating ATutor modules, and review the module files in the Hello World demo module (and other modules) as a model that can be duplicated and modified to quickly add new addon features to an ATutor installation.

Export Module

If you want to take a copy of a module from your ATutor system to import into another ATutor installation, or to bundle a copy of a module you have created to submit to to be included in the module repository, select the module from the Module Manager screen, then press Export. This will create a standard module ZIP file that you can download.

Visit the ATutor Modules Site [] for a list of add-on modules for ATutor.


The Patcher was introduce in ATutor 1.6 to allow administrators to update their systems with feature adjustments, security fixes, and other ATutor code changes in between ATutor releases. The Patcher is included as a standard module with ATutor 1.6.1+, and installs as an extra module for 1.6.

The Patch List
On the opening screen of the Patcher will appear a list of patches available for the version of ATutor you are using, along with a description of each patch. This list is retrieved from, as are the patches themselves, so you must be connected to the Internet. Patches are retrieved from by ATutor and applied as necessary.
File Permissions
In most cases you will be asked to temporarily grant write permission to the files that need to be updated or replaced, then once the patch has been applied, you will be asked to change the permissions back to read only. It is important that you follow the instructions after patches have been applied, otherwise you run the risk of opening a security hole.
Types of Patches
Patches come in various forms. Some patches replace code in a file with new code. Others replace a file with a new file. Others may do both on multiple files and multiple code changes. Other patches delete files that are no longer required.
Required and Non-Required Patches
In most cases you will want to install patches in the order they appear in the patch list, but not all patches are required patches. Some feature patches can be ignored if you do not need the features they would add or modify on your system. Other patches will have dependencies, requiring the administrator to install earlier patches before installing a later one. You will be prompted to install previous patches if there are dependencies.
Checks and File Backups
If you have made changes to a file the Patcher wishes to change, you will be prompted to continue or not. The patcher compares your local file with the same file in the ATutor code repository, and if they differ the prompt will display. In many cases the Patcher can apply patches without changing the code you have modified, but if the code to be replaced was modified, the patch will fail, or if the patch replaces a file, your changes will be lost. In all cases the patcher will create a backup of the files that were modified, identified by the filename plus the patch number added as a suffix. Rename the file to its original name to restore that file back to its original state. You can list these files by clicking the view messages button next to the patch listing after the patch is installed. After you have confirmed that the patches were applied and are working properly, it is safe to delete the backup files, though it does not hurt to keep them around.
Private Patches
In some cases private patches can be applied by uploading a patch file through the upload form below the patch list. Private patches are often those used to apply changes that are not being applied to the ATutor default source code, or to apply custom features, or to share patches between users, etc. When uploading a patch, be sure the patch id, defined in the patch.xml file, is unique .

Creating Patches

If you happen to come across a bug you can fix, or have a new feature you would like added to the ATutor public distribution, you can use Create Patch to put your changes into a form that can be easily added to the ATutor public code. Or, if you have a feature you are adding to one ATutor installation that you would like to have added to another, Create Patch is ideal for reproducing your feature across installations. If you are creating new features that are not going to become part of the ATutor public source code, you can build them into a patch so they can be reapplied from version to version as you upgrade your ATutor system. Creating patches does require knowledge of PHP, and of SQL if you plan on creating a patch that changes the ATutor database. Please refer to the appropriate documentation for information on PHP and SQL.

ATutor Patch ID
The patch id you give to your patch must be different from all patches available for the particular version of ATutor it applies to. It is suggested you prefix your patches with a special identifier that represents the author or the authoring organization. If for example the University of Toronto is creating the patch, a patch ID might look like "uoft_0002."
ATutor Version to Apply
This needs to be the exact version number of the ATutor version the patch applies to (e.g 1.6). including any minor version numbers (e.g The exact version number can be found on the Administrator open screen under "Statistics and Information." In most cases when applying a patch created for an older version of ATutor, the "ATutor version to Apply" will need to be adjusted. Or, this can be adjusted manually in the patch.xml file included with the source code of the patch.
This should be a detailed description of what the patch does. Example might include "fixes problem uploading files to filemanager" for a bug fix, or "added a timer function to tests" for an added feature, or "removes registration tab" for a feature adjustment, etc. Include enough detail so those applying the patch understand exactly what it will do..
SQL Statement
This optional field can be used to insert SQL commands which modify the ATutor database. It might be used to write an SQL statement to modify and existing table, such as changing a data type, or a field size, or to add or remove an field. It can also be used to insert SQL that generates a new table for a new feature created by a patch, or it can be used to insert data into a table used by a feature created by the patch. Any SQL can be included in this field. Be careful when running SQL, that that SQL is not going to interfere with upgrade SQL. If you are changing table structures and those same tables are being altered during an upgrade, the upgrade may fail.
Dependant Patches
It is common for later patches to require changes from earlier patches before they can be installed. If this is the case for the patch you are creating, enter the patch IDs into the Dependant Patch ID field. Click on Add Dependent Patch if additional dependencies are required. Be sure to check the patches on the opening screen of the Patcher to see if the file you are modifying with your patch is being modified by an patch. If they are modifying the same files, you may need to include the ID numbers for those patches in the Dependant Patches for the patch your are creating.
This area is where most ATutor patches are created. Click on Add File to generate a patch block. A patch block can include one of four actions on the file being modified, as described below. As many patch blocks as required can be added to a patch.
Add File
The Add action can be used to add a new file to ATutor. This action is often used in conjuction with other patch blocks that alter or delete files, to add a replacement file for one deleted, or to perhaps add a required or include file needed by a modified section in the file being changed. In the File Name field enter the file name to be assigned to the file when it is installed. In the Directory field enter the relative path from the ATutor root directory in which the modified file is or will exist. Select from Upload File using the Browse button to locate the file in your local computer's file system. Note that the upload file can have any name. It will be renamed to the file name listed in the File Name field when it is installed.
Alter File
This option is used when you wish to make changes to a piece of code within an existing source code file. In the File Name field enter the name of the file in the ATutor source code that will be altered. In the Directory field enter the relative path to the directory in which the to be alter file exists, relative to the ATutor root directory. In the Code To Replace From field copy the code from the original file the will be replaced, or appended to, and in the Code To Replace To field enter to code that will replace the code above in the From field. Or, if you are adding code instead of replacing code, include the code from the field above so it gets added back if you are only using that code as a way of identifying a location in the file where new code is being added.
Delete File
This option will remove files from ATutor. In the File Name field enter the name of the file to be deleted. In the Directory field enter the path to the directory in which the to be delete file exists, relative to the root directory of the ATutor installation.
Overwrite File
This option is used to replace an existing file in ATutor with a new one. In the File Name field enter the name of the file to be replaced. In the Directory field enter the path to the directory in which the to be replaced file exists, relative to the root directory of the ATutor installation. In the Upload File field use the Browse button to choose a file from your local computer to replace the specified file. The upload file may be named anything. It will be renamed to the file it is replacing when the patch is installed.
Create Patch
Click on this button to build the patch into a downloadable zip file. This zip file can then be uploaded in the Upload field on the main Patcher screen to apply a patch to a system.
Save Patch
Click on this button to save the developing patch to the ATutor database for future reference. Though it is not required, you should save a copy of the patch in this way, so it can be retrieved and edited if necessary. Or, if a patch takes more than a single sitting to build, you can save it, then retrieve it later to continue.
Press this button to ignore the latest changes to the patch, and return to My Own Patches Screen.


A variety of strategies are available for troubleshooting an ATutor installation that may not be functioning properly.

Near the top of the include/ file, set the value of AT_DEVEL to true. This will display your session variables at the bottom of the screen. It will also display the variable names associated with all feedback messages, so they are easier to find through the language manager if you wish to modify their language. The debug() function will also become available, allowing testers to print out any type of variable in an easily readable format.
debug(mixed variable [, string title])
It is possible to display the value of variables using debug(). variable is the PHP variable to output. title is an optional title that can be printed inside the debugging box to easily identify which variable is being outputted.
debug($_SESSION); // print current session variables
debug($_REQUEST); // print all GET, POST, and COOKIE variables
Error Logging
View the error log through the System Preferences section. There may be information in the error reports that can help you identify where or how an error occured. The output from the error log can be sent to the ATutor team to aid them in finding a solution to your problem.
Often, system problems can be fixed by reviewing the phpinfo page. This will show all of the configuration options for your system. Review the Requirement & Recommendations for different values that should be set and displayed in the phpinfo output. Below is the contents of a phpinfo file. Viewing this page in a browser will show the system variables.


Also see the Developer Documentation for details about modifying the source code.