EPrints v3 Configuration Notes

Enabling OAI

Enabling OAI in ePrints is very easy to achieve as versions of ePrints since v3.0.0 have included both oai_dc and uketd_dc OAI compliance as part of the standard installation. The only actions required to make an archive OAI-enabled are to configure the archive-specific settings so that OAI calls return the correct information.

These are stored in
/opt/eprints3/archives/ARCHIVE_ID/cfg/cfg.d/oai.pland comments within this file describe the institution-specific data than needs to be added. Most of the data is informational text (such as content- and data-policies) but the crucial, technical items are :
  • Archive ID : The name of the archive. This MUST be unique. As this can include full stops, we use the obvious ARCHIVE_NAME.INSTITUTION_DOMAIN (eg. etheses.bham.ac.uk)
  • Output Plugins : the metadata formats supported by this archive. These are used by the system to return data when an OAI call is made. See below for more information on this.
  • Sets/Filters : Optional configuration so that exports can be made of subsets of the archive.
Once this is configured and the archive reloaded with the command

/opt/eprints3/bin/epadmin reload ARCHIVE_ID
Instructions on testing the compliance of the archive are given below.

Adding/Changing fields.

If any customisation of the ePrints metadata structure is made, new or edited fields may need to be added to the XML returned by an OAI getRecord command.

This XML is generated by the appropriate ePrints Export plugin and are assigned to metadata prefixes in the output_plugins section of

by default this contains the lines:
# The output plugins must be loaded for the archive and have # the methods xml_dataobj and properties for xmlns and schemaLocation. # # The keys of this hash are the OAI metadataPrefix to use, and the values # are the ID of the output plugin to use for that prefix. $oai->{v2}->{output_plugins} = { "oai_dc" => "OAI_DC", "didl" => "DIDL", "uketd_dc" =>"OAI_UKETD_DC", "context_object" => "ContextObject", "mets" => "METS" };
which show that the eTHOS plugin is named OAI_UKETD_DC and is enabled by default. This plugin can be found at

Although written in perl, little programming experience is necessary for basic administration of this file. Adding and editing simple fields can be done by copying an existing field's code. These are at the end of the file and of the format : if( $eprint->exists_and_set( "language" )){ push @etddata, [ "language", $eprint->get_value( "language" ), "dc"]; } if( $eprint->exists_and_set( "sponsors" )){ push @etddata, [ "sponsor", $eprint->get_value( "sponsors" ), "uketdterms"]; } if( $eprint->exists_and_set( "alt_title" )){ push @etddata, [ "alternative", $eprint->get_value("alt_title" ), "dcterms"]; }
The last parameter on each line refers to the schema from which the type is derived. The above three fields, for example, will appear in the output XML as
<dc:language>English</dc:language> <uketdterms:sponsors>The Umbrella Corp.</uketdterms:sponsors> <dcterms:alt_title>Raccoon City Pop. Study</dcterms:alt_title>

Testing OAI Compliance

The basic configuration of an archive (the name and policies) can be tested by pointing a browser to the address


Full OAI compliance validity (the correct record formats, etc.) can be tested by entering the base url of the archive, http://ARCHIVE.WEB.ADDRESS/cgi/oai2(external link), into the OAI-PMH Repository Explorer at http://re.cs.uct.ac.za/(external link)

The XML generated by a plugin can be viewed by submitting an OAI call including the Prefix=<prefixname> parameter. For Ethos, this would be :


This will list all available records in an archive including their uketd_dc stanza. If an archive is large, an individual record's data can be retrieved using the address

http://ARCHIVE.WEB.ADDRESS/cgi/oai2? verb=GetRecord&metadataPrefix=uketd_dc&identifier=oai:ARCHIVE_ID:ID

(Where the ID is the ePrint ID) e.g.

http://etheses.bham.ac.uk/cgi/oai2? verb=GetRecord&metadataPrefix=uketd_dc&identifier=oai:etheses.bham.ac.uk:4