source: gsdl/trunk/runtime-src/src/oaiservr/README.txt@ 19294

OAI Server Configuration Instructions
-------------------------------------

Greenstone needs some configuration before successfully supporting OAI serving.  This consists of three steps:

1) Server-wide configuration to support vital OAI commands such as Identify.
   This allows the OAI client to obtain information on the maintainer of
   the server, etc.  See the OAI documentation for further information on
   the Identify verb.  These configurations are kept in gsdl/etc/oai.cfg.

2) Configuring collections to be 'active' OAI collections; just as collections
   in Greenstone can be 'private' or 'public', collections can similarly be
   'visible' or 'invisible' to OAI.  By default, collections are NOT served
   via OAI - you have to enable them by adding each collection's name to a
   list in gsdl/etc/oai.cfg.

3) Mapping your collection metadata to a "Namespace" supported by OAI.  At
   present, Greenstone supports the Dublin Core metadata format alone in OAI,
   and metadata fields in a Greenstone collection must be mapped into the
   Dublin Core namespace.  This configuration can be done either server-wide,
   for all collections, in gsdl/etc/oai.cfg or in the etc/collect.cfg of
   each individual collection.

This documentation explains how to set up Greenstone's configuration for steps 1-3 above, install, deplay and test OAI on your Greenstone system.

Part 1: Server-Wide Configuration Information
---------------------------------------------

Your OAI server should provide some basic information on the collections it holds as a whole.  For this purpose, all collections on your server are treated the same: you cannot have different information for each collection.  In this section, we describe what information you should provide, and how to configure Greenstone correctly to provide it.

The basic server-wide information is:
  * The OAI repository (server) name - this is a human readable form such
    as "The Research Authority's OAI Server".
  * The central administrative email address for the OAI repository.
  * The base URL for the repository.
  * Which version of OAI the repository supports/delivers.
  * A free text item of information about the OAI repository - e.g. its
    purpose, size, origins, etc.

These items are kept in the following items of gsdl/etc/oai.cfg.  The syntax rules for these configuration items are the same as for gsdl/etc/main.cfg -  e.g. strings containing spaces should be enclosed in quotation marks.  See the main Greenstone configuration documentation for further information.

  * repositoryName
       One item only, free text.
  * maintainer
       One item only, as a valid email address
  * baseURL
       One item only, see the example in the oai.cfg file.
  * httpdomain 
       NB: in the gsdlsite.cfg file, NOT oai.cfg
       Should not require specific configuration if your Greenstone install
       is already operational through your web server.
  * oaiversion
       One item only, which should be either "1.1 or "2.0"
  * oaiinfo
       Numerous items, which are usually in a label and value pair.
       An example item may be:
          oaiinfo sponsor "The Big Cheese Corporation"

Sample items are already provided in the default oai.cfg file - please ensure that you complete these in your preferred text editor.


Part 2: Enabling Collections
----------------------------

In addition to the items above, one further sort of item needs to be added to gsdl/etc/oai.cfg - a list of the collections that should be made available to OAI clients.  This list is supplied in one or more lines in gsdl/etc/oai.cfg in the form:

  oaicollection OAIDemo HDL

The first item in each line should be the same - "oaicollection" - followed by one or more collection names.  Each collection name should be the name of the folder/directory in the gsdl/collect directory which holds the collection.

Once these items have been added to gsdl/etc/oai.cfg, the final stage of the OAI configuration can begin: mapping from a collection's own metdata fields into the Dublin Core metadata fields used by OAI.  This will be detailed in the folloowing section of this document.


Part 3: Mapping fields
----------------------

In Greenstone, metadata fields are created by the collection designer.  These may follow an accepted standard - e.g. Dublin Core - be a modification or extension of an accepted standard, or a bespoke format specific to the needs of the particular collection.  As Greenstone installer, you should have decided upon one of these three approaches already.  You may have chosen one of the standard metadata structures incorporated into the Greenstone Librarian Interface (GLI), or created your own using your own metadata files and automatically extracted information from your document files.  Whatever the approach you have used for obtaining the metadata in your collection, or whatever the fields are that you have used in your collection, the approach to linking these fields (mapping them) to the OAI Dublin Core format is the same.

The mapping of fields is done in two ways: first, globally for all collections, and secondly specifically for one collection.  The syntax for the configuration items to achieve these different mappings is the same.  The file in which they are placed determines whether they apply to all collections, are just one.  Global mappings are found with the other OAI configuration items in gsdl/etc/main.cfg whilst collection-specific mappings are placed in the etc/collect.cfg file of the collection itself.

Mapping items in the configuration file take the following format:

  oaimapping <greenstone fieldname> <dublin core fieldname>

The syntax of each of the two fieldnames given above requires a little more detail; we will take the Dubline Core fieldname first.  

The Dublin Core fieldsname should be given in the form "DC:<fieldname>", as OAI can support other metadata formats, and thus we use "DC:" to be clear that we are mapping to Dublin Core.  The fieldnames available for Dublin Core can be found on the central Dublin Core website at http://www.dublincore.org/.

The Greenstone fieldname can be in two formats.  The simpler one is simply the name of the field to map from.  The more complex one has the name of the collection placed in front of the field name, followed by a colon.  e.g. "demo:Title" would mean the metadata field "Title" in the collection called "demo".  Using this, all mappings can be stored in the central gsdl/etc/oai.cfg file if you wish, and we recommend this approach.

Let us recap at this point with a few example items for a gsdl/etc/oai.cfg:

oaimapping Author dc.Creator
oaimapping dls.Title  dc.Title
oaimapping Photos:fileformat dc.Format

The first item maps any occurrence of 'Author' in any collection to the Dublin Core 'Creator' field (there is no 'Author' field in DC).  The second item maps 'dls.Title' to 'dc.Title'. Finally, in the specific collection 'Photos', we will map the unique metadata field 'fileformat' to the Dublin Core 'Format' field.


Installation and Testing
------------------------