From 8b23aae57552ac631189286232dfef3578daa727 Mon Sep 17 00:00:00 2001 From: Mike Rylander Date: Tue, 17 May 2022 16:29:02 -0400 Subject: [PATCH] Docs: OAI-PMH data provider support Signed-off-by: Andrea Buntz Neiman --- docs/modules/admin_initial_setup/nav.adoc | 1 + docs/modules/admin_initial_setup/pages/oaipmh.adoc | 97 ++++++++++++++++++++++ 2 files changed, 98 insertions(+) create mode 100644 docs/modules/admin_initial_setup/pages/oaipmh.adoc diff --git a/docs/modules/admin_initial_setup/nav.adoc b/docs/modules/admin_initial_setup/nav.adoc index 0b2c5cf490..88d729175b 100644 --- a/docs/modules/admin_initial_setup/nav.adoc +++ b/docs/modules/admin_initial_setup/nav.adoc @@ -34,3 +34,4 @@ ** xref:admin:phonelist.adoc[Phonelist.pm Module] ** xref:admin:sip_server.adoc[SIP Server] ** xref:admin:audio_alerts.adoc[Managing Audio Alerts] +** xref:admin_initial_setup:oaipmh.adoc[OAI-PMH Data Provider Support] diff --git a/docs/modules/admin_initial_setup/pages/oaipmh.adoc b/docs/modules/admin_initial_setup/pages/oaipmh.adoc new file mode 100644 index 0000000000..a85d96e06f --- /dev/null +++ b/docs/modules/admin_initial_setup/pages/oaipmh.adoc @@ -0,0 +1,97 @@ += OAI-PMH Data Provider Support = +:toc: + +As of version 3.9 Evergreen can act as an OAI-PMH data provider, exposing the catalog to harvesting through the http://www.openarchives.org/OAI/openarchivesprotocol.html[OAI2 protocol]. + +== Entry points == + +There are two entry points: one for bibliographic records and one for authority records: + +`http:///opac/extras/oai/authority` + +`http:///opac/extras/oai/biblio` + + +An example of a working URL on a system with an authority record with ID 1: + +`http:///opac/extras/oai/authority?verb=GetRecord&identifier=oai:localhost:1&metadataPrefix=oai_dc` + +== Setspec are partially implemented == + +Sets for bib records are currently based on copy visibility, Located URI visibility, or bib source. Generally useful combinations are generated for item, Located URI, and transcendent bib sources. + +Sets for authority records are based on the browse axis of the heading for the record. + +All generated Sets for bib records currently test for effective search visibility on the three described components. + +In order to retrieve item data from a specific branch of the org tree, a harvester must use a Set that contains `COPIES:`. The hierarchical shortnames of the org units follow the colon, so in a freshly installed system a Set with the setSpec of `COPIES:CONS:SYS2:BR3` will retrieve all bib records that have visible copies at BR3, and include only the item data for that org unit. + +To retrieve records with Located URIs, which behave in the hierarchical reverse of copies by limiting display to those org units "inside" the branch of the tree where the licensing "lives", a harvester should supply a setSpec with an org unit shortname that would display the Located URI. For example: `LURIS:CONS:SYS2:BR3` + +Note: the `LURI:` org unit is also used to restrict any item data that may be available for LURI-filtered records. + +To retrieve records that are in a transcendent bib source, a harvester can used a setSpec starting with `SOURCES:` followed by the source name. + +To harvest all records, including deleted records, simply omit the setSpec from the request. All item data will be included. + +To list available Sets, use the ListSets verb, for instance: + +`http://your-domain/opac/extras/oai/biblio?verb=ListSets` + +`http://your-domain/opac/extras/oai/authority?verb=ListSets` + +== Bibliographic mapping of assets to 852 subfields == + +Certain attributes asset are placed into 852 subfields so: + +|=== +| subfield code | asset resource + +| a | location +| b | owning_lib +| c | callnumber +| d | circlib +| g | barcode +| n | status +|=== + +Thus the Concerto with record ID 1 will have its 852 subfields expressed as: + +[source,xml] +---- + + Stacks + BR4 + ML 60 R100 + BR4 + CONC70000435 + Checked out + +---- + +This mapping can be customized and extended with static subfields: + +[source,xml] +---- +A constant value +---- + +== Default configuration == + +See comments in `opensrf.xml` (in the `open-ils.supercat app_settings/oai` element) for default configuration and customization instructions. + +== Upgrade instructions == + +OAI support is not turned on by default. To enable it, edit the Apache configuration file `eg_vhost.conf` to uncomment the following section and restart Apache: + +[source,conf] +---- +# +# SetHandler perl-script +# PerlHandler OpenILS::WWW::SuperCat::OAI +# Options +ExecCGI +# PerlSendHeader On +# Require all granted +# +---- + -- 2.11.0