====== Greenstone 2 OAI server ======

Greenstone comes with a built-in OAI data provider. This runs as a CGI program called
 ''oaiserver.cgi'', and is installed in the Greenstone cgi-bin directory. 
It can be accessed via the same URL as the Greenstone library (replacing 
''library.cgi'' with ''oaiserver.cgi''). On Windows, you must be using a web server (eg Apache) not the local library server. 

Configuration of the server is done via the ''oai.cfg'' file in the Greenstone ''etc'' directory. This file specifies general information about the repository, lists collections to be made accessible and may include metadata mapping information. **Important:** the ''oai.cfg'' file must be utf-8 encoded.

Please edit ''oai.cfg'' and set the repositoryName and repositoryId fields. 
If you are not using the standard Apache setup that comes with Greenstone, 
you may need to set oaiserverPath, libraryPath, docRootPath. Optionally, 
you can set baseServerURL to use a domain name instead of IP address in URLs.

By default, collections are not accessible. To enable a collection, add its name to the ''oaicollection'' list. 

Greenstone's OAI server currently supports Dublin Core, Qualified Dublin Core, and 
RFC1807 metadata. For collections that use other metadata sets, including extracted 
metadata, metadata mapping rules should be provided to map the existing metadata 
to Dublin Core. ''oai.cfg'' has more details.

==== To add a new metadata set for use with oaiserver ==== 

You need to do the following:
  * Create a schema (or find an existing one) for the metadata set. See [[http://www.greenstone.org/namespaces/gsdl_qdc/1.0/gsdl.qdc.xsd|Greenstone's qualified dublin core]] schema, OAI standard [[http://www.openarchives.org/OAI/1.1/dc.xsd|dublin core]] files for examples.
    * Put the new schema somewhere web accessible
  * Coding in GSDLHOME/runtime-src/src/oaiservr:
    * Create a new metaformat class for the metadata set. See dublincore.h/cpp, qualified_dublincore.h/cpp, rfc1807.h/cpp for examples.
    * edit Makefile.in, Makefile and win32.mak to use the new files
    * Edit recordaction.cpp to include the new header file and instantiate the new class (in recordaction())

  * Tell the server to use the new set: edit etc/oai.cfg and add the set name to the oaimetadata line. You may also need to add oaimapping information.
  * Recompile and test.

====Testing==== 

Once you have your OAI service in place, testing can be done via online validation facilities such as the following: http://www.openarchives.org/data/registerasprovider.html or http://re.cs.uct.ac.za/.

The former only verifies the Identify command, while extensive testing can be performed via the later one (called //Repository Explorer//).

The Greenstone OAI server must be publically accessible over the Internet to use these validation tools.