Basic E-Learning Tool Set (BELTS)

File Release Notes and Changelog

Release Name: 1.0.0

Notes:
Release Notes for Release 1.0.0 of BELTS
========================================

This is Version 1.0.0 of BELTS. It is provided as a compressed tar file.

Before Installing
================= 

The Basic E-Learning Tool Set is a sophisticated web-based application. The 
software should be installed and configured by an experienced technician. 
Technicians should be experienced in securing and administering web and 
database servers. These instructions only relate to the installation of the 
BELTS application onto an existing preconfigured operating system. Failure 
to properly configure the host machine could result in an unsecured device 
on your network. 

Education institutions should be aware of the software distributions they 
are using. All software should be tested and control of distributions 
maintained. 

Upgrading
=========

If you are upgrading from a pre-release version of BELTS, you will need to
remove your existing database and Storage directory and then follow the
installation steps outlined below.

Installation
============

Instalation differs slightly depending on whether you are installing on Windows
or Linux. Please follow the installation directions below for your
operating system.

Windows Installation
====================

Installation of this release requires a working version of postgres 
running on your machine, as well as a current 1.4 version of the Java 
Development Kit. The JAVA_HOME environment variable should be set to the 
home directory of your JDK installation.

Postgres Installation
---------------------

Postgres installation currently requires that the Cygwin environment is
installed. A copy of postgres is included in that environment. To install
this, go to http://www.cygwin.com and select the "Install" link. Ensure that
postgres is invluded in the list of packages to download. Once the Cygwin
environment is installed, add its bin directory (e.g. c:\cygwin\bin) to your
PATH and reboot.

The following steps are required to get postgres working. These notes are
a copy of what is at
http://www.tishler.net/jason/software/postgresql/postgresql-7.3.2.README.

Follow these directions in the exact order specified, as the setting of
permissions can cause problems if not done correctly.

Install:

There are two types of Cygwin PostgreSQL installations -- basic and NT
services.  The basic installation is good for casual use on any version of
Windows, but required on Windows 9x/Me.  The NT services installation is
good for a more production environment, but is only available on Windows
NT/2000.  Note that this installation type is very similar to the normal
Unix installation with just some Cygwin/Windows variations.  You should
choose the type which best meets your needs and/or is constrained by your
platform.

Regardless of the installation type, the first step is to install the
latest cygipc from:

    http://www.neuro.gatech.edu/users/cwilson/cygutils/cygipc/index.html

*and* start the cygipc ipc-daemon.  If ipc-daemon is not running or a
version previous to 1.13-2 is running, then initdb and postmaster will
fail with the error message:

    IpcSemaphoreCreate: semget(...) failed: Function not implemented

and

    IpcMemoryCreate: shmget(...) failed: Function not implemented

respectively.  Note with Cygwin PostgreSQL 7.2.3-1 and previous versions,
initdb and postmaster would hang, consuming all available CPU cycles if
ipc-daemon was not running.

The following is the basic Cygwin PostgreSQL installation procedure:

1. Start the cygipc ipc-daemon:

    $ ipc-daemon &

2. Initialize PostgreSQL:

    $ initdb -D /usr/share/postgresql/data

3. Start the PostgreSQL postmaster:

    $ postmaster -D /usr/share/postgresql/data &

4. Connect to PostgreSQL:

    $ psql template1

The following is the NT services Cygwin PostgreSQL installation procedure
(with footnotes designated by "[n]"):

1. Install the cygipc ipc-daemon as a NT service:

    # ipc-daemon --install-as-service

2. Create the "postgres" user account:

    # net user postgres $password /add /fullname:postgres /comment:'PostgreSQL user account' /homedir:"$(cygpath -w /home/postgres)" # [11]
    # mkpasswd -l -u postgres >>/etc/passwd

3. Grant the "postgres" user the "Log on as a service" user right:

    # cmd /c secpol.msc # [3] [4] [5]

4. Install postmaster as a NT service:

    # cygrunsrv --install postmaster --path /usr/bin/postmaster --args "-D /usr/share/postgresql/data -i" --dep ipc-daemon --termsig INT --user postgres --shutdown # [6]

5. Create the PostgreSQL data directory:

    # mkdir /usr/share/postgresql/data

6. Change ownership of the PostgreSQL data directory:

    # chown postgres /usr/share/postgresql/data # [10]

7. Start the cygipc ipc-daemon:

    # net start ipc-daemon # [7]

8. Initialize PostgreSQL (*when running under the "postgres" account*):

    $ initdb -D /usr/share/postgresql/data

9. Start postmaster:

    # net start postmaster # [7]

10. Connect to PostgreSQL:

    # psql -U postgres template1 # [8] [9]

The following are the notes to the above:

[1] The "#" prompt indicates running as a user which is a member of the
    Local Administrators group.
[2] The "$" prompt indicates running as the "postgres" user.  Log in as
    "postgres" or use ssh to emulate Unix's "su" command.
[3] Sorry, but I don't know of a generally available command line way of
    setting user rights.
[4] On Windows 2000, this starts the "Local Security Settings" applet.
    On Windows NT 4.0, do the analogous operation.
[5] See http://support.microsoft.com/default.aspx?scid=KB;en-us;q259733 for
    a Microsoft KB article explaining how to configure user rights.
[6] Clean postmaster shutdown will only work with a post Cygwin 1.3.2
    snapshot from 2001-Jul-28 or later.
[7] Cygwin's bin directory (e.g., C:\Cygwin\bin) must be added to the
    Windows NT/2000's system PATH and the machine rebooted for the SCM
    to find cygwin1.dll.
[8] Actually, psql can run under any user account.
[9] One can use PostgreSQL's createuser command or set PGUSER to obviate
    the need to specify "-U postgres" on the psql command line.
[10] Assumes that ntsec is set via the CYGWIN environment variable.
[11] $password is the password for the postgres user account.

Homepage:

The primary PostgreSQL web site is:

    http://www.postgresql.org


BELTS Installation
------------------

Once postgres is installed, BELTS can be installed by extracting the 
downloaded file and performing the following steps:
 
1. Use 'createuser' to create a postgres user called 'belts'. This user 
noes not need to be able to create databases or users. The password for 
the belts user is currently set to 'verysecret'. If desired, this can be 
changed by updating belts-1.0.0/server/belts/deploy/postgres-service.xml.

        createuser --username=postgres --password

2. Create the belts database

        createdb --username belts belts

3. Create the database tables by running the setup script in 
belts-1.0.0/server/belts/setup.

        cd belts-1.0.0\server\belts\setup
        setupdb

4.  Create the Storage directory used for downloading learning objects and 
storing search information.  These default to directories in \var\lib\belts
on the BELTS installation drive, but can be changed by modifying the
appropriate entries in 
   belts-1.0.0\server\belts\deploy\belts-services.sar\META-INF\jboss-service.xml.

Note that there are currently three entries in this file that need to be 
changed.  

	mkdir \var\lib\belts
	 
Note that you will need to create this directory on the same drive as the 
BELTS installation under Windows.

5. Setup your Mail Dispatcher Service

In belts-1.0.0\server\belts\deploy\belts-services.sar\META-INF\jboss-service.xml, 
find the lines describing the SMTPMailDispatcherService and adjust them to 
your settings.  For example, the BELTS demo site at Jacus uses the following: 

    <mbean name="belts:service=SMTPMailDispatcherService" code="au.edu.educationau.belts.management.mail.SMTPMailDispatcherService">
        <attribute name="Sender">jacus-belts@jacus.com.au</attribute>
        <attribute name="Prefix">Belts</attribute>
        <attribute name="ServerName">localhost</attribute>
    </mbean>

In this configuration, mail is sent by localhost and comes from 
jacus-belts@jacus.com.au.  Mail sent by this host is prefixed with Belts 
so it is obvious where the mail came from.  

6. Setup your Learning Exchange connection

In belts-1.0.0\server\belts\deploy\belts-services.sar\META-INF\jboss-service.xml, 
find the configuration lines describing the LearningExchangeClient and 
adjust them to include your username and password.  The default values for 
these are set to "changeme". If you require a proxy, set those values also.

        <mbean
                name="belts:service=LearningExchangeClient"
                code="au.edu.educationau.belts.management.repository.LearningExchangeClient"
        >
        <depends>jboss.mq.destination:service=Queue,name=belts-download</depends>
                <depends>jboss.mq:service=InvocationLayer,type=OIL</depends>
                <attribute name="JndiName">belts/belts-repository</attribute>
                <attribute name="URL">http://lex.thelearningfederation.edu.au/webservices/LearningExchange.asmx</attribute>
                <attribute name="ProxyHost"></attribute>
                <attribute name="ProxyPort">-1</attribute>
                <attribute name="Username">changeme</attribute>
                <attribute name="Password">changeme</attribute>
                <attribute name="QueueName">queue/belts-download</attribute>
                <attribute name="LastDownloadFile">/var/lib/belts/repository-last-download.txt</attribute>
        </mbean>

7. Start the BELTS server

        cd belts-1.0.0/bin
        belts

The server takes around 1 or 2 minutes to startup depending on the 
hardware it is running on.
 
If you wish to have the server started as a Windows service, run the 'install'
batch file. The service will be started automatically the next time the machine
is booted or you can run 'net start belts' to start it immediately. To remove
the service, run the 'uninstall' batch file.


Linux Installation
==================

Installation of this release requires a working version of postgres 
running on your machine, as well as a current 1.4 version of the Java 
Development Kit. The JAVA_HOME environment variable should be set to the 
home directory of your JDK installation.

Postgres Installation
---------------------

Ensure postgres is installed in your Linux environment by using the appropriate
tool for your distribution to install it. Once installed, there is often no
need to change anything to get BELTS to work successfully.

BELTS Installation
------------------

Once postgres is installed, BELTS can be installed by extracting the 
downloaded file and performing the following steps:
 
1. Use 'createuser' to create a postgres user called 'belts'. This user 
noes not need to be able to create databases or users. The password for 
the belts user is currently set to 'verysecret'. If desired, this can be 
changed by updating belts-1.0.0/server/belts/deploy/postgres-service.xml.

        createuser --username=postgres --password

2. Create the belts database

        createdb --username belts belts

3. Create the database tables by running the setup script in 
belts-1.0.0/server/belts/setup.

        cd belts-1.0.0/server/belts/setup
        setupdb.sh

4.  Create the Storage directory used for downloading learning objects and 
storing search information.  These default to directories in /var/lib/belts,
but can be changed by modifying the appropriate entries in 
   belts-1.0.0/server/belts/deploy/belts-services.sar/META-INF/jboss-service.xml.

Note that there are currently three entries in this file that need to be 
changed.  

	mkdir /var/lib/belts
	 
5. Setup your Mail Dispatcher Service

In belts-1.0.0/server/belts/deploy/belts-services.sar/META-INF/jboss-service.xml, 
find the lines describing the SMTPMailDispatcherService and adjust them to 
your settings.  For example, the BELTS demo site at Jacus uses the following: 

    <mbean name="belts:service=SMTPMailDispatcherService" code="au.edu.educationau.belts.management.mail.SMTPMailDispatcherService">
        <attribute name="Sender">jacus-belts@jacus.com.au</attribute>
        <attribute name="Prefix">Belts</attribute>
        <attribute name="ServerName">localhost</attribute>
    </mbean>

In this configuration, mail is sent by localhost and comes from 
jacus-belts@jacus.com.au.  Mail sent by this host is prefixed with Belts 
so it is obvious where the mail came from.  

6. Setup your Learning Exchange connection

In belts-1.0.0/server/belts/deploy/belts-services.sar/META-INF/jboss-service.xml, 
find the configuration lines describing the LearningExchangeClient and 
adjust them to include your username and password.  The default values for 
these are set to "changeme". If you require a proxy, set those values also.

        <mbean
                name="belts:service=LearningExchangeClient"
                code="au.edu.educationau.belts.management.repository.LearningExchangeClient"
        >
        <depends>jboss.mq.destination:service=Queue,name=belts-download</depends>
                <depends>jboss.mq:service=InvocationLayer,type=OIL</depends>
                <attribute name="JndiName">belts/belts-repository</attribute>
                <attribute name="URL">http://lex.thelearningfederation.edu.au/webservices/LearningExchange.asmx</attribute>
                <attribute name="ProxyHost"></attribute>
                <attribute name="ProxyPort">-1</attribute>
                <attribute name="Username">changeme</attribute>
                <attribute name="Password">changeme</attribute>
                <attribute name="QueueName">queue/belts-download</attribute>
                <attribute name="LastDownloadFile">/var/lib/belts/repository-last-download.txt</attribute>
        </mbean>

7. Start the BELTS server

        cd belts-1.0.0/bin
        belts console

The server takes around 1 or 2 minutes to startup depending on the 
hardware it is running on.

Other options to the belts command are:
	belts start (runs BELTS in the background)
	belts stop (stops the background BELTS process)



Accessing BELTS
===============

BELTS can be accessed by loading a web browser and going to 
http://localhost:8080/ if you are accessing it from the machine it is 
running on. If it is running on another machine, replace 'localhost' with 
the name of that machine.

The sample data created by running setupdb contains the following users:

test-administrator-1 - a system administrator
test-school-admin-1 - a school administrator
test-teacher-1 - a teacher
test-student-1 - a student

All of these users are given an initial password of 'belts'.

Known Useability Behaviour
==========================

Tabbing Behaviour on Netscape 6.2 Edit Lesson Screen

When Tabbing through the edit lesson section in Netscape the tab order is 
as expected until the focus reaches the "Upload File" box.  Successive 
tabs from here and the focus remains on this box.  


Tabbing Behaviour on Netscape 6.2 Login Screen

It is not possible to tab from the Netscape URL bar to the input and login 
fields on the login screen.  


Login Behaviour after Timeout

After opening up a new login page then after this has been left for a 
period of time then a timeout is activated.  This means that it is no 
longer possible to login until a new page refresh has been activated on 
the login screen.  


Menu Differences IE and Netscape

In IE the icon at the side of the menus do not drive any functional links 
and just the area where the text leads up to can be selected.  The full 
icon area and menu space area is selectable to drive functionality in 
Netscape.  


Learning Objects not viewable in Netscape 7

Not all learning objects currently in the BELTS repository currently work 
when viewed through BELTS in Netscape 7.  A current workaround is to 
download objects locally and run them accordingly.  


Non Searchable Test User Data

If an set of test users is provided then they may not be available for 
searches, as they will probably not be indexed correctly.  All new users 
and edited users will be searchable.  


Logging into Disabled Accounts/Users/Schools

It is possible to login to accounts that have been disabled for a small 
period of time after the disablement occurs.  The same caching issue also 
means that it is possible to login with an old password within a small 
period of time after the change has been made.  


Adding URLs to Lessons

When adding URLs to lessons then the behaviour of the Add button is such 
that it needs to be tabbed onto or clicked on by the mouse.  If entry is 
purely by keyboard with the entry of an Enter button afterwards then the 
URL will not be added to the lesson.  This usability problem is restricted 
to the IE browser series.  Netscape 6.2 has no such problem.  


Websites viewed when in Lessons

When URLs are incorporated into lessons then they DO NOT open new windows.  
As such the lesson surrounding buttons will be lost in this situation.  As 
a workaround it is suggested that either the URL selected is opened in a 
new window, or that after the completion of a website task that the user 
navigates to the relevant place within the lesson.  


Recommended Viewing Area

Learning objects in IE are scalable and hence the more viewing area 
available on the screen then the bigger they will be.  It is suggested 
that if the available viewing area is not large enough then all of IEs 
navigational menus can be hidden and the objects will display in a larger 
more viewable screen area.  (F11 Toggles Full Screen Mode in an IE 
Browser).  

Objects in Netscape 6.2 don't Scale to fill viewing area.

Learning objects viewed in Netscape 6.2 do not scale.  As such they are a 
fixed viewing size, best viewed at 800 by 600 resolution.  


Search the Exchange Selection of Radio Button

In The search the Exchange area of the site it is possible to select a 
radio button and enter search details in a different area than applied or 
inferred by the radio button.  

Searches within BELTS are Case sensitive

Exact casing is required when searching for specific keywords contained 
within the metadata of objects.  

Learning Objects containing internal Close calls

If you are viewing a learning object within a lesson and this has an 
internal Close call then this will close the object and any external 
navigation linked to the LO navigational view.  As such it is recommended 
that to utilise the full lesson view sequence that individual objects 
should not be closed.  


Macintosh Netscape 6.2 Navigation

It is not possible to tab into any of the menus or side navigation for 
Privacy, TS and Cs , About and Copyright screens when using a Macintosh 
Netscape 6.2.  

Non-Javascript Browsers

For non Javascript browsers then new windows will not open associated with 
viewing objects etc.  As such, all browsing will be contained in the same 
window.  That said the user should not use the Close window option in 
either BELTS or within the object itself or the entire user session will 
be lost.  

Configuring The Viewing Area for Netscape 6
===========================================

The Viewing area for Netscape 6 is a set display area.  This is due to the 
non-scalability of objects within this particular browser because of a 
browser limitation.  Depending on your setup and/or preferred screen 
resolution then you may want to alter the display area for the objects.  

The change needs to be made to an xslt file located in:

$BELTS_HOME/server/belts/deploy/belts.ear/belts-web.war/xsl/object-width.xslt

Simply modify the settings for Pixel width and height as appropriate to 
your needs.  Any edit to this particular file should not be performed 
unless the user is familiar with xslt.  Incorrectly editing this file will
break the entire server.  i.e.  no pages will be served.  

Potential Problems
==================

When attempting to view an object then nothing is displayed (A blank/white 
viewing area is displayed).  Some browsers (eg Internet Explorer) will 
automatically detect that this is the case and will direct you to an 
install.  Others (eg Netscape) will simply remain as a blanc white screen.  

The likely problem here is that your browser does not have the correct 
plug-ins installed to display the particular object you are trying to 
view.  Resolution: Depending on the object type then the likely fix to 
this is to visit the website http://www.macromedia.com/downloads/.  At 
this site you should download both the latest version of Macromedia Flash 
Player and Macromedia Shockwave Player.  Before running each of these 
files it is recommended to shutdown all instances of your browser before 
running each install.  

Known Issues
============

For an up to date track of known issues within the project please check 
out the Jira issue tracking for the BELTS project: 
http://jira.thelearningfederation.edu.au/jira/secure/BrowseProject.jspa?id=10010 



Changes: