ATutor Admin Handbook

ATutor Administrator Handbook

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.

Installation

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.

PHP

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: Zlib support must be enabled in PHP; It is used for compressing and uncompressing ZIP files.
mysql: MySQL support must be enabled in PHP.
mbstring: 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: Sessions support must be enabled in PHP.
session.auto_start = 0: session.auto_start must be disabled in PHP.
session.save_path: 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

MySQL

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 [dev.mysql.com/doc/mysql/en/privileges.html] 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 [getfirefox.com] 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 atutor.ca downloads [atutor.ca/atutor/download.php] page.

Windows Considerations

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

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/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.

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, http://your_server.com/path_to_atutor/ATutor/, then follow the step-by-step instructions:

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 [atutor.ca/services/licensing.php] for more details.
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.
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.
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.
Save configuration
Before reaching the final step the include/config.inc.php 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 config.inc.php.
Anonymous Usage Collection
To assist the development team in serving the ATutor community, you can anonymously submit basic system information to the atutor.ca server.
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 [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.

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:

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.
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
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.
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.
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.
Save configuration
Before reaching the final step the include/config.inc.php 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/config.inc.php). 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/config.inc.php)
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.
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.
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 atutor.ca 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.
Session Timeout: To help prevent a person's ATutor session from being abused if they walk away without logging out, a timeout period can be set to automatically end a person's session after a certain period of inactivity. A reasonably short period of time is advised if users might be expected to use ATutor at a public workstation. Users are warned of the timeout 5 minutes in advance, then are automatically logged out if they do not acknowledge the warning. Default: 20 minutes
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
Course Browser: If enabled, students are able to browse through the available course in ATutor.
Show Current Activity on My Start Page: If enabled, students and instructors are presented with a list of current changes in their course on My Start Page, such as current announcements, new forum posts, upcoming tests, new files for download, and much more.
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 [www.phpcaptcha.org/captcha-gallery/] 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.
Allow Instructors to Create Courses: If the ATutor administrator should be responsible for creating new courses, disable this setting. Otherwise the default setting allows instructors to create their own courses. This feature may not be avaible on some systems.
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 'http://www.atutor.ca/cgi/mimetex.cgi?'. For production use, please do not use the public mimeTeX web service. Install mimeTeX on your own server instead. Please read http://www.forkosh.com/mimetex.html [www.forkosh.com/mimetex.html] 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 atutor.ca 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 atutor.ca will be imported automatically This option is available in ATutor 1.5.3.2+.
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.

Languages

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.

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:

Language Code
Locale
Character Set
Direction
Left to Right, Right to Left
Regular Expression
Language name translated
Language name in English

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 atutor.ca language repository directly.

To manually import a new language pack:

Visit atutor.ca/atutor/translate/ [atutor.ca/atutor/translate/index.php] to download one of the available language packs for your version.
Use the Browse... button to find the downloaded language pack.
Use the 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:

Select the language you want to import from the drop down.
Use the 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.

Translating ATutor

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

Set the AT_DEVEL_TRANSLATE constant in /include/vitals.inc.php to '1'
Set the session language to the language you wish to translate by using the language selector at the bottom of the screen.
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 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

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 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.

Managing Existing Themes

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

Preview: 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+.
Enable/Disable: 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.
Export: 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.
Delete: 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 atutor.ca 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 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.

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

Enter your hosts cron utility, either using an existing web interface or from the shell with the command crontab -e.
To run the cron every 10 minutes enter one of the following lines into the crontab editor:
*/10 * * * * wget -q -O /dev/null http://your-server.com/atutor/admin/cron.php?k=SECRET-KEY
Or
*/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.

Windows et al Setup

webcron.org [www.webcron.org] offers free web-based cron services and is available in multiple languages.

EasyCron.com [www.easycron.com] is another free cron job provider which is worth a try.

Enrollment

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.

Privileges

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.

Users

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:

Disabled: 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: Unconfirmed accounts are created only when the System Preferences Require Email Confirmation Upon Registration option is enabled.
Student: A regular account which can enroll, but not create courses.
Instructor: 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).

Administrators

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.

Courses

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.

Backups

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.

Forums

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

Title: 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.

Modules

Import Modules

As of version 1.6.2 the preferred method of installing modules is by importing modules from atutor.ca 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 atutor.ca [www.atutor.ca/forum/17/1.html]

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 atutor.ca. 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 atutor.ca 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 [www.atutor.ca/atutor/modules/index.php] for a list of add-on modules for ATutor.

Patcher

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 update.atutor.ca, as are the patches themselves, so you must be connected to the Internet. Patches are retrieved from update.atutor.ca 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 1.6.1.2) 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.
Description: 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 update.atutor.ca 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.
Files: 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.
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.
Cancel: Press this button to ignore the latest changes to the patch, and return to My Own Patches Screen.

Troubleshooting

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

AT_DEVEL

Near the top of the include/vitals.inc.php 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.

phpinfo()

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.

<?php
phpinfo();
?>

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

Creating and Adding External Tools

The External Tools utility allows ATutor administrators and instructors to link external tools into ATutor, and to associate those tools with content as learning activities. External tools that support the LTI 1.0 tool provider standard may be added to content here.

Setup A New External Tool

Title: Enter a name for the tool being created in the title field
ToolID: Create an ID for the tool that will be unique across all tools on the system (e.g. demo_tool.ocadu.ca) any unique string will do
Description: Describe the tool, its function, and how it might be used.
Tool Launch URL: Copy the URL of the tool's LTI launch location. Ensure there is no space at the end of the URL (see the Sample LTI Tool below for demo purposes)
Enter the Tool Key and secret
Set various options and Save

External Tool Options

These values may be set by the administrator or the administrator may allow the instructor to set these values in content items.

Required Settings

ToolId (must be unique across system)
This is a unique identifier that you much choose. This identifier must be unique across the system. This identified is used to connect tool content items across exports and imports of the content area.
Tool Launch URL
This is the launch URL for the external tool. It is provided by the eternal tool provider and should be entered here. Generally an external tool provider will give you a URL, key, and secret so that you can access their tool.
Tool Key (oauth_consumer_key)
This is the launch key for the external tool. It is provided by the external tool provider and should be entered here. Generally an external tool provider will give you a URL, key, and secret so that you can access their tool.
Tool Secret
This is the launch key for the external tool. It is provided by the eternal tool provider and should be entered here. Generally an external tool provider will give you a URL, key, and secret so that you can access their tool.

Optional External Tool Settings

Frame Height
This allows you to control the height of the frame that will contain the external tool.
Allow Frame Height to be Changed
The frame height may be specified for a tool by the administrator, or the administrator may allow the instructor to change the frame height.
Launch Tool in Pop Up Window
Normally tools are launched in an iframe at the bottom of an ATutor content page. This option can be used so that the tool opens in a new browser window by clicking a link at the bottom of a content page, which replaces the default iframe. This option may be specified for a tool by the administrator, or the administrator may allow the instructor to specify this option.
Launch Tool in Debug Mode
This option should normally be off except when you are having problems with tool launching. When this option is turned on, The launch is paused part-way through to allow you to examine the data to be sent to the external tool. You are then given an option to continue the launch by pressing a button. This option may be specified for a tool by the administrator, or the administrator may allow the instructor to specify this option.
Send User Names to External Tool
This option determines whether you want to send user names to the external tool. You should only send user names to trusted tools and you should make sure that if you share user names with the external tools that you are following all appropriate regulations regarding student privacy. Sending user names is optional data in the LTI 1.0 specification although some tools may require user names to function properly. This option may be specified for a tool by the administrator, or the administrator may allow the instructor to specify this option.
Send User Mail Addresses to External Tool
This option determines whether you want to send user mail addresses to the external tool.You should only send user mail addresses to trusted tools and you should make sure that if you share user addresses with the external tools that you are following all appropriate regulations regarding student privacy. Sending user mail addresses is optional data in the LTI 1.0 specification although some tools may require user names to function properly. This option may be specified for a tool by the administrator, or the administrator may allow the instructor to specify this option.
Accept Grades From External Tool
Some tools can send grades back to ATutor through an LTI extension REST web service. If the external tool has the capability of using these services and you would like to allow the tool to send grades back to ATutor, you can enable this option. When you author an external tool content item and enable this option, the tool will only be able to read and write grades in a single grade book item that you associate with the content item. This option may be specified for a tool by the administrator, or the administrator may allow the instructor to specify this option.
Allow External Tool To Retrieve Roster
Some tools can retrieve the entire course roster through a LTI 1.0 extension REST web service. If the external tool has the capability of using these services and you would like to provide the entire course roster to the tool then you can enable this option. If this option is enabled, it respects the privacy option setting as to whether or not to release user names and email addresses. If these are configured to be provided on launches and the tool can retrieve the entire roster, then user names and mail addresses are included in the roster when it is retrieved. This option may be specified for a tool by the administrator, or the administrator may allow the instructor to specify this option.
Allow External Tool to use the Setting Service
This option allows the external tool to store up to 8K of data in the content item. Typically the external tool uses this area for a resource setting or perhaps a playlist as selected by the user. In particular it does not allow a separate 8K setting for each user for a content item. This option may be specified for a tool by the administrator, or the administrator may allow the instructor to specify this option.
Custom Parameters Sometimes the external tool requires that you send additional custom parameters along with the launch. The typical use of this would be to specify an ISBN number for a book associated with the launch or to select a particular content item within a content repository. Different tools will use this capability differently. Typically these will be specified as a keyword and a value such as
isbn=929293939

LTI Resources

Sample LTI Tool for Testing/Demo Purposes. Copy this URL, and its associated key and secret, into the corresponding fields in the Create External Tool screen to setup a simple demonstration tool.
http://www.imsglobal.org/developers/BLTI/tool.php
key: lmsng.school.edu
secret: secret

Tools Currently with LTI Provider Capability

QuestionMark
http://www.questionmark.com/ [www.questionmark.com/]
Noteflight
http://www.noteflight.com/ [www.noteflight.com/]
Wimba
http://www.wimba.com/
Elluminate
http://www.elluminate.com/ [www.elluminate.com/]

A current list of LTI conformant systems can be found at:
http://www.imsglobal.org/cc/statuschart.html [www.imsglobal.org/cc/statuschart.html]

More about the LTI Standard http://www.imsglobal.org/lti/ [www.imsglobal.org/lti/]

Here are a couple videos with more information:
http://www.vimeo.com/18074396 [www.vimeo.com/18074396]
http://vimeo.com/14100773 [vimeo.com/14100773]

ATutor

Learning Management System