<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<book id="index">

  <title>HelpmeICT - Helpdesk Issue Manager v0.71</title>

  <bookinfo>
    <author>
      <firstname>Dave</firstname><surname>Thorne</surname>
    </author>
    <copyright>
      <year>2003</year>
      <holder>Dave Thorne</holder>
      <holder>Central Manchester CLC</holder>
    </copyright>
  </bookinfo>

  <preface id="disclaimer">
    <title>Disclaimer</title>
    <para>
      This documentation is currently being written and so is not yet finished. For an up-to-date
      version of documentation please visit our
      <ulink url="http://helpdesk.centralmanclc.com/docs/index.html">online documentation</ulink>.
    </para>
  </preface>

  <chapter id="introduction">
    <title>Introduction</title>
    <sect1 id="what">
      <title id="what.title">What is the system?</title>
      <para>
        If you currently run a job based helpdesk of some sort, this system will make your life
        easier. By <quote>helpdesk</quote> I mean a service whereby requests are made by a number of
        clients to a number of support agents. The requests could be for anything, and the
        following list shows examples of such systems.
      </para>
      <itemizedlist>
        <listitem>
          <para>
            An ICT helpdesk within an organisation where a number of techincally trained staff
            are supporting a large user base.
          </para>
        </listitem>
        <listitem>
          <para>
            The maintenance crew of a building or organisation who require some sort of logging
            system for all their jobs.
          </para>
        </listitem>
        <listitem>
          <para>
            Education assistants in an education institution such as a school, where the teachers
            request help from a central group of assistants.
          </para>
        </listitem>
      </itemizedlist>
      <para>
        In fact, as this system is effectively a work flow manager, any such organisational unit
        that works in this way could benefit.
      </para>
    </sect1>
    <sect1 id="domains">
      <title>Domains - Functional Diversity</title>
      <para>
        This system can be slpit into any number of functional <quote>domains</quote>. Each domain
        would map to specific implementations of the system (as seen in the example list found in
        <link linkend="implementations" endterm="implementations.title"></link>) but which would potentially
        share the same user base. This means an organisation such as a school could have an
        ICT helpdesk, a maintenance helpdesk, and a departmental teaching assistance helpdesk all
        running on the same instance of HelpmeICT. The three helpdesks would share the same
        user base (i.e. the teachers and staff) but as they are doing fundamentally different
        jobs they deserve their own domains. Each domain is partitioned so that no information
        (other than that of users) is transferrable between them, keeping them very seperate
        entities.
      </para>
      <para>
        Domains help you have <quote>diversity</quote>, that is many different functions
        housed under the same server. Do not get that confused with scale of implementation.
        If your helpdesk is simply a very large helpdesk with many different sites, each with
        their own hierarchy of support agents, then bare in mind that one domain would suffice
        for your needs. To deal with scale you should read the following chapter and learn about
        <link linkend="sites" endterm="sites.title"></link>.
      </para>
    </sect1>
    <sect1 id="sites">
      <title id="sites.title">Sites - Scaling the System</title>
      <para>
        Each domain can consist of one or more sites. Sites can be used to distinguish between
        geographically distinct areas that are serviced by the helpdesk, or maybe just different
        departments within the same building. The crucial point to make is that clients and
        support agents (and every other type of user in the system - see
        <link linkend="users" endterm="users.title"></link>) are allocated their access on a
        site by site basis. As such, a client of one site does not have to be a client of all
        sites. This means that for a large helpdesk that is internally partitioned with different
        teams supporting different sites can be implemented simply with one domain split into
        a number of sites.
      </para>
      <para>
        This allows for the system to be used for anything from a single support agent
        supporting a single client up to a city wide educational ICT helpdesk supporting a large
        number of schools and consisting of complex heirarchies of staff. That's the plan anyway!
      </para>
    </sect1>
    <sect1 id="levels">
      <title>Levels - Escalating Issues</title>
      <para>
        The concept of levels of support is something that is common to many different
        implementations. In practice, this could be used to partition different levels of support
        such as first line and second line support in an ICT helpdesk.
      </para>
    </sect1>
    <sect1 id="users">
      <title id="users.title">Users - The Life Blood</title>
      <sect2 id="usercategories">
        <title id="usercategories.title">Access Types</title>
        <para>
          The most important part of any system is the user base, and it is important to
          accomodate as many users as possible. This system splits the user base into six
          specific access types, each with its own abilities and access rights. Each user, as
          described above is associated with a certain set of sites, and to each of those sites,
          the user is associated with a different access type. The list is as follows:
        </para>
        <itemizedlist>
          <listitem>
            <para>
              <literal>Client</literal> - A client is your end user, the person your system is
              supporting.
            </para>
          </listitem>
          <listitem>
            <para>
              <literal>Site Contact</literal> - A site contact is a privileged client who is
              allowed more of an overview of the system's state. This would be analagous to
              a department head - someone with a vested interest in the issues within those
              sites. They also have access to reset the passwords of all the clients below them
              in the sites they are associated with.
            </para>
          </listitem>
          <listitem>
            <para>
              <literal>Support Agent</literal> - The support agent with the responsibility for
              resolving submitted issues. The can manage issues and reset passwords for clients
              and site contacts below them.
            </para>
          </listitem>
          <listitem>
            <para>
              <literal>Administrator</literal> - The support agent with the responsibility for
              assigning other users to appropriate sites. This user administration is restricted
              to the sites they have 'Administrator' access to.
            </para>
          </listitem>
          <listitem>
            <para>
              <literal>Domain Administrator</literal> - The administrator with the responsibility
              for setting up the system. They have the ability to fully configure a domain's
              levels, priorities, statuses and categories. They can also carry out user
              administration for the whole domain.
            </para>
          </listitem>
          <listitem>
            <para>
              <literal>Root</literal> - The root user, used to configure the very high level
              settings of the system such as the domains in the system. The root user can
              configure everything in the entire system across all domains and all sites, but
              has no access to the actual issues within the domains.
            </para>
          </listitem>
        </itemizedlist>
        <para>
          User administration is cascading, and so all users can administer the users below them.
          For example, site contacts can administer the clients below them in their sites; support
          agents can configure all site contacts and clients below them for their sites; and so on.
          This delegation of user administration makes the day to day running of the system a little
          easier, ensuring not to swamp the support agents with trivial password change requests
          that can be carried out by site contacts.
        </para>
      </sect2>
      <sect2 id="userrights">
        <title id="userrights.title">What can those Access Types do?</title>
        <para>
          The following table shows the abilities of each access type.
        </para>
        <table frame="all">
          <title>Privileges</title>
          <tgroup cols="7" align="left" colsep="1" rowsep="1">
            <thead>
              <row>
                <entry valign="bottom">Issue Privilege</entry>
                <entry>Client</entry>
                <entry>Site Contact</entry>
                <entry>Support Agent</entry>
                <entry>Administrator</entry>
                <entry>Domain Administrator</entry>
                <entry>Root</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>Submit an issue</entry>
                <entry>Yes - but cannot specify priority or assignee</entry>
                <entry>Yes - but cannot specify assignee</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>No</entry>
              </row>
              <row>
                <entry>View an issue</entry>
                <entry>Your own issues</entry>
                <entry>Your sites' issues</entry>
                <entry>Your sites' issues</entry>
                <entry>Your sites' issues</entry>
                <entry>Your sites' issues</entry>
                <entry>No</entry>
              </row>
              <row>
                <entry>Revoke an issue submitted by you</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>No</entry>
              </row>
              <row>
                <entry>Edit an issue</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>No</entry>
              </row>
              <row>
                <entry>Remark on an issue</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>No</entry>
              </row>
              <row>
                <entry>Find an issue</entry>
                <entry>From your issues</entry>
                <entry>From your sites' issues</entry>
                <entry>From your sites' issues</entry>
                <entry>From your sites' issues</entry>
                <entry>From your sites' issues</entry>
                <entry>No</entry>
              </row>
              <row>
                <entry>Be assigned to an issue</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>No</entry>
              </row>
              <row>
                <entry>View statistics</entry>
                <entry>No</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>No</entry>
              </row>
              <row>
                <entry>View reporting</entry>
                <entry>No</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>No</entry>
              </row>
              <row>
                <entry>Change personal preferences</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>No</entry>
              </row>
              <row>
                <entry>Change personal details</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
              </row>
              <row>
                <entry>Casdcading user admin</entry>
                <entry>No</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
              </row>
              <row>
                <entry>Site admin</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
              </row>
              <row>
                <entry>Problem Category admin</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
              </row>
              <row>
                <entry>Level admin</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
              </row>
              <row>
                <entry>Priority admin</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
              </row>
              <row>
                <entry>Status admin</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
              </row>
              <row>
                <entry>Public Notice admin</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>Yes</entry>
                <entry>Yes</entry>
              </row>
              <row>
                <entry>Domain admin</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>No</entry>
                <entry>Yes</entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>
        </para>
      </sect2>
    </sect1>
  </chapter>

  <chapter id="initialinstall">
    <title>Initial Installation</title>
    <sect1 id="gettingthedist">
      <title>Getting hold of the distribution</title>
      <para>
        The Helpdesk Issue Manager is available free of charge from the project
        homepage at sourceforge
        (<ulink url="http://helpmeict.sourceforge.net/">http://helpmeict.sourceforge.net/</ulink>).
        The project is released under the
        <ulink url="http://www.gnu.org/licenses/licenses.html#GPL">GNU Public License</ulink>,
        and as such can be freely downloaded and modified under the terms of that
        license. Current distributions come in a single downloadable gzipped tar file.
      </para>
      <para>
        The first thing you need to do is create a new directory in which to put the downloaded
        file. This could be anywhere you have access to, but bare in mind it will eventually hold
        your documentation and related files. The best bet would be to put it somewhere in your
        home directory. Secondly you need to unpack the distribution using the following command:
      </para>
      <programlisting>
#> tar xvzf helpdesk_archive_file.tgz</programlisting>
      <para>
        You will now find yourself with the following in your chosen directory.
      </para>
      <itemizedlist>
        <listitem>
          <para>
            <filename>LICENSE</filename> - A copy of the GNU Public License terms.
          </para>
        </listitem>
        <listitem>
          <para>
            <filename>INSTALL</filename> - An overview of the installation.
          </para>
        </listitem>
        <listitem>
          <para>
            <filename>README</filename> - A quick pointer to where to start.
          </para>
        </listitem>
        <listitem>
          <para>
            <filename>database.sql</filename> - The database definition script.
          </para>
        </listitem>
        <listitem>
          <para>
            <filename>docs/</filename> - This documentation.
          </para>
        </listitem>
        <listitem>
          <para>
            <filename>web-tree.tar</filename> - An archive of the PHP scripts.
          </para>
        </listitem>
      </itemizedlist>
      <para>
        Read on to find out what to do with them.
      </para>
    </sect1>
    <sect1 id="phpscripts">
      <title id="phpscripts.title">PHP scripts</title>
      <sect2 id="unpacking">
        <title>Unpacking the scripts</title>
        <para>
          To install the php scripts, simply untar the PHP source archive into
          the directory in your web server's document root that you have created for
          your helpdesk system. This could simply be a directory called <quote>helpdesk</quote>
          or you could do more fancy things with virtual hosts but that is up to you. Make sure
          you specify the full path of the <filename>web-tree.tar</filename> archive if
          it is not in the current working directory.
        </para>
        <programlisting>
#> tar xvf web-tree.tar</programlisting>
        <para>
          This should automatically create all the relevant folders and populate them with the
          correct PHP scripts.
        </para>
      </sect2>
      <sect2 id="configuringphp">
        <title>Configuring PHP</title>
        <para>
          The Helpdesk Issue Manager stipulates the values of certain PHP config variables.
          These are as follows:
        </para>
        <variablelist>
          <varlistentry>
            <term><varname>include_path</varname></term>
            <listitem>
              <para>
                Depending on where you have placed your scripts, you may have to update your PHP's
                configuration script in order to ensure that the include files can be found by the
                interpreter. For a system that is using a subdirectory of the document root, then
                you will have to make sure that that directory is listed in the
                <filename>PHP.ini</filename> file.
              </para>
              <programlisting>include_path = ".:/php/includes:/srv/www/htdocs/helpdesk"             # UNIX
include_path = ".;c:\php\includes;c:\intepub\wwwroot\helpdesk"        # Windows
</programlisting>
              <para>
                If you are going to set up a virtual host to hold the system, then the default
                PHP include directories are sufficient.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><varname>arg_separator.output</varname></term>
            <listitem>
              <para>
                In order to ensure <acronym>XHTML1.0</acronym> compliance, this argument
                separator variable must be set to use ampersand entities instead of ampersand
                literals. This is because no element attribute is allowed to include the
                <quote>&amp;</quote> character, and must instead be replaced with the
                <quote>&amp;amp;</quote> entity. This is used when PHP dynamically creates or
                modifies querystrings in order to keep track of sessions.
              </para>
              <programlisting>arg_separator.output = "&amp;amp;"</programlisting>
              <para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><varname>magic_quotes_gpc</varname></term>
            <listitem>
              <para>
                In order to ensure that any input is correctly escaped, the following must be
                set to <quote>On</quote>.
              </para>
              <programlisting>magic_quotes_gpc = On</programlisting>
              <para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><varname>magic_quotes_runtime</varname></term>
            <listitem>
              <para>
                The runtime escaping of <acronym>SQL</acronym> commands is useful in some
                cases, but in this system (and most others) this conflicts with the
                previous config variable, and so this should be set to <quote>Off</quote>.
              </para>
              <programlisting>magic_quotes_runtime = Off</programlisting>
              <para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><varname>short_open_tag</varname></term>
            <listitem>
              <para>
                This config variable is quite frequently set to <quote>On</quote> because of
                the slight increase in simplicity of PHP code that can be written as a
                consequence. Sometimes however, this is set to <quote>Off</quote> in order to
                aid in developing of XML applications. Currently, it is required that this be
                set to <quote>On</quote>. As this system is an XHTML application, this is
                something that will change in later versions so that this configuration varible
                can be ignored, but for now:
              </para>
              <programlisting>short_open_tag = On</programlisting>
              <para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><varname>register_globals</varname> (Optional)</term>
            <listitem>
              <para>
                This config variable is quite frequently set to <quote>On</quote> because of
                the simplicity of PHP code that can be written as a consequence. Unfortunately,
                security is difficult to ensure in such an environment as the
                <varname>POST</varname> variables are indistinguishable from
                <varname>SESSION</varname> variables. This is just good practice and not a
                requirement. This system will work just as well and just as securely whether
                this is set to <quote>On</quote> or <quote>Off</quote> because of the way it
                is written.
              </para>
              <programlisting>register_globals = Off</programlisting>
              <para>
            </listitem>
          </varlistentry>
        </variablelist>
        <para>
          It must be understood that the <filename>PHP.ini</filename> configuration file
          comprises of many different variables for controlling many different aspects of
          the PHP interpreter. Whereas most of the unmentioned config variables would not
          directly affect the system, it is possible that there could be undesirable
          consequences from setting some of them. Fotrunately though, if you have left the
          defaults in place, you shouldn't have a problem.
        </para>
      </sect2>
    </sect1>
    <sect1 id="databasesetup">
      <title id="databasesetup.title">Setting up the database</title>
      <sect2 id="databasecreation">
        <title id="databasecreation.title">Creating the database</title>
        <para>
          The database definition script (the <filename>database.sql</filename> file that can be downloaded with
          the distribution) should be used to create the tables used by this system. If you
          task your PostgreSQL database administrator with the following instructions,
          you won't go far wrong:
        </para>
        <orderedlist>
          <listitem>
            <para>
              Create a database user with 'createdb' privileges. To do this, your system
              administrator must log into the postgres account at the command line shell
              and then use the <command>createuser</command> program as follows, entering
              the chosen password when prompted:
            </para>
            <programlisting>
#> su postgres
%> createuser -A -d -E -P chosen_username</programlisting>
            <para>
              The default username and password used with this distribution are
              <quote>helpdesk</quote> and <quote>helpdesk</quote> but you should choose
              your own username/password for security reasons. If so then make sure that
              you change that username and password in the DB connection script (found in
              <filename>system/db.php</filename>) before continuing with the installation.
            </para>
          </listitem>
          <listitem>
            <para>
              Using the newly created database account, you must create a new database called
              <database>helpdesk</database>, entering the password chosen above when prompted:
            </para>
            <programlisting>
%> createdb -U chosen_username -W helpdesk</programlisting>
            <para>
              As above, you can use a different database name if you wish,
              but if you do you will have to change the DB connection script to reflect
              this (and in the next step you will have to replace <quote>helpdesk</quote>
              with your chosen database name).
            </para>
          </listitem>
          <listitem>
            <para>
              Execute the sql script for the appropriate release to create all the
              system's tables using the same account as above. This will enter some
              initial values for some tables and set up integrity constraints. Make sure
              you specify the full path of the <filename>database.sql</filename> script if
              it is not in the current working directory.
            </para>
            <programlisting>
%> psql -U chosen_username -W helpdesk -f database.sql</programlisting>
            <para>
              As the database definition file includes <command>drop table</command> statements,
              you will get a list of errors explaining that the tables and views do not exist.
              This is expected. Any other errors should be classed as fatal and as such the
              database will not be in the correct form.
            </para>
          </listitem>
        </orderedlist>
      </sect2>
      <sect2 id="databasesecurity">
        <title id="databasesecurity.title">A note on security</title>
        <para>
          It is important to note that with PostgreSQL, the default security settings are not at
          all secure. If you do not have the experience of a database administrator at your
          disposal you will have no guarantee that the data in your database is secure. For those
          who do not have the liberty that a DBA affords, then you can always follow my example
          and hope for the best. No guarantees!
        </para>
        <para>
          In the <filename>postgresql.conf</filename> that can be found in the root of your
          database cluster file system (usually at <filename>/var/lib/pgsql/data</filename>),
          make sure that the following two lines are present (and come before all others).
        </para>
      <programlisting>
local          all            postgres       trust
local          helpdesk       all            password</programlisting>
        <para>
          The first ensures that the standard user (in this case <quote>postgres</quote>) has full
          access to the database. Without this first, your database might not correctly start
          at boot time. The second grants your database scripts (assuming you have called the database
          <quote>helpdesk</quote>) access to your database and nothing else. It also ensures
          authentication.
        </para>
        <para>
          Of course, the above came from a system that had no other databases present in the
          cluster, and so caused no problems. Always think twice before setting this yourself.
        </para>
      </sect2>
    </sect1>
  </chapter>

  <chapter id="migrating">
    <title>Migrating an existing installation</title>
    <sect1 id="migratingphpscripts">
      <title>Migrating the PHP scripts</title>
      <para>
        Migrating the PHP scripts is as simple as re-installing the same version of scripts
        on the new server. Just follow the instructions for
        <link linkend="phpscripts" endterm="phpscripts.title"></link>. How easy
        is that?
      </para>
    </sect1>
    <sect1 id="migratingdatabase">
      <title>Migrating the database</title>
      <para>
        Migrating the database is carried out by dumping the current database, and then restoring
        the data in the new database. These two functions should be carried out by your database
        administrator using the <command>pg_dump</command> and <command>psql</command>
        commands. The first act is to dump the old <database>helpdesk</database> database to a
        file (such as <filename>migration.sql</filename>):
      </para>
      <programlisting>
#> pg_dump -U chosen_username -W -d -c -f migration.sql helpdesk</programlisting>
      <para>
        Then on the new server, assuming the new database server has been installed correctly,
        you should create an empty helpdesk database using the following commands (please
        see <link linkend="databasesetup" endterm="databasesetup.title"></link>):
      </para>
      <programlisting>
#> su postgres
%> createuser -A -d -E -P chosen_username
%> createdb -U chosen_username -W helpdesk</programlisting>
      <para>
        Then once the <filename>migration.sql</filename> file has been transferred between
        the servers, the simple act of restoring the data and schema to your new database is
        done with the following command:
      </para>
      <programlisting>
#> psql -U chosen_username -W helpdesk -f migration.sql</programlisting>
      <para>
        Please be aware that the above is simply a guide for those without experience who wish
        to try. If you are working on important and sensitive information you should be getting
        your fully experienced database administrator to do the job. If they're worth their salt,
        they shouldn't need to read this chapter.
      </para>
    </sect1>
  </chapter>

  <chapter id="upgrading">
    <title>Upgrading an existing installation</title>
    <para>
      Before you can even think about upgrading your system from one release to the next, please
      take note of the following:
    </para>
    <orderedlist>
      <listitem>
        <para>
          You must be currently using a system that is version 0.62 or above, as all releases
          prior to version 0.63 do not come with database upgrade scripts. If you are using a
          version before 0.62 then your only option is to make a clean install, removing your
          current data from the system.
        </para>
      </listitem>
      <listitem>
        <para>
          The upgrade is carried out in two parts. Both parts must be done before the system is
          usable again, and so only carrying out one part of the upgrade will lead to an inconsistent
          system. This will require downtime for you system, and your user base needs to be aware
          of this downtime. The upgrade itself should take no more than a couple of minutes, but
          during that time, noone must have access to the system.
        </para>
      </listitem>
      <listitem>
        <para>
          Ugrade scripts for the database are written to upgrade from one specific version to the
          next. If you are trying to upgrade from say v0.62 to v0.7, missing out v0.63 (or any other
          versions that might have been released in between) your upgrade will fail and result in an
          unusable system. In order to upgrade through a number of versions, you must sequentially
          execute each individual version increase (in the right order and not skipping any versions)
          from your current version to the required version.
        </para>
      </listitem>
    </orderedlist>
    <sect1 id="updatingphpscripts">
      <title>Updating the PHP scripts</title>
      <para>
        Upgrading the PHP scripts is as simple as installing the new version of scripts
        on the server in place of the old ones. Just follow the instructions for
        <link linkend="phpscripts" endterm="phpscripts.title"></link>.
      </para>
    </sect1>
    <sect1 id="updatingdatabase">
      <title>Updating the database</title>
      <para>
        From version 0.63, each release will come packaged with a database definition file,
        <filename>upgrade.sql</filename> that can be used to upgrade the database. Before you
        go ahead and update the system, you must open the file in your favourite text editor and
        read the top few lines. An example might read:
      </para>
      <programlisting>
/*
  Helpdesk Issue Manager
  Database Definition Script
  Update from version 0.62 to 0.63

  DO NOT USE ON ANY OTHER VERSION!!!
*/</programlisting>
      <para>
        Make sure you read this and ensure that the version you are updating from is indeed the
        one specified. And do as it says, DO NOT USE ON ANY OTHER VERSION or you will end up with
        a system that does not work. You have been warned.
      </para>
      <para>
        To carry out the database upgrade, you must execute the database definition script
        <filename>update.sql</filename> in your PostgreSQL database. To do this, type the
        following command. Make sure you specify the full path of the
        <filename>update.sql</filename> script if it is not in the current working directory.
      </para>
      <programlisting>
#> psql -U chosen_username -W helpdesk -f update.sql</programlisting>
      <para>
        The above script will then modify the database to bring it up to the correct release format
        by creating or altering tables, and of course, updating the system's version number. The
        above script should return no errors.
      </para>
    </sect1>
  </chapter>

  <chapter id="systemconfig">
    <title>System Configuration</title>
    <sect1 id="initialsetup">
      <title>Initial setup</title>
      <para>
        Initially, the helpdesk system is set up with one user account. The Root user. This user
        is not a normal member of society, in that they have no access to submit issues or view
        existing issues. Root's sole goal in life is to set up the parameters for the system.
        The initial username and password are <literal>root</literal> and <literal>root</literal>.
        As administration is cascading, the least amount of work the Root user must do to get a
        fully working system is to do the following:
      </para>
      <orderedlist>
        <listitem>
          <para>
            Create a new domain (or modify the <quote>demo</quote> domain that is
            initially present in the system) to use as your helpdesk's domain.
            (see <link linkend="workingwithdomains" endterm="workingwithdomains.title"></link>).
          </para>
        </listitem>
        <listitem>
          <para>
            Create the first (and maybe only) site for that domain.
            (see <link linkend="workingwithsites" endterm="workingwithsites.title"></link>).
          </para>
        </listitem>
        <listitem>
          <para>
            Create a user account for whoever is to take responsibility for the administration
            of that domain and give them <quote>Domain Administrator</quote> access to the
            newly added site. This new user will then take over the job of setting up that
            domain correctly.
            (see <link linkend="workingwithusers" endterm="workingwithusers.title"></link>).
          </para>
        </listitem>
      </orderedlist>
      <para>
        For an average implementation, you should be looking to have at least two priorities
        (<quote>Low</quote> and <quote>High</quote>) and two statuses (<quote>Open</quote> and
        <quote>Closed</quote>). For larger implementations, more would be prudent. Examples of
        a few different implementations can be found in the chapter
        <link linkend="implementations" endterm="implementations.title"></link>.
      </para>
    </sect1>
    <sect1 id="workingwithdomains">
      <title id="workingwithdomains.title">Working with Domains</title>
      <para>Coming soon...</para>
    </sect1>
    <sect1 id="workingwithsites">
      <title id="workingwithsites.title">Working with Sites</title>
      <para>Coming soon...</para>
    </sect1>
    <sect1 id="workingwithusers">
      <title id="workingwithusers.title">Working with Users</title>
      <para>Coming soon...</para>
    </sect1>
    <sect1 id="workingwithstuff">
      <title id="workingwithstuff.title">Working with Priorities, Statuses and Levels</title>
      <para>Coming soon...</para>
    </sect1>
    <sect1 id="workingwithnotice">
      <title id="workingwithnotice.title">Working with Public Notices</title>
      <para>Coming soon...</para>
    </sect1>
    <sect1 id="implementations">
      <title id="implementations.title">Implementation Examples</title>
      <para>Coming soon...</para>
    </sect1>
  </chapter>

</book>
