next up previous contents
Next: How to Upgrade Open Up: Open Administration for Schools Previous: Contents



Version Information

Please read this over before trying to do too much!

Overview for Newbies

Each school that is running Open Admin could normally have up to three virtual for the school office, one for teachers, and one for parents/students.

An installation capable of running on a single SSL (or not) protected website is also available.

The html and cgi scripts for all sites for each school are located in a common folder, normally under the school name. /opt/openadmin/YOURSCHOOL.

The administration or office site has it's files in admin for the HTML files and cgi for the matching cgi scripts. Similarly the teacher site directories are called tadmin and tcgi. So also, phtml and pcgi for the parent site.

If you are limited to having one site only (as some Australian schools are), it can also be configured to run on this single site.

File Locations

Everything is normally arranged:

/opt/openadmin/andrews/admin - for St Peter School main admin site
/opt/openadmin/andrews/tadmin - for St Peter School teacher site
/opt/openadmin/andrews/padmin - for St Peter School parent site

As well as these 6 folders, there are 3 additional folders for:

Together, these 9 folders make up the Open Admin files for a school.

There is also a global.conf configuration file listing all of the schools in a school division, consortium, etc. if more than one installation. If not, then only the version of this file found in the school's etc directory need be used.

If more than one school installation is done, the global.conf file should be placed in


so that all school installations may read it, and share data. This is so that withdrawn students from one school can be easily enrolled in another (ie. feeder schools). Even single schools have to add their database name to this file. This is one of the installation problems people have had in the past, and which is now more easily done with the new installation scripts. The location of this directory in set in the admin.conf file and would normally be in your schools etc folder by default.

If you are running the IEP (Special Education) site, you can install those files in:

/opt/openadmin/iep/admin - for the special needs website.

The Simple Install - Debian/Ubuntu

  1. Install Linux (Debian). For a minimal secure server installation, turn off the 'Desktop Environment' choice and the 'Standard System' choice to minimize running software and installation issues.

  2. Download Open Admin. Untar the download (tar xvzf openadmin-5.25.tar.gz ) and move to the utility/debian-install directory.

  3. Run the scripts in numeric order from 1 to 4. Script 1 will install Apache and MySQL and other required apps (via apt-get). Script 2 will install perl modules available as Debian packages. Script 3 will install a couple of other perl modules not available as Debian packages. Script 4 does the main OA site installation including the MySQL database creation. Script 4 can be run again to install other schools on the same server. The 'removesite' script can be used to remove sites (the reverse of script 4). will do the installation of the special education site, also.

  4. OA is now installed and accessible using those web addresses (URL's) specified during installation. If you don't yet have these web addresses in your DNS server, you can edit your workstation computer 'hosts' file to map the web addresses to the IP address of the server.

Program Requirements

One of the design goals of OA was to make it relatively easy to install and lightweight to run both in hardware and bandwidth demands so that even satellite connections with long latency will work. This has already been demonstrated in many remote schools.

The following perl modules will also be required:

In order to install the perl modules, the easiest approach is to use the packages and package manager that comes with your Linux version. The Debian / Ubuntu package manager (apt-get) makes this fairly straight forward. More is found under the Debian/Ubuntu installation, or just using the install scripts described above.

Another method is the CPAN method. The CPAN (Comprehensive Perl Archive Network) is a worldwide network of servers from which you can automaticallY download and install the modules. The first time this is used you configure the server locations you want to use, etc. The defaults suggested work fine.

One syntax is as follows:

perl -MCPAN -e 'install PERLMODULE'

where PERLMODULE is the name of the module to install... such as FreezeThaw. Case appears to be an issue. If you can't find the right name go to the CPAN search site
( ) and have a look around.

If you are using the software in Saskatchewan and would like to communicate directly to the provincial SDS system, then additional software and perl modules are required since we create a secure HTTPS connection to the Sask Learning server and send and receive transactions in an XML format.

You will also need:

  1. OpenSSL (from - SSL library required for https.
  2. Perl Modules:

    1. Bundle::LWP (which includes LWP::UserAgent, HTTP::Headers, and
      HTTP::Request::Common) - used to connect via https.
    2. Crypt::SSLeay (for SSL connections)
    3. XML::Writer - used to write the output XML.
    4. XML::Writer::String - holds xml output in a string.
    5. Data::UUID

    GD Graphics for the Reading Report Graphs from Then the supporting perl modules: GD::Graph. We also need zlib and libjpg and also libpng if you'd like.

Installation Overview

The installation process consists of the following steps:

  1. Install Linux
  2. Copy the files.
  3. Configure the Webserver.
  4. Add the Data to the database.
  5. Import Student Data.
  6. Edit the Configuration.
  7. Get Started (on the Browser Side)

Step 1: Install Linux

Download the latest Ubuntu Server or Debian Installation (or your Linux distribution of choice). Make sure that you add Apache, Perl, MySql (or PosgreSQL), and TeXLive. Please see the Ubuntu/Debian Installation instructions.

If creating an Open Admin only server, then a minimal, lightweight installation would be a good choice. The idea is to create a server appliance that needs only minimal, if any, management. As well, only a minimal hardware platform will be required if only a few schools are running on it.

Step 2: Copy the Files

  1. Download the latest Open Admin version from into /tmp (or some other commonly used file location). If you download to your workstation desktop you can copy to your server using a secure copy program like scp, or simply copy it to a flash drive and copy onto the server in this way.

  2. Untar the download:

    tar xvzf openadmin-5.xx.tgz

    This will create /tmp/openadmin-5.xx with:

  3. Create a directory to hold the files for a school (or several) if it doesn't already exist.

    mkdir /opt/openadmin

    We will assume that you are using /opt/openadmin. Just substitute another filepath.(ie. /opt, /Library/Webserver/ if OSX, etc.)

  4. Copy the directory containing the main OA school site files into this new directory with a short single word for the school:

    cp -r /tmp/openadmin-5.xx/school /opt/openadmin/andrews

    where andrews is replaced with your school name. (if it's not St. Peter!) You now have the main school files in place to run the 3 main St. Peter websites (main, teacher, parent).

  5. Copy the school folder as many times as required to get one school folder for each school.

    (ie. cp -r /tmp/openadmin-5.xx/school /opt/openadmin/stmary )

    This assumes a multi-school installation. Just do this once if a single school.

  6. Check/change the ownership and permissions on the files/folders. The files in the downloaded tar distribution are set to root ownership and members of root group.

    Change the ownership of the copied files/directories to that of the user and group that the webserver runs as. In Debian/Ubuntu this is www-data for both user and group. For Slackware this is webuser and webgroup. For Red Hat this is apache for both. Make sure that you are in the /opt/openadmin directory so that you change the ownership of everything below this level in the filesystem.

    If www-data:www-data then chown -R www-data:www-data *
    If apache:apache then: chown -R apache:apache *

    If this seems too loose in terms of security ( since you may have users on this system), ownership may be left at root/root for scripts and just make sure that the running scripts can create required LaTeX files in the folder where the script runs that is creating it. If not set correctly, you'll see entries in the error log about the script not being able to create tex files and no pdf files (such as student roster reports and report cards) will be created. Get into the habit of checking the webserver logs for each of the sites. Again, the location of these log files varies depending on the linux distribution that you are using. On Debian/Ubuntu servers, it is located in /var/log/apache2 while Red Hat stores them in /var/log/httpd.

    A running script must also be able to copy generated PDF files into the download folder in admin or tadmin of the main or teacher site. Scripts must also be able to change the term file, studentnumber, receiptnumber files in the school level etc folder as well. You will have to change the permissions on these files and directories if you don't reset the ownership to that of the User Id (UID) that the webserver runs as (as outlined above).

  7. Copy your School Logo file (if you have one) into the school directory admin/images. For example, /opt/openadmin/andrews/admin/images folder and name it logo.gif. It should already be in GIF format! You should replace/erase the existing files (logo.gif and logotn.gif). The new configuration logoadd script will allow you to set these logos from the web interface.

    The size of your logo.gif should be approximately 150-200 pixels high or so (and a reasonable width). Excessive width (more than 300 pixels or so) may cause layout problems on smaller screens. Pick a size that is pleasing when displayed on the main page. This should give a good starting point. A smaller version of the school logo (about 100 pixels high) should be saved and renamed to logotn.gif (Logo Thumbnail) This is the logo visible on the attendance, discipline, report card pages, etc. To conserve bandwidth, these should be as small as possible. The other 2 small image files tabactive.gif, tabmain.gif (total 2k in size) implement the menu system on the admin site.

  8. Edit the configuration file called admin.conf located in the school etc directory. For example, (/opt/openadmin/andrews/etc) This is read by all of the scripts (cgi, tcgi, pcgi) and is required to access the database, put in the right navigational links, etc. The new configuration system will rewrite these files automatically from the system configuration table ( conf_system ).

    Three important entries of the admin.conf configuration file are for user, database, and password. The user and password would be set when installing the database. More on this below. The fourth entry, dbtype selects whether you are using MySQL(mysql) or PosgreSQL (Pg). The rest of the entries in this file should be obvious from the comments around them. More on this below, also.

    There is also a file called studentnumber located in the school etc folder that stores the next available student number. This should be set once students have been imported into this system. It stores the next available student number. For small standalone schools, a 3 digit starting number would be a good choice (ie. 100). This is the default. Other files in this folder... term, receiptnumber must also be writeable by the webserver user.

    If you are installing multiple copies of openadmin for division schools, then blocks of numbers should be set aside for each school. There is currently no checking for overlap of numbers, so give each lots of room. This will give a unique student number to each student in the division, thus enabling easy data transfers and enabling use of the shared IEP system (which require unique student numbers for all students in that system and still requiring access back to their home school database).

    Make sure that the download folders in admin and tadmin for each school are writeable by the webserver user (the user the webserver runs as) so that scripts, which run with the same UID, can place created files there for downloading (mentioned above). A background script running daily (ie. a cron job) should be set to empty out these folders.

Step 3: Configure the Webserver

These are directions to set up the Apache2 webserver. If using other webserver software, you're on your own. Look for the virtual website documentation for that server. ( It should have name based virtual site capability rather than IP based virtual sites, although either method could be used. )

There are several basic variations on configuration depending on your version of Linux:

  1. Debian / Ubuntu - In these distros the Apache configuration files are located in /etc/apache2.

    Install the apache2 module to allow for mysql password authentication. The module is the libapache2-mod-auth-mysql one, installed with apt-get. Also make sure the module is active also.

    In the utility folder of your download, there is a file called apache2-debian.conf. Edit this file and search and replace the 'SCHOOLNAME' text into the folder name of your school (ie. andrews). As well, change the ServerName entries to the domain names for your websites. This should provide a good starting point for your school sites.

    Copy and Rename this file into /etc/apache2/ sites-available. Then create a symbolic link in the /etc/apache/sites-enabled folder to point to this file. Alternatively, just copy the file directly into sites-enabled.

  2. Red Hat and Friends - In these distros the Apache configuration files are located in /etc/httpd.

    In the utility folder of your download, there is a file called apache2-redhat.conf. Edit this file and search and replace the 'SCHOOLNAME' text into the folder name of your school (ie. andrews). As well, change the ServerName entries to the domain names for your websites. This should provide a good starting point for your school sites.

    Copy this file into /etc/httpd/conf and rename it with a school name (ie. andrews.conf). Then edit the httpd.conf file in the same folder. At the bottom of the file (where Virtual Sites are normally configured), add a line: Include conf/andrews.conf where andrews.conf is the name of the file renamed above. The text NameVirtualHost *:80 should also be added above the Include (if not present somewhere above the Include line). This turns on virtual hosting.

  3. Other Distros - More General Instructions

    The webserver settings are located in a file called httpd.conf. This file is normally located in the server's, etc/apache2 or /etc/httpd directories.

    The virtual websites are normally at the bottom of this file. External config files are the easiest way to configure OA, and can be pulled in with include statements in the httpd.conf. It would look like:

    NameVirtualHost *:80
    Include conf/myhttpd-school.conf
    Include conf/another-school.conf

    The NameVirtualHost directive turns on name based virtual hosting so that web browsers can send a site name in an http header and the webserver will provide a site based on that name.

    The conf folder in the Include statement is added since the include file is located relative to DocumentRoot, described below). Examples of this external file is found in the utility directory and are called apache2-xxxx.conf).

    Here is an example of an apache2-*.conf include file for St Peter School. It assumes that the NameVirtualHost *:80 has been placed in the main httpd.conf file before the Include statement that loads this school configuration file. It also includes teacher authentication from staff table rather than file.

    # Start of Admin Site
    <VirtualHost *:80>
       ServerAdmin root@localhost
       DocumentRoot /opt/openadmin/andrews/admin
       # Make .shtml files be parsed
       AddType text/html .shtml
       AddHandler server-parsed .shtml
       DirectoryIndex index.shtml
       ErrorLog /var/log/httpd/spa-error-log
       CustomLog /var/log/httpd/spa-access-log common	
       ScriptAlias /cgi-bin/ "/opt/openadmin/andrews/cgi/"
      <Directory /opt/openadmin/andrews/admin>
        Options +Includes  # turns on Server Side Includes (SSI)
          # to parse date (and user in teacher)
        AuthType Basic
        AuthName Admin
        AuthUserFile /etc/httpd/auth_users/andrewsadmin
        <Limit GET POST>
           require valid-user
      <Directory /opt/openadmin/andrews/cgi>
        AuthType Basic
        AuthName Admin
        AuthUserFile /etc/httpd/auth_users/andrewsadmin
        <Limit GET POST>
           require valid-user

    Some key points being:
    DocumentRoot: The path to your html files for this virtual site.
    ServerName: the name the virtual site should be identified as.
    ScriptAlias: where your perl (.pl) scripts are located for this site.

    The server side includes are turned on to process the main admin .shtml file so that it will corrrectly display the current date. This is done above with the "Options +Includes". This is also true of the teacher site to allow the Apache user to be seen.

    You can test this configuration with the Apache controller.

    apache2ctl configtest

    You may have to include it's full path, typically /usr/sbin/apachectl. It should respond with an OK. If not, fix the problem and try again. If all is well, then you may restart the web server. One method is:

    apache2ctl graceful

Setup Access Control

There are 2 methods to control access to these sites:

  1. File Access Control - files contain userid and password information that control access to particular site.

    The password file(s) that control access to the virtual site(s) are created using the htpasswd program. Currently this is only the main admin site since the teacher site can be configured to use the values in the staff table for authentication / authorization.

    A folder named auth_users must be created in /etc/httpd or /etc/apache2 (if it doesn't already exist) and the htpasswd program used to create entries in the auth_users/andrewsadmin file. Only these users will have access to the admin site. Normally only a few passwords are used for these sites. Read the man page for htpasswd program to see how to do this.

    The teacher site normally uses database authentication, but a file based authentication like the main admin site may be used also.

  2. Mysql Access Control - user information is read from the staff table. The file called apache2-teacherauth.conf in the utility folder contains the directory commands that may be copied in place of the teacher site directory commands in your school.conf ( andrews.conf ) file. This will allow teachers to log into the teacher site using their own userid and password. The mod_auth_mysql module will also have to be installed and working in your Apache installation, if not already installed.

Setup Log Files

Next are the log files which record site activity. The log files are very important to signal any problems or errors. In the event of white screens with nothing on them (Secretaries notice things like this... I call them WSOD... White Screens of Death),

Look at the Log Files!

Normally we create a /logs symbolic link to point to where the log files are actually located (ie. /var/log/apache2/). This simplifies the query for problems:

tail /logs/andrewsa-error.log - view main site error log.

Also note, that if doing updates, you can use symbolic links in Linux filesystems (Windows NTFS filesystems have limited symbolic link support, as far as I know. This would allow you to install an updated version of OA in a different folder and then use a symbolic link to point to this new folder, rather than another older folder. If you have installation problems (and your site is very active, as it normally is with school admin), you can quickly switch back to older code (as long as the table structures haven't changed with the newer version).

These directions assume that Apache has it's configuration installed in /etc/httpd or etc/apache2. These are the normal locations for most Unixlike operating systems.

Step 4: Set up MySQL

See the Installation Appendix for the PostgreSQL instructions if using that database engine.

I will assume that you have a basic installation of MySQL and that the MySQL engine is running. (If you're not sure, do a ps aux and you should see several mysql processes running). Normal installation of Linux should give you a working copy of this. You may also download and install versions from as well.

  1. Create a database for the application:

    mysqladmin create -pROOTPASSWORD myschool

    where rootpassword is the root password for the MySQL server (which is the not same thing as the root password for the entire computer) and myschool is the name of the database to be created. This is the name that will be placed in the /cgi/admin.conf file with $dbase = .

  2. Now create a non-root password for this school by using the mysql grant command. First go into the mysql client by typing:

    mysql -prootpassword -u root myschool

    Then type the following to create an entry so that you may use your own user and password to access the database:

    grant all on myschool.* to myuser@localhost identified by 'mypassword';

    where myschool is the name of the database, and myuser and mypassword are the user and password to get access to the program. They do not have to exist on the system as a real user, but are merely used by the scripts. These are the $user and $password variables in the admin.conf file. You can now use this userid and password to access your database.

    A new mysql identity (rouser - read only user) should be created that has only read (sql select) capability for that school's database. This is particularly important for use with the publicly accessible parent page/site that allows students and parents to view attendance, report and gradebook marks. Other scripts will use this as well.

    grant select on myschool.* to rouser@localhost identified by 'ropassword';

    where rouser and ropassword are the values also entered in the admin.conf configuration file for $rouser and $ropassword.

    A utility called mysql_setpermission can also be used to set access control, like the grant command.

    Another mysql identity (which I call global) with read capabilities for all of the school databases should be created, if using the SIS site (central office). This will allow a global user to read all of the school databases, but not change them. This is required for the central office application and some global view scripts.

  3. Create the database tables

    Run the following command using the file in the utility/sql folder of the download called blankxxx.sql. It contains the SQL statements necessary to create the entire database (where xxx is the latest version).

    mysql -pmypassword -u myuser myschool $<$blankxxx.sql

    If all went well, and no errors were shown, you should now have tables in your database, ready to accept records. You can verify this by doing a show tables command when in the mysql client.

    The meta table (data dictionary) is initially blank. The metaxxx.sql file in the utility/sql folder contains starting student and staff tables defaults for this. Run this just like you did for the blank.sql file above and it will put in defaults, etc. required by the templates used with these 2 tables for forms, etc.

    If you add more fields to the student and/or staff tables, then after doing so, you can update the meta table by running the Meta Update script located on the Start/End of Year page of the admin site ( See also the section on customizing OA ).

    If you are using the Special Needs application, it has a different database design. It is installed in the same fashion as outlined above, using the file called iepdataXXX.sql located in the utility/sql folder. It is inserted into an iep database (or whatever you would like to name it) created with mysqladmin (as above).

    The central office application also requires a database, but only for the reading system default values and the email groups system if using Google Educational domains. It mainly queries all of the schools (and iep if it exists) databases for data.

Your database setup it now complete.

Step 5: Converting Student Data

The student information can be uploaded from a CSV spreadsheet file using a new import script on the Export page of the main admin site called 'Import Student Records - CSV'. This is the easiest approach. Simply save your spreadsheet student information as a CSV file, first.

There is now a matching script that can also import staff information.

The following information outlines how to do student data imports using another utility script ( from the command line. It is more complex, but is more powerful since it can also munge the data and rearrange information within fields, etc.

The import script,, must be edited so that what the script expects matches the input file format. This kind of file format can be exported from various spreadsheet and database programs. If starting from scratch, it might be easiest to quickly type in required student information into a spreadsheet, and then import that ( either with or via the web import script on the Export page.

Run it (assuming your data file is mydata.csv) with:

./ mydata.csv

This should correctly put the students into the student table in the school database. In the event of errors, simply empty the student table and try again. You can do this with:

mysql -pmypassword -u myuser myschool

Once in the MySql client, enter the SQL command to empty the student table (without deleting it):

delete from student;

and try, try again. It will take a couple of times at least to get the data in a format that you like (or will accept). You can also edit the CSV file in a spreadsheet before importing it here to quickly get the data in the form that you would like.

Once you have imported student data, either using the simple import button or the complex studentupload script, set the etc/studentnumber file to the student number for the next student enrolled (as mentioned above). This will ensure that once the secretar(y/ies) start adding students, the student numbers are assigned starting with the next available number.

Step 6: Configuration

OA is configured by editing configuration files located in the etc folder of each school.

The main configuration file is called admin.conf and is read by all scripts from main admin (cgi), teacher (tcgi), and parent (pcgi). Setting correct values is very important since it affects all program operations.

The new configuration system will write these files from stored values in the system configuration table. Viewing the choices there will provide background about how to setup OA. The following section is left for now to see the options for the main setup.

New options are now placed at the top of the file, making it easier to edit the file when doing upgrades from previous OA versions.

# -- New in 3.50 ----
# password settings used by Crypt::GeneratePassword, also Data::Password
$password_minlen = 5;
$password_maxlen = 6;
$password_lang = 'en';
$password_signs = 0;
$password_caps = 1;
$password_minfreq = .001;
$password_avgfreq = .001;

#--- New in 2.50 ------------------------
# For translation purposes, this has to be in configuration...
#  Files now use this to display Months, Days of Week, etc.
@month = ('','January','February','March','April','May','June','July',
@s_month = ('','Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec');

@dow = ('','Sunday','Monday','Tuesday','Wednesday','Thursday','Friday','Saturday');
@s_dow = ('','Sun','Mon','Tue','Wed','Thu','Fri','Sat');

# Location of special ed config file in your filesystem
#  Actual filesystem location of the file ON YOUR SERVER.
$iepdir = '/opt/openadmin/iep';

# Paper Size: Letter, Legal, A4 (entered as: letterpaper, legalpaper, a4paper);
$defaultpapersize = 'letterpaper';

# ---- End of New Section for 2.50 ---------

# Basic Constants for the database
$user = 'USER';
$password = 'PASSWORD';
$dbase = 'DATABASE';
$dbtype = 'mysql';  # mysql or Pg (postgresql; watch case!)

# SQL Syntax settings for mysql or Pg.
$sql{default} = 'NULL';  # Change to DEFAULT for Pg.
$sql{like} = 'like'; # Change to ILIKE for Pg; case insensitive searches.

# Language Settings
$langcode = 'en';
$language = 'English';

# Full Text Name of School and Address 
$schoolname = 'YOURSCHOOL';
$schooladdr1 = 'Addr1';
$schooladdr2 = 'Addr2';
#$schooladdr3 = 'Addr3';
$schoolcity = 'City';
$schoolprov = 'Province';
$schoolpcode = 'Pcode';
$schoolphone = '(306) 123-4567';
$schoolfax = '(306) 123-4568';
$schoolemail = '';

# CGI areas - normal file paths; cgi is main admin, tchcgidir is teacher
# These are the pathnames ON YOUR SERVER! (not part of the URL)
$cgidir = '/opt/openadmin/YOURSCHOOL/cgi';
$tchcgidir = '/opt/openadmin/YOURSCHOOL/tcgi';
$parcgidir = '/opt/openadmin/YOURSCHOOL/pcgi';

# CGI URL's - for self referencing scripts
#  part of Apache configuration, not server filesystem.
$cgiurl = '/cgi-bin';
$tcgiurl = '/cgi-bin'; 

# Picture Directories and URL's
#  dir is actual filesystem pathname, url is apache config.
$picdir = '/opt/openadmin/YOURSCHOOL/admin/pic-big';
$picdirurl = '/pic-big';

# Picture area for thumbnails
$tndir = '/opt/openadmin/YOURSCHOOL/admin/pic-sm';
$tndirurl = '/pic-sm';

# Full path to download folders; used by scripts to copy files there.
# Actual pathname ON YOUR SERVER!
$downloaddir = '/opt/openadmin/YOURSCHOOL/admin/download';
$tchdownloaddir = '/opt/openadmin/YOURSCHOOL/tadmin/download';

# Web location of download (put into URL)
# Apache configured values. Part of the URL.
$webdownloaddir = '/download';
$tchwebdownloaddir = '/download';

# CSS File locations and name
$css = '/admin.css';
$tchcss = '/tadmin.css';
$parcss = '/padmin.css';

# Location of global config file to integrate school databases.
#  Actual filesystem location of the file ON YOUR SERVER.
$globdir = '/opt/openadmin/global';

# Path for PDFLatex Executable
$pdflatex = "/usr/bin/pdflatex";

# Administrator Contact Info; used by scripts for error contacts.
$adminname = "ADMIN";
$adminemail = "ADMIN\@YOURBOX";

# Return Address - address of school, or secretary/administrator
# Currently used by Sask SDS code for enrollment resolution.
$returnaddress = "SECRETARY\@YOURSCHOOL";

# Appended to top of generated HTML.
$doctype = "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01 Transitional //EN\" 

# Character Type
$chartype = '<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">';

# CSS Files - Webspace Links
$g_maincss = "<link type=\"text/css\" rel=\"stylesheet\" href=\"admin.css\">"; 
$g_tchcss = "<link type=\"text/css\" rel=\"stylesheet\" href=\"tadmin.css\">"; 

# Top Level HTML Pages - URL Links
$homepage = "/index.shtml";
$discpage = "/discipline.html";
$reppage = "/repcard.html";
$attpage = "/attendance.html";
$exppage = "/export.html";
$eoypage = "/eoy.html";
$schpage = "/schedule.html";
$feespage = "/fees.html";

$tchpage = "/index.shtml";

# Global Color Settings: used by gradebook groups
$g_color[0] = '#8FA';
$g_color[1] = '#FF8';
$g_color[2] = '#AAF';
$g_color[3] = '#F8F';
$g_color[4] = '#FFA';
$g_color[4] = '#FAF';
$g_color[5] = '#AFF';
$g_color[6] = '#FAA';
$g_color[7] = '#AFA';
$g_color[8] = '#AAF';
$g_color[9] = '#AAA';

# Attendance Settings for Periods per Day (ppd) for each grade.
# Put your grades in the curly braces and 
# the number of periods in the quotes.
$g_ppd{PK} = "2";
$g_ppd{K} = "2";
$g_ppd{1} = "2";
$g_ppd{2} = "2";
$g_ppd{3} = "2";
$g_ppd{4} = "2";
$g_ppd{5} = "2";
$g_ppd{6} = "2";
$g_ppd{7} = "2";
$g_ppd{8} = "2";
$g_ppd{9} = "2";
$g_ppd{10} = "2";
$g_ppd{11} = "2";
$g_ppd{12} = "2";

# The school year;
$schoolyear = "2010-2011";
$schoolstart = "2010-08-28";
$schoolend = "2011-06-27";

# School Terms
$g_termstart{1} = "2010-08-28";
$g_termend{1} = "2010-11-16";
$g_termstart{2} = "2010-11-19";
$g_termend{2} = "2011-03-07";
$g_termstart{3} = "2011-03-10";
$g_termend{3} = "2011-06-27";

# Days Per Cycle; only needed for Scheduling.
$daysPerCycle = 6; # assume a 6 day cycle.

# Dates to reset the 'dayInCycle' to throughout the year. If there are
# no reset values here, then the schoolstart value is assumed to be Day
# 1, and days loop through the cycle from there, omitting any dates set
# for the school year with a 'N' in the DayInCycle field (on Start/End
# of year page) under Date Management.

#$resetDate{'2010-08-31'} = 1;

# These are ONLY needed if your school is a K-12 school and
# has two (or more) different school term dates in same school.
# (ie. 3 terms for K-6, and 4 terms for 7-12). All programs support
# the structure above this ($g_termstart{1} = 'date') in any case.
# You may use other values rather than 'e' and 'h' as long as the 
# $g_termtype{Grade} = 'MyValue' matches  
# $g_termstart{MyValue}[TermNumber] = 'TermStartDate'

$multiTrack = 0; # 1=yes, 0=no

# Scripts supporting this date structure are: (repcard card
#  script... soon, then SDS scripts, etc.)

# $g_termstart{e}[1] = "2010-08-27";
# $g_termend{e}[1] = "2010-11-19";
# $g_termstart{e}[2] = "2010-11-22";
# $g_termend{e}[2] = "2011-03-28";
# $g_termstart{e}[3] = "2011-03-31";
# $g_termend{e}[3] = "2011-06-28";

# $g_termstart{h}[1] = "2010-08-27";
# $g_termend{h}[1] = "2010-11-19";
# $g_termstart{h}[2] = "2010-11-22";
# $g_termend{h}[2] = "2011-01-28";
# $g_termstart{h}[3] = "2011-01-31";
# $g_termend{h}[3] = "2011-01-28";
# $g_termstart{h}[4] = "2011-02-01";
# $g_termend{h}[4] = "2011-07-28";

# $g_termtype{K} = 'e';
# $g_termtype{1} = 'e';
# $g_termtype{2} = 'e';
# $g_termtype{3} = 'e';
# $g_termtype{4} = 'e';
# $g_termtype{5} = 'e';
# $g_termtype{6} = 'e';

# $g_termtype{7} = 'h';
# $g_termtype{8} = 'h';
# $g_termtype{9} = 'h';
# $g_termtype{10} = 'h';
# $g_termtype{11} = 'h';
# $g_termtype{12} = 'h';

# Saskatchewan Specific constants
$schoolnumber = "123456";
# An english stream program in Saskatchewan; used by export/sds program.
# Note that each student record also has a program code. This is just a 
# default so no need to add all records, unless special ed, etc.
$program = "10";
# Used by Saskatchewan SDS code to disable functions for non-native schools.
# Disables reserve residency, band affiliation, and treaty number xml updates.
$nativeschool = '0';

# Main controls for Sask Learning
$url = '';
$sds_userid = 'USERID';
$sds_password = 'PASSWORD';

$maxfilesize = 30000; # Max Filesize for transfers.
# SL has 32k limit for xml file transfers. Must be too big for oracle...
# 30k setting above it relatively safe limit. Don't go higher unless
#  you know what you're doing.

# SDS XML Schema Declarations
$xmlns = "";
$xmlnsxsi = "";
#---------- End of Sask Specific Constants ----------------

# --- Attendance Settings - currently used in teacher attendance entry.

my $g_maxterms = 12; # maximum # of terms to search for.
my $g_attendview = 16; # Number of previous attendance records to see;
my $g_teachview = 12; # Number of teacher attendance records to see.
my $g_allowedit = 1;  # Comment out to disable teacher editing of att records.

# Reason Categories.... the Unexcused ones, and Late/Absent Groups...
#  currently used by attendance profiles...
$absentUnexcused = 'Absent Unexcused';
$lateUnexcused = 'Late Unexcused';
$lateString = 'Late';
$absentString = 'Absent';

# Reasons for Attendance
# Note: "Absent" and "Late" MUST be used to be correctly tagged by reports.
#  Case is significant. We have several classes: Absent Unexcused; Absent
#   for a variety of reasons. (Absent Illness, Absent Moved, etc.). If 
#   excused but for another reason it's Absent Excused. Similar for Lates.

$attend[0]="Absent Unexcused";
$attend[1]="Absent Excused";
$attend[2]="Absent Illness";
$attend[3]="Absent Moved";
$attend[4]="Absent Suspension";
$attend[5]="Late Unexcused";
$attend[6]="Late Excused";

# Array to list reasons to ignore for perfect attendance; cgi/
@ignore_reason = (5, 6);

# Trigger Points Match Reasons Above.
# Values assigned to each type of missing attendance reason.

$points[0] = "3";
$points[1] = "0";
$points[2] = "0";
$points[3] = "0";
$points[4] = "0";
$points[5] = "1";
$points[6] = "0";

# Points => Discipline Event; 
# These numbers of points trigger a discpline event.
%trigger = ( 
	6 => 'Absence (Two)',
	12 => 'Absence (Four)',
	18 => 'Absence (Six)',
	24 => 'Absence (Eight)',
	30 => 'Absence (Ten)'

# A formletter file (in /cgi/forms) that matches trigger events above
# Generated by the Attendance Scan script (/cgi/
%formletter = ( 
	6 => 'discipline.tex',
	12 => 'discipline.tex',	
	18 => 'discipline.tex',	
	24 => 'discipline.tex',	
	30 => 'withdraw.tex'

# Ethnic values now stored in meta table as defaults.
# Religion Values now stored in meta table as defaults. - $g_religion

# Staff Member Positions; all globals vars start with g_

# Allows admin functions in Discipline system.
@g_posadmin = ('Principal','Vice-Principal');

# New functions in upcoming PTI system
$g_possped = 'Special Education Teacher';

$g_position[0] = "Classroom Teacher";
$g_position[1] = "Teacher Assistant";
$g_position[2] = "Special Education Teacher";
$g_position[3] = "Principal";
$g_position[4] = "Vice-Principal";
$g_position[5] = "Secretary";
$g_position[6] = "Librarian";
$g_position[7] = "Community School Room";
$g_position[8] = "Custodian";

# Needed by perl scripts to loading this config file.

Other Configuration Files in the etc directory:

  1. repcard.conf - a configuration file to control report card printing. Please read this file over carefully so that your report card prints correctly. This has lots of comments in it to explain the different features, which include: column spacing, show averages, show homeroom teachers, show school logo, number of terms to show, term descriptors, per grade evaluation keys, student placement text for year end report cards. Still missing: show per subject attendance.

  2. image.conf - a configuration file to control the student/staff images. It mainly contains limits on filesize uploads and resolution of created student images.

  3. schedule.conf - a scheduling system configuration file. Currently it only contains the period start and end times during the day

  4. transcript.conf - a configuration file for the transcript system.

  5. gbook.conf - gradebook configuration file.

The special education (IEP (Individual Education Program)) application has a similar script with common settings.

There is also a global configuration file ( nominally located in the school etc folder and called global.conf) that stores information about all of the schools on the local server (normally, that would be all participating schools in the division). This information is used to enable global reporting. This is used by central office for reporting as well as used by the schools to enable school transfers of demographic information. Once a secretary or admin in a school finds the student number of a withdrawn student, they can simply put that number into the normal entry/withdraw input box on the main page to register that student and have all demographic information transferred.

I've located the global config file in the school etc folder, and set the admin.conf configuration file to point to it's location there. This is because most installations are for single schools, not large division installs.

If you are doing a multiple school installation then move this file to a global folder at top level (ie. /opt/openadmin/global). Add all databases to it. Then edit all school admin.conf files so that their $globaldir setting points to this folder.

The Look and Feel of all school sites can be changed by simply changing the stylesheet files (.css) located in admin, tadmin, and padmin folders. Normally I just change the color scheme slightly to match colors in the school logos (ie. school colors). I do this by searching and replacing the #049 (RGB) with a color triplet matching the logo.

The scripts that generate webpage reports, etc. also use the same stylesheet so that this one file can control the overall look of the application. Currently, this has only been done to a very limited degree to make sure browser compatibility doesn't become an issue. As browser support continues, this will evolve.

The HTML pages are basically separate from the scripting, so that the look of all school sites can be changed extensively if desired by simply changing the html files and the CSS files. The only issue will be to maintain those elements in the CSS files used by the scripts to control report rendering, etc.

As well, within the stylesheets are settings to it hide the religion fields in the student table and also the high school functions in the SDS update section of the export page.

Step 7: Getting Started on the Browser Side...

From this point on, secretaries may take over, if desired. The following functions are on the Start/End of Year page (There is more about this in the User Documentation under Getting Started).

  1. Add your teachers and other staff members. For a teacher in a split situation (teaching 2 grades in the same classroom), add those 2 grades into the grade area, but with the same homeroom value. For jobsharing teachers, add each one separately with the same homeroom.

    In a middle years or high school (or with any subject specialists who only teach certain subjects such as music or foreign languages), the homeroom and grade fields are normally left blank. The teacher is grouped with students by their subject enrollment in his/her class.

  2. Enter school dates that school is not in session, Monday to Friday. This is located on the Start/End of Year page also.

    This includes any school holidays within the year and teacher inservices, etc. (The system automatically assumes that school is not in session on Saturday/Sunday). This should now correctly do attendance calculations, etc. The DayInCycle setting is used to mark those days that actually count in schools using different types of cycles (ie. 6 day cycles) for classes, even though the students may not be in class (ie. due to teacher professional development).

You are now ready to enter attendance, discipline, etc.

Install Appendix A - Setting up the PostgreSQL Database

(Courtesy of David Bandel)

Note (July, 2007): This section hasn't been updated in a while, so some options may have changed, etc. You're on your own with this since I have no test versions running pgsql any more.

Ensure you have installed the PostgreSQL server and associated tools (including plpgsql). Most distributions include PostgreSQL, but if not you can probably find binaries at the PostgreSQL site (

Make sure Postgres is running and starts on bootup. If running, you should find a postmaster daemon (ps ax | grep postmaster). If the postmaster process is not running, start it. If this is a new install, you may get an error. If so, you probably haven't initialized the database properly. See the Postgres instuctructions for running initdb.

These instructions assume you are running PostgreSQL as the user postgres, and that user is also the db administrator. If you don't understand the preceding sentence, please read the PostgreSQL documentation that came with your binaries or can be found on the PostgreSQL site.

  1. First, if you haven't installed the plpgsql language, do so:

    createlang -U postgres plpgsql template1

  2. Then, if you want better security, create a user for openadmin with a password:

    createuser -U postgres -P openadmin

    Allow the user to create new databases, but decline creating new users. The -U allows you to specify the user, -P prompts for a password. If you don't want your user to have a password (bad idea), omit the -P. It's also a good idea to add a password to your postgres admin user.

    Note: if your are refused a connection to your database in 1 or 2 above, check your pg_hba.conf file and change the lines:

    local all postgres ident sameuser
    local all all ident sameuser
    host all all ident sameuser


    local all postgres trust
    local all all trust
    host all all trust

    and restart your PostgreSQL server.

  3. Create the database (let's assume you chose openadmin as your username above):

    createdb -U openadmin myschool

  4. Now create the database tables:

    psql -U openadmin myschool <

    You will find the PostgreSQL schema in the utilities directory under the name

  5. Configure each school to use PostgreSQL. In etc/admin.conf under each school directory, ensure your dbtype line looks like this:

    $dbtype = 'Pg';

    The P is capitalized, the Pg is surrounded by single quotes, and the assignment ends with a semicolon. This paragraph is a change to the instructions as presented in Configuration, below.

  6. Ensure you run a backup script to backup your databases regularly. A Pg backup script is available for download.

    Modify your crontab thusly for a full nightly backup at 2 a.m.:

    0 2 * * * /root/ bva

    Remember to configure your backup script appropriately.

Install Appendix B - Setting Up Webname Resolution

You can set these website locations in individual computers in theirhosts files so that they can access these sites without any DNS (Domain Name) records being installed on your DNS server (that maps webnames to IP addresses). This can be quite useful in initial testing before any DNS updates have been done. On Linux workstations these are located in /etc/hosts. On Windows workstations (XP) these are found in:


Look on the wikipedia website ( under Hosts file.

The entries in the hosts files look like this for St. Peter: # admin site # teacher site # parent site

Using hosts files will help hide the virtual sites to some degree, since there will not be DNS records for them. However, they have to individually maintained. Also, in terms of security, avoid placing links to admin sites on school web pages. (security by obscurity). The next step up in security is the use of SSL to give encrypted connections to/from websites.

The DNS System

The webserver is setup for several virtual OA websites. You must setup your DNS records (on your DNS server) to match. These DNS names are set to point to the same server.

Let's assume that you are setting up the webserver and DNS for the Tiny School Division and they have a registered domain name for and a server located at called gandalf.

You would setup a DNS record to point to the server:

gandalf IN A

and also several aliases that also point to the same server:

spa IN	CNAME  gandalf	 - St Peter School Office Administration
spt IN	CNAME  gandalf	 - St Peter School Teacher Admin
spp IN	CNAME  gandalf	 - St Peter School Parent Site

bruna IN  CNAME	gandalf	 - Bruno School Office Administration
brunt IN  CNAME	gandalf	 - Bruno School Teacher Admin
brunp IN  CNAME	gandalf	 - Bruno School Parent Site

iep     IN  CNAME  gandalf  - Special Education Student Site
central IN  CNAME  gandalf - Central Office Site

Even though you are going to the same computer, the virtual hosting capabilities of the Apache web server will show you different websites (based on the name that you're looking for which is sent in the HTTP header).

The St Peter secretaries and administrators go to to enter attendance, etc. while teachers at St Peter would go to to print their classlists, etc. Parents could go to to see their children's attendance, reportcards and ongoing grades from the gradebook (where allowed). This would be similar for other schools running on this same server.

Central Office staff and special education teachers would go to to view special needs student programs. There is also a single central office application to show combined school enrollments, ethnic enrollments and other functions.

All these addresses are going to the same server. This is the basic idea behind this administration system. The entire school division can run from one medium performance server that can be housed and maintained at some central location. The parents site is not protected by a common password (since the scripts require individual passwords from parents), while the other two (per school) are protected by passwords stored in a file ( or database )for the main admin site and in the staff table for the teacher site.

next up previous contents
Next: How to Upgrade Open Up: Open Administration for Schools Previous: Contents