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.
The first step when installing or upgrading ATutor is to check if the minimum requirements are met. The following describes those checks.
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.
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.
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.0.2 or higher, or 4.1.10 or higher is required. MySQL 4.0.20 and higher or 4.1.10 and higher is recommended, especially if you are using languages that would benefit from being represented in the UTF-8 character set. As ATutor moves towards utilizing UTF-8 throughout, support for older version of MySQL will be removed.
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 [dev.mysql.com/doc/mysql/en/privileges.html] for additional information.
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 [getfirefox.com] for either Windows, *nix or Mac OS X.
Please review the requirements section before attempting to install ATutor. The latest version of ATutor can always be found on the atutor.ca downloads [atutor.ca/atutor/download.php] page.
To extract the ATutor .tar.gz archive you will need an application like WinZip [winzip.com] or WinRar [rarlabs.com].
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/config.inc.php 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/config.inc.php to be Readable and Writeable by World, and the content directory to be Readable, Writeable, and Executable by World.
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, http://your_server.com/path_to_atutor/ATutor/, then follow the step-by-step instructions:
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 [www.atutor.ca/atutor/translate/] 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 [atutor.ca/atutor/docs/translate.php] 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 [atutor.ca/atutor/themes/index.php] 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, http://your_server.com/path_to_atutor/ATutor/, then follow the step-by-step instructions.
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:
My Account allows the Administrator to change his/her account password, name, or email address.
The default preferences are only applied to newly created accounts at the time of their creation and to guests when accessing public courses. Note that the default theme is set in the Themes area, and default language is set in the System Preferences area. Also, Auto-Login is not decided by administrators. 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 atutor.ca website.
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.
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 atutor.ca language repository directly.
To manually import a new language pack:
Browse...
button to find the downloaded language pack.Import
button to import the language.If your ATutor installation is connected to the Internet and can contact the atutor.ca website, then it will try to retrieve the list remotely. To automatically import a new language pack from within ATutor:
Import
button to import the selected language.If your installation cannot retrieve the language list from atutor.ca, 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.
Administrators have the ability to customize an installation's language. In order to translate a language,
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 atutor.ca Translation Forum [atutor.ca/forum/4/1.html]. Also see the Translator Documentation [atutor.ca/atutor/docs/translate.php] 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.
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 atutor.ca [www.atutor.ca/atutor/themes/index.php] 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.
All available themes on an ATutor system are listed in the Administrator's Themes section.
Preview
Enable/Disable
Set as Default
Export
Delete
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.
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 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 atutor.ca support forums, attaching any error logs may be helpful in finding solutions to problems on your system.
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 Syndicated Feeds link under the System Preferences tab.
For the Web Search module to function, an administrator must first create an account and obtain a license key at google.com/apis [google.com/apis] and enter it on this page. The google web search can then be used by students as an external embedded service within ATutor.
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.
crontab -e
.*/10 * * * * wget -q -O /dev/null http://your-server.com/atutor/admin/cron.php?k=SECRET-KEY
*/10 * * * * lynx -dump http://your-server.com/atutor/admin/cron.php?k=SECRET-KEY > /dev/null
Replace your-server.com/atutor/
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
.
webcron.org [www.webcron.org] 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:
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.
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.
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 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"
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.
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.
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.
See Creating Courses documentation for Instructors.
In addition, administrators have access to the following properties:
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.
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 Student Tools area under the Manage tab.
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.
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.
Since version 1.5.2, ATutor provides the facility to install, enable, or disable student, instructor, and administrator tools as modules.
To install a module 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 retrieved and the module installed.
After extracting a module, be sure to see the readme file in the module's top directory for any additional installation instructions or requirements. 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.
Visit the ATutor Modules Site [www.atutor.ca/atutor/modules.php] for a list of add-on modules for ATutor.
A variety of strategies are available for troubleshooting an ATutor installation that may not be functioning properly.
debug($_SESSION); // print current session variables debug($_REQUEST); // print all GET, POST, and COOKIE variables
<?php phpinfo(); ?>
Also see the Developer Documentation for details about modifying the source code.