docs/RELEASE_NOTES_NEXT/OAI2/new_oai_opensrf_service.adoc

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