Helpdesk Programmers Guide

This is the Programmer's Guide for the f2w Helpdesk. It deals with installation and customisation, and explains the intention behind some of the design decisions that were made.

If you want to know how to use the helpdesk, see the User Guide. If you want to know how to administer the data, see the Administrator Guide.

Installation

The helpdesk software is in 2 main parts. There is an SQL database back-end which holds the data (currently implemented in PostgreSQL), and a web-based front-end that provides the user interface (currently implemented in Zope).

Both parts are available for free download from the project web-site, which is at http://sourceforge.net/projects/f2w. The database back-ends are named like "f2w-psql-version.tgz" and the zope front-ends are named like "f2w-version.zexp.gz". In general the latest front-end needs the latest database schema, although the release notes may indicate what needs to be done to patch an existing database to the new version.

These installation instructions are for version 1.5, as of September 2003.

Installing the Database

These instructions assume you have PostgreSQL, version 7.3 or above but preferably the latest stable release. If you want to use another database which works with Zope it should be possible, but you will have to do a lot of figuring out for yourself.

So far only Oracle and MS SQL are even nearly supported as an alternative to PostgreSQL - but not by me, as I have access to neither.

If you are installing on a Debian GNU/Linux system, note that f2w helpdesk is developed on the latest .deb in the "testing" distribution.

As the postgres user, create a user called "f2w" and an empty f2w database owned by user "f2w" thus:

$ createuser -P -d f2w		# NB: should prompt you for f2w user's password - I use "f2w"!
$ createdb -U f2w f2w

The most likely thing to go wrong at this stage is an error like this:

psql: FATAL:  IDENT authentication failed for user "f2w"

All that means is your pg_hba.conf file needs changing to allow you to be the "f2w" user. In that case, I recommend adding these lines near the start of the access rules:

local all f2w md5 host all f2w 127.0.0.1 255.255.255.255 md5

You will need to remember what password you gave user "f2w" of course. You can change it from psql with an ALTER USER f2w ENCRYPTED PASSWORD 'whatever'.

The next step is to create the tables, indexes, sequences and initial data for the database. Unpack the "f2w-psql-version.tgz" file. It unzips as a directory called "f2w" containing various SQL files.

To apply the SQL definitions to your new empty f2w database (as user f2w) do this:

$ cat *.sql | psql -U f2w f2w

You can now look at the database structure with a tool such as pgaccess or psql.

If you are upgrading from an earlier version of the f2w database schema, apply all the schema patches from the version you have up to the current version. These patches are just single SQL files, also available for download in the same place. They are named like "f2w-patch-version.sql".

If you want to use Oracle, then you don't need the "functions.sql" file, but you need the "z_initial.oracle" instead of "z_initial.sql" file (to work around a problem with empty strings being treated the same as NULLs). You may also need to fiddle with the SQL syntax a little to make it work.

Installing the Zope Front-end

You need Zope, preferably version 2.6 or higher. If you are installing on a Debian GNU/Linux system, note that f2w helpdesk is developed on the latest .deb in the "testing" distribution.

Until you are confident of getting Zope and another webserver to play nicely with each other, you might want Zope configured as a stand-alone webserver.

You also need Zope's ZPsycoPgDA product. This is available from the Zope.org website. Actually, you could use another Zope Database Adapter for PostgreSQL, but you may have to do a little extra work to get the helpdesk up and running. I used to use ZPoPyDA but there were problems once getting it to work with Zope 2.4.x. It's probably fine by now.

Once you get Zope running, you install the f2w helpdesk by un-gzipping the f2w-version.zexp.gz file into Zope's "import" directory. From the Zope management screens, import the file into the root folder (or wherever else you want it to live).

You may import Zope objects which have been previously exported to a file, by placing the file in the "import" directory of your Zope installation on the server. You should create the "import" directory in the root of your Zope installation if it does not yet exist.

Note that by default, you will become the owner of the objects that you are importing. If you wish the imported objects to retain their existing ownership information, select "retain existing ownership information".

Import file name
Ownership	Take ownership of imported objects Retain existing ownership information

Note: You DO want to take ownership of the imported objects, otherwise they will still belong to me, and they won't work properly. Sort of like getting your software from Microsoft, really :-)

It will create a folder called (for example) "f2w-1.5". You can re-name this to "f2w" or "helpdesk" or whatever, to keep your URLs tidy. I will just call the folder "f2w" in this document.

Oracle configuration

At this point, if you are using Oracle do the following things from the management screens:

Delete /f2w/f2w_db
Create an Oracle datbase connection instead, to the Oracle database you have set up with the f2w tables.
View /f2w/admin/config and hit the "Configure for Oracle SQL" button. This will copy over the default Postgres-specific SQL with Oracle equivalents, and set a few properties on the top level folder.

Users

The next stage is creating Zope users who are able to access the application. Click on the new folder you have just imported, and create an acl_users folder in it by choosing "User Folder" from the list at the bottom of the page. Click on the acl_users folder to begin adding users.

When you create a user, make sure you know what kinds of permissions they are to have. Zope has a flexible role-based access control system built in. Users who are to be allowed to modify the code of the helpdesk system should be given the role of "Manager".

I have added 2 extra roles "Admin" and "User". Anyone who will be operating the helpdesk e.g. taking calls and adding or annotating requests is a "User". Anyone who will be administering the data (e.g. creating new request categories or contacts etc) must have the "Admin" role. You can add extra "User" users from within f2w, but not "Admin" users, which have to be created through Zope's management screens.

Configuring for Oracle

If you are using Oracle as the back-end database you need to run the Python Script "configure_for_oracle" once, to set up some properties that will be used to work around the differences between Oracle and PostgreSQL.

Checking the Database Connection

In the f2w folder, there is an object called f2w_db. This is a ZPsycopgDA database connection, which by default is connected to database "f2w" as user "f2w". If you have such a database and the database connection is open, you are ready to go.

If you click on f2w_db, you should see something like this:

The database connection is open.

Translation / Localisation

As well as the f2w-version.zexp.gz file, there is another file called en-version.zexp.gz which can be used to localise the application for a different language or change some of the text of the application for other reasons.

The "en" folder contains English-language strings used to generate some of the pages. If it is imported at the same level as the "f2w" folder, and the f2w helpdesk is accessed using a URL like http://yourserver/en/f2w, these strings are available to the application and are used in preference to the defaults.

If you prefer a helpdesk request to be called a "Ticket", then change the property called "LLreq" on the "en" folder from "Request" to "Ticket", and include "en" on the URL as above.

Suppose you want an Esperanto version of the helpdesk. Copy the "en" folder as "eo" and translate all the properties and folder contents. Use http://yourserver/eo/f2w to access the helpdesk and Voila! (or, I suppose, Vidu!) - it's in Esperanto.

One good thing about this is that you can have multiple translations. You control which one you see by including it in the URL. If translations for any strings are missing, they are rendered as the default English version. I'm not sure if a multiple-language helpdesk is useful, but you can do it. Maybe it would go down well in Canada.

You can currently get translations in Hungarian and German. I'd like to attempt Catalan or Danish, but I would not do it well: if you love either of these languages, the best way to save them from me is to do a translation yourself!

The substitution of translated strings is implemented using Zope's acquisition rules and "missing=" option of the DTML-VAR tag. For example:

<dtml-var LLreq missing="Request">

It's still experimental at the moment, and you may find that some of the translatable strings haven't been separated out.

E-mail Installation

E-mail needs to be set up for the helpdesk to work properly. The MailHost object f2wmail needs to be pointing at a working SMTP mail server. If not, then any e-mail sent from the system will go astray or even cause errors.

I have mine set up thus:

Id	f2wmail
Title
SMTP Host
SMTP Port

And that's about it for installation. Point your web-browser at http://your-zope-url/f2w and you should see the welcome page.

Backup

For backup, you need to do 2 things: back up the Zope installation and back up the back-end database. I can't tell you the best way to do this, but I can tell you what I do, which seems to work.

To back up Zope, you only need to back up the Data.fs file where the Zope Object DB lives. I do this by copying it weekly to /var/backups/zope/Data.fs and letting logrotate keep a few historical snapshots of it.

To back up PostgreSQL databases, you use the pg_dump command. I back up the live f2w database daily as /var/backups/postgres/f2w.psql, and again let logrotate look after it. I also drop and re-create my test database f2w-test each time, and re-load it from the live backup.

Of course, you probably want to make physical backups too, on tape or CD, but how you do that is up to you.

The relevant section of my /etc/crontab looks like this:

# f2w database backup (note Zope needs shut down first to release f2w-test)
# on fridays, back up the ZODB while I'm at it. See logrotate.conf too.
50 2    * * 2-6 root    /etc/init.d/zope stop
00 3    * * 2-6 postgres  /usr/local/sbin/f2w-backup
05 3    * * 5   root    /bin/cp /var/lib/zope/var/Data.fs /var/backups/zope
10 3    * * 2-6 root    /etc/init.d/zope start

The script f2w-backup looks like this:

echo -n "Beginning " ; date
/usr/lib/postgresql/bin/vacuumdb -z f2w
pg_dump f2w > /var/backups/postgres/f2w.psql
dropdb f2w-test
createdb -U f2w f2w-test
psql -U f2w -d f2w-test < /var/backups/postgres/f2w.psql
echo -n "Ended " ; date

In order to drop the f2w-test DB, it has to have no open connections, which is mostly why I stop Zope for a few minutes while I do the backup.

My settings in /etc/logrotate.conf are as follows:

/var/backups/postgres/f2w.psql {
    daily
    nocreate
    compress
    delaycompress
    rotate 7
    missingok
}

/var/backups/zope/Data.fs {
    weekly
    nocreate
    compress
    delaycompress
    rotate 4
    missingok
}

Last updated 5 Sep 2003

Name	me

New Password
(Confirm)

Domains
Roles