docs/RELEASE_NOTES_NEXT/OAI2/new_oai_opensrf_service.adoc

   1 OAI-PMH Data Provider Support
   2 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   3
   4 Evergreen can now act as an OAI-PMH data provider, exposing the catalog to
   5 harvesting through the [OAI2 protocol](http://www.openarchives.org/OAI/openarchivesprotocol.html).
   6
   7
   8 Entry points
   9 ++++++++++++
  10 There are two: one for bibliographic records and one for authority records:
  11
  12     http://your-domain/opac/extras/oai/authority
  13     http://your-domain/opac/extras/oai/biblio
  14
  15 An example of a working URL on a system with an authority record with ID
  16 1:
  17
  18     http://your-domain/opac/extras/oai/authority?verb=GetRecord&identifier=oai:localhost:1&metadataPrefix=oai_dc
  19
  20 Setspec are not implemented
  21 +++++++++++++++++++++++++++
  22
  23 This is a work in progress and not enabled. The aim is to have the owning library determine the set hierarchy. The Concerto
  24 test database for example has a record with record ID #1. This record is so popular it has copies attached to library units
  25 "Example Branch 1", "Example Branch 2", "Example Branch 3", "Example Bookmobile 1" which is a child of Branch 3 and
  26 "Example Branch 4". This entire kinship is expressed as sets like so:
  27
  28 ```xml
  29 <header>
  30     ...
  31     <setSpec>CONS</setSpec>
  32     <setSpec>CONS:SYS1</setSpec>
  33     <setSpec>CONS:SYS2</setSpec>
  34     <setSpec>CONS:SYS1:BR1</setSpec>
  35     <setSpec>CONS:SYS1:BR2</setSpec>
  36     <setSpec>CONS:SYS2:BR3</setSpec>
  37     <setSpec>CONS:SYS2:BR4</setSpec>
  38     <setSpec>CONS:SYS2:BR3:BM1</setSpec>
  39 </header>
  40 ```
  41 Likewise the setSpecs of authority records are derived from their browse axis ( Title, Author, Subject and Topic ).
  42
  43 Bibliographic mapping of assets to 852 subfields
  44 ++++++++++++++++++++++++++++++++++++++++++++++++
  45
  46 Certain attributes asset are placed into 852 subfields so:
  47
  48 |===
  49 | subfield code | asset resource
  50
  51 | a | location
  52 | b | owning_lib
  53 | c | callnumber
  54 | d | circlib
  55 | g | barcode
  56 | n | status
  57 |===
  58
  59 Thus the Concerto with record ID #1 will have it's 852 subfields expressed as:
  60 ```xml
  61 <marc:datafield ind1="4" ind2=" " tag="852">
  62     <marc:subfield code="a">Stacks</marc:subfield>
  63     <marc:subfield code="b">BR4</marc:subfield>
  64     <marc:subfield code="c">ML 60 R100</marc:subfield>
  65     <marc:subfield code="d">BR4</marc:subfield>
  66     <marc:subfield code="g">CONC70000435</marc:subfield>
  67     <marc:subfield code="n">Checked out</marc:subfield>
  68 </marc:datafield>
  69 ```
  70 This mapping can be customized and extended with static subfields:
  71 ```xml
  72     <marc:subfield code="q">A constant value</marc:subfield>
  73 ```
  74
  75 Default configuration
  76 +++++++++++++++++++++
  77
  78 See comments in opensrf.xml (in the open-ils.supercat app_settings/oai element)
  79 for default configuration and customization instructions.
  80
  81 Upgrade Instructions
  82 ++++++++++++++++++++
  83 OAI support is not turned on by default. To enable it, edit the Apache
  84 configuration file `eg_vhost.conf` to uncomment the following
  85 section and restart Apache:
  86
  87 [source,conf]
  88 ----
  89 #<Location /opac/extras/oai>
  90 #    SetHandler perl-script
  91 #    PerlHandler OpenILS::WWW::SuperCat::OAI
  92 #    Options +ExecCGI
  93 #    PerlSendHeader On
  94 #    Require all granted
  95 #</Location>
  96 ----
  97
  98 Optional: Setting the datestamp
  99 +++++++++++++++++++++++++++++++
 100
 101 The edit date of the bibliographic and authority record is used as
 102 datestamp. If you want the date for editorial updates of bibliographic
 103 assets (i.e. copies, call numbers) reflected in the datestamp, then add the
 104 triggers shown below.
 105
 106 ```sql
 107
 108 CREATE OR REPLACE FUNCTION oai.datestamp(rid BIGINT)
 109   RETURNS VOID AS $$
 110 BEGIN
 111   UPDATE biblio.record_entry AS bre
 112   SET edit_date = now()
 113   WHERE bre.id = rid;
 114 END
 115 $$ LANGUAGE plpgsql;
 116
 117 CREATE OR REPLACE FUNCTION oai.call_number_datestamp()
 118   RETURNS TRIGGER AS $$
 119 BEGIN
 120   IF TG_OP = 'DELETE'
 121   THEN
 122     PERFORM oai.datestamp(OLD.record);
 123     RETURN OLD;
 124   END IF;
 125
 126   PERFORM oai.datestamp(NEW.record);
 127   RETURN NEW;
 128
 129 END
 130 $$ LANGUAGE plpgsql;
 131
 132 CREATE OR REPLACE FUNCTION oai.copy_datestamp()
 133   RETURNS TRIGGER AS $$
 134 BEGIN
 135   IF TG_OP = 'DELETE'
 136   THEN
 137     PERFORM oai.datestamp((SELECT acn.record FROM asset.call_number as acn WHERE acn.id = OLD.call_number));
 138     RETURN OLD;
 139   END IF;
 140
 141   PERFORM oai.datestamp((SELECT acn.record FROM asset.call_number as acn WHERE acn.id = NEW.call_number));
 142   RETURN NEW;
 143
 144 END
 145 $$ LANGUAGE plpgsql;
 146
 147 CREATE TRIGGER call_number_datestamp AFTER INSERT OR UPDATE OR DELETE ON asset.call_number FOR EACH ROW EXECUTE PROCEDURE oai.call_number_datestamp();
 148 CREATE TRIGGER copy_datestamp AFTER INSERT OR UPDATE OR DELETE ON asset.copy FOR EACH ROW EXECUTE PROCEDURE oai.copy_datestamp();
 149 ```
 150