1.6/development/supercat.xml

   1 <?xml version="1.0" encoding="utf-8"?>\r
   2 <chapter xml:id="supercat" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
   3     xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
   4         <info>\r
   5                 <title>SuperCat</title>\r
   6         </info>\r
   7         <para>SuperCat allows Evergreen record and information retrieval from a web browser using a based on a number of open web standards and formats. The following record types are supported:</para>\r
   8         <itemizedlist>\r
   9                 <listitem>isbn</listitem>\r
  10                 <listitem>metarecord</listitem>\r
  11                 <listitem>record</listitem>\r
  12         </itemizedlist>\r
  13         <simplesect>\r
  14                 <title>Return a list of ISBNs for related records</title>\r
  15                 <para>Similar to the OCLC xISBN service, Evergreen can return a list of related records based on its oISBN algorithm:</para>\r
  16                 <screen>http://&lt;hostname&gt;/opac/extras/osibn/&lt;ISBN&gt;</screen>\r
  17                 <para>For example, http://dev.gapines.org/opac/extras/oisbn/0439136350 returns:</para>\r
  18                 <programlisting>\r
  19                 &lt;idlist metarecord="302670"&gt;\r
  20                 &lt;isbn record="250060"&gt;0790783525&lt;/isbn&gt;\r
  21                 &lt;isbn record="20717"&gt;0736691316&lt;/isbn&gt;\r
  22                 &lt;isbn record="250045"&gt;0790783517&lt;/isbn&gt;\r
  23                 &lt;isbn record="199060"&gt;9500421151&lt;/isbn&gt;\r
  24                 &lt;isbn record="250061"&gt;0790783495&lt;/isbn&gt;\r
  25                 &lt;isbn record="154477"&gt;0807286028&lt;/isbn&gt;\r
  26                 &lt;isbn record="227297"&gt;1594130027&lt;/isbn&gt;\r
  27                 &lt;isbn record="26682"&gt;0786222743&lt;/isbn&gt;\r
  28                 &lt;isbn record="17179"&gt;0807282316&lt;/isbn&gt;\r
  29                 &lt;isbn record="34885"&gt;0807282316&lt;/isbn&gt;\r
  30                 &lt;isbn record="118019"&gt;8478885196&lt;/isbn&gt;\r
  31                 &lt;isbn record="1231"&gt;0738301477&lt;/isbn&gt;\r
  32                 &lt;/idlist&gt;\r
  33                 </programlisting>\r
  34          </simplesect>\r
  35          <simplesect>\r
  36                 <title>Return records</title>\r
  37                 <para>SuperCat can return records and metarecords in many different formats (see <xref linkend='supportedsupercatformats' /></para>\r
  38                 <screen>http://&lt;hostname&gt;/opac/extras/supercat/retrieve/&lt;format&gt;/&lt;record-type&gt;/&lt;bib-ID&gt;</screen>\r
  39                 <para>For example, http://dev.gapines.org/opac/extras/supercat/retrieve/mods/record/555 returns:</para>\r
  40                 <programlisting>\r
  41                 &lt;mods:modsCollection version="3.0"&gt;\r
  42                         &lt;mods:mods xsi:schemaLocation="http://www.loc.gov/mods/ http://www.loc.gov/standards/mods/mods.xsd"&gt;\r
  43                                 &lt;titleInfo&gt;\r
  44                                         &lt;title&gt;More Brer Rabbit stories /&lt;/title&gt;\r
  45                                 &lt;/titleInfo&gt;\r
  46                                 &lt;typeOfResource&gt;text&lt;/typeOfResource&gt;\r
  47                                 &lt;originInfo&gt;\r
  48                                         &lt;place&gt;\r
  49                                                 &lt;code authority="marc"&gt;xx&lt;/c0de&gt;\r
  50                                         &lt;/place&gt;\r
  51                                         &lt;publisher&gt;Award Publications&lt;/publisher&gt;\r
  52                                         &lt;dateIssued&gt;c1982, 1983&lt;/dateIssued&gt;\r
  53                                         &lt;dateIssued encoding="marc" point="start"&gt;1983&lt;/dateIssued&gt;\r
  54                                         &lt;dateIssued encoding="marc" point="end"&gt;1982&lt;/dateIssued&gt;\r
  55                                         &lt;issuance&gt;monographic&lt;/issuance&gt;\r
  56                                         &lt;/originInfo&gt;\r
  57                                 &lt;language authority="iso639-2b"&gt;eng&lt;/language&gt;\r
  58                                 &lt;physicalDescription&gt;\r
  59                                         &lt;form authority="marcform"&gt;print&lt;/form&gt;\r
  60                                         &lt;extent&gt;unp. : col. ill.&lt;/extent&gt;\r
  61                                 &lt;/physicalDescription&gt;\r
  62                                 &lt;note type="statement of responsibility"&gt;ill. by Rene Cloke.&lt;/note&gt;\r
  63                                 &lt;subject authority="lcsh"&gt;\r
  64                                         &lt;topic&gt;Animals&lt;/topic&gt;\r
  65                                         &lt;topic&gt;Fiction&lt;/topic&gt;\r
  66                                 &lt;/subject&gt;\r
  67                                 &lt;subject authority="lcsh"&gt;\r
  68                                         &lt;topic&gt;Fables&lt;/topic&gt;\r
  69                                 &lt;/subject&gt;\r
  70                                 &lt;recordInfo&gt;\r
  71                                         &lt;recordContentSource&gt;(BRO)&lt;/recordContentSource&gt;\r
  72                                         &lt;recordCreationDate encoding="marc"&gt;930903&lt;/recordCreationDate&gt;\r
  73                                         &lt;recordChangeDate encoding="iso8601"&gt;19990703024637.0&lt;/recordChangeDate&gt;\r
  74                                         &lt;recordIdentifier&gt;PIN60000007 &lt;/recordIdentifier&gt;\r
  75                                 &lt;/recordInfo&gt;\r
  76                         &lt;/mods:mods&gt;\r
  77                 &lt;/mods:modsCollection&gt;\r
  78                 </programlisting>\r
  79          </simplesect>\r
  80          <simplesect>\r
  81                 <title>Return a feed of recently edited or created records</title>\r
  82                 <para>SuperCat can return feeds of recently edited or created authority and bibliographic records:</para>\r
  83                 <screen>http://&lt;hostname&gt;/opac/extras/feed/freshmeat/&lt;feed-type&gt;/[authority|biblio]/[import|edit]/&lt;limit&gt;/&lt;date&gt;</screen>\r
  84                 <para>The limit records imported or edited following the supplied date will be returned. If you do not supply a date, then the most recent limit records will be returned.</para>\r
  85                 <para>If you do not supply a limit, then up to 10 records will be returned.</para>      \r
  86                 <para>Feed-type can be one of atom, html, htmlholdings, marcxml, mods, mods3, or rss2.</para>           \r
  87                 <para>For example, http://dev.gapines.org/opac/extras/feed/freshmeat/atom/biblio/import/10/2008-01-01</para>\r
  88         </simplesect>\r
  89          <simplesect>\r
  90                 <title>Browse records</title>\r
  91                 <para>SuperCat can browse records in HTML and XML formats:</para>\r
  92                 <screen>http://&lt;hostname&gt;/opac/extras/supercat/browse/&lt;format&gt;/call_number/&lt;org_unit&gt;/&lt;call_number&gt;</screen>\r
  93                 <para>For example, http://dev.gapines.org/opac/extras/browse/xml/call_number/-/GV returns:</para>\r
  94                 <programlisting>\r
  95                 &lt;hold:volumes xmlns:hold='http://open-ils.org/spec/holdings/v1'&gt;\r
  96                         &lt;hold:volume id="tag:open-ils.org,2008:asset-call_number/130607" lib="FRRLS-FA" label="GUTCHEON BETH"&gt;\r
  97                                 &lt;act:owning_lib id="tag:open-ils.org,2008:actor-org_unit/111" name="Fayette County Public Library"/&gt;\r
  98                                 &lt;record xsi:schemaLocation="http://www.loc.gov/MARC21/slim http://www.loc.gov/ \r
  99                                         standards/marcxml/schema/MARC21slim.xsd"\r
 100                                         id="tag:open-ils.org,2008:biblio-record_entry/21669/FRRLS-FA"&gt;\r
 101                                         &lt;leader&gt;09319pam a2200961 a 4500&lt;/leader&gt;\r
 102                                         &lt;controlfield tag="001"/&gt;\r
 103                                         &lt;controlfield tag="005"&gt;20000302124754.0&lt;/controlfield&gt;\r
 104                                         &lt;controlfield tag="008"&gt;990817s2000    nyu           000 1 eng  &lt;/controlfield&gt;\r
 105                                         &lt;datafield tag="010" ind1=" " ind2=" "&gt;\r
 106                                                 &lt;subfield code="a"&gt;   99045936&lt;/subfield&gt;\r
 107                                         &lt;/datafield&gt;\r
 108                                         ..\r
 109                                 &lt;/record&gt;\r
 110                                 &lt;record&gt;\r
 111                                         ..\r
 112                                 &lt;/record&gt;\r
 113                         &lt;/hold:volume&gt;\r
 114                 &lt;/hold:volumes&gt;   \r
 115                 </programlisting>\r
 116         </simplesect>\r
 117          <simplesect xml:id="supportedsupercatformats">\r
 118                 <title>Supported formats</title>\r
 119                 <para>SuperCat maintains a list of supported formats for records and metarecords:</para>\r
 120                 <screen>http://&lt;hostname&gt;/opac/extras/supercat/formats/&lt;record-type&gt;</screen>\r
 121                 <para>For example, http://dev.gapines.org/opac/extras/supercat/formats/record returns:</para>\r
 122                 <programlisting>\r
 123                 &lt;formats&gt;\r
 124 \r
 125                   &lt;format&gt;\r
 126                     &lt;name&gt;opac&lt;/name&gt;\r
 127                     &lt;type&gt;text/html&lt;/type&gt;\r
 128                   &lt;/format&gt;\r
 129 \r
 130                   &lt;format&gt;\r
 131                     &lt;name&gt;htmlholdings&lt;/name&gt;\r
 132                     &lt;type&gt;text/html&lt;/type&gt;\r
 133                   &lt;/format&gt;\r
 134                  \r
 135                   &lt;format&gt;\r
 136                     &lt;name&gt;html&lt;/name&gt;\r
 137                     &lt;type&gt;text/html&lt;/type&gt;\r
 138                   &lt;/format&gt;\r
 139                  \r
 140                   &lt;format&gt;\r
 141                     &lt;name&gt;htmlholdings-full&lt;/name&gt;\r
 142                     &lt;type&gt;text/html&lt;/type&gt;\r
 143                   &lt;/format&gt;\r
 144                  \r
 145                   &lt;format&gt;\r
 146                     &lt;name&gt;html-full&lt;/name&gt;\r
 147                     &lt;type&gt;text/html&lt;/type&gt;\r
 148                   &lt;/format&gt;\r
 149                  \r
 150                   &lt;format&gt;\r
 151                     &lt;name&gt;marcxml&lt;/name&gt;\r
 152                     &lt;type&gt;application/xml&lt;/type&gt;\r
 153                     &lt;namespace_uri&gt;http://www.loc.gov/MARC21/slim&lt;/namespace_uri&gt;\r
 154                     &lt;docs&gt;http://www.loc.gov/marcxml/&lt;/docs&gt;\r
 155                  \r
 156                     &lt;schema_location&gt;\r
 157                     http://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd\r
 158                     &lt;/schema_location&gt;\r
 159                   &lt;/format&gt;\r
 160                  \r
 161                   &lt;format&gt;\r
 162                     &lt;name&gt;marcxml-full&lt;/name&gt;\r
 163                     &lt;type&gt;application/xml&lt;/type&gt;\r
 164                     &lt;namespace_uri&gt;http://www.loc.gov/MARC21/slim&lt;/namespace_uri&gt;\r
 165                     &lt;docs&gt;http://www.loc.gov/marcxml/&lt;/docs&gt;\r
 166                  \r
 167                     &lt;schema_location&gt;\r
 168                     http://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd\r
 169                     &lt;/schema_location&gt;\r
 170                   &lt;/format&gt;\r
 171                  \r
 172                   &lt;format&gt;\r
 173                     &lt;name&gt;rss2&lt;/name&gt;\r
 174                     &lt;type&gt;application/xml&lt;/type&gt;\r
 175                   &lt;/format&gt;\r
 176                  \r
 177                   &lt;format&gt;\r
 178                     &lt;name&gt;rss2-full&lt;/name&gt;\r
 179                     &lt;type&gt;application/xml&lt;/type&gt;\r
 180                   &lt;/format&gt;\r
 181                  \r
 182                   &lt;format&gt;\r
 183                     &lt;name&gt;rdf_dc&lt;/name&gt;\r
 184                     &lt;type&gt;application/xml&lt;/type&gt;\r
 185                     &lt;namespace_uri&gt;http://purl.org/dc/elements/1.1/&lt;/namespace_uri&gt;\r
 186                     &lt;schema_location&gt;http://purl.org/dc/elements/1.1/&lt;/schema_location&gt;\r
 187                   &lt;/format&gt;\r
 188                  \r
 189                   &lt;format&gt;\r
 190                     &lt;name&gt;oai_dc&lt;/name&gt;\r
 191                     &lt;type&gt;application/xml&lt;/type&gt;\r
 192                     &lt;namespace_uri&gt;http://www.openarchives.org/OAI/2.0/oai_dc/&lt;/namespace_uri&gt;\r
 193                     &lt;schema_location&gt;http://www.openarchives.org/OAI/2.0/oai_dc.xsd&lt;/schema_location&gt;\r
 194                   &lt;/format&gt;\r
 195                  \r
 196                   &lt;format&gt;\r
 197                     &lt;name&gt;srw_dc&lt;/name&gt;\r
 198                     &lt;type&gt;application/xml&lt;/type&gt;\r
 199                     &lt;namespace_uri&gt;info:srw/schema/1/dc-schema&lt;/namespace_uri&gt;\r
 200                  \r
 201                     &lt;schema_location&gt;\r
 202                     http://www.loc.gov/z3950/agency/zing/srw/dc-schema.xsd\r
 203                     &lt;/schema_location&gt;\r
 204                   &lt;/format&gt;\r
 205                  \r
 206                   &lt;format&gt;\r
 207                     &lt;name&gt;mods32&lt;/name&gt;\r
 208                     &lt;type&gt;application/xml&lt;/type&gt;\r
 209                     &lt;namespace_uri&gt;http://www.loc.gov/mods/v3&lt;/namespace_uri&gt;\r
 210                     &lt;docs&gt;http://www.loc.gov/mods/&lt;/docs&gt;\r
 211                     &lt;schema_location&gt;http://www.loc.gov/standards/mods/v3/mods-3-2.xsd&lt;/schema_location&gt;\r
 212                   &lt;/format&gt;\r
 213                  \r
 214                   &lt;format&gt;\r
 215                     &lt;name&gt;mods3&lt;/name&gt;\r
 216                     &lt;type&gt;application/xml&lt;/type&gt;\r
 217                     &lt;namespace_uri&gt;http://www.loc.gov/mods/v3&lt;/namespace_uri&gt;\r
 218                     &lt;docs&gt;http://www.loc.gov/mods/&lt;/docs&gt;\r
 219                     &lt;schema_location&gt;http://www.loc.gov/standards/mods/v3/mods-3-1.xsd&lt;/schema_location&gt;\r
 220                   &lt;/format&gt;\r
 221                  \r
 222                   &lt;format&gt;\r
 223                     &lt;name&gt;mods3-full&lt;/name&gt;\r
 224                     &lt;type&gt;application/xml&lt;/type&gt;\r
 225                     &lt;namespace_uri&gt;http://www.loc.gov/mods/v3&lt;/namespace_uri&gt;\r
 226                     &lt;docs&gt;http://www.loc.gov/mods/&lt;/docs&gt;\r
 227                     &lt;schema_location&gt;http://www.loc.gov/standards/mods/v3/mods-3-1.xsd&lt;/schema_location&gt;\r
 228                   &lt;/format&gt;\r
 229                  \r
 230                   &lt;format&gt;\r
 231                     &lt;name&gt;mods&lt;/name&gt;\r
 232                     &lt;type&gt;application/xml&lt;/type&gt;\r
 233                     &lt;namespace_uri&gt;http://www.loc.gov/mods/&lt;/namespace_uri&gt;\r
 234                     &lt;docs&gt;http://www.loc.gov/mods/&lt;/docs&gt;\r
 235                     &lt;schema_location&gt;http://www.loc.gov/standards/mods/mods.xsd&lt;/schema_location&gt;\r
 236                   &lt;/format&gt;\r
 237                  \r
 238                   &lt;format&gt;\r
 239                     &lt;name&gt;mods-full&lt;/name&gt;\r
 240                     &lt;type&gt;application/xml&lt;/type&gt;\r
 241                     &lt;namespace_uri&gt;http://www.loc.gov/mods/&lt;/namespace_uri&gt;\r
 242                     &lt;docs&gt;http://www.loc.gov/mods/&lt;/docs&gt;\r
 243                     &lt;schema_location&gt;http://www.loc.gov/standards/mods/mods.xsd&lt;/schema_location&gt;\r
 244                   &lt;/format&gt;\r
 245                  \r
 246                   &lt;format&gt;\r
 247                     &lt;name&gt;atom&lt;/name&gt;\r
 248                     &lt;type&gt;application/xml&lt;/type&gt;\r
 249                     &lt;namespace_uri&gt;http://www.w3.org/2005/Atom&lt;/namespace_uri&gt;\r
 250                     &lt;docs&gt;http://www.ietf.org/rfc/rfc4287.txt&lt;/docs&gt;\r
 251                   &lt;/format&gt;\r
 252                  \r
 253                   &lt;format&gt;\r
 254                     &lt;name&gt;atom-full&lt;/name&gt;\r
 255                     &lt;type&gt;application/xml&lt;/type&gt;\r
 256                     &lt;namespace_uri&gt;http://www.w3.org/2005/Atom&lt;/namespace_uri&gt;\r
 257                     &lt;docs&gt;http://www.ietf.org/rfc/rfc4287.txt&lt;/docs&gt;\r
 258                   &lt;/format&gt;\r
 259                 &lt;/formats&gt;\r
 260                 </programlisting>\r
 261         </simplesect>\r
 262         <simplesect>\r
 263                 <title>Adding new SuperCat formats</title>      \r
 264                 <para>SuperCat web services are based on the OpenSRF application, <emphasis>open-ils.supercat</emphasis>.</para> \r
 265                 <para>Developers are able to add new formats by adding the <emphasis>xsl</emphasis> \r
 266                 stylesheet for the format in the directory<filename class="directory">/openils/var/web/opac/extras/xsl/</filename>, and by adding the feed references to the perl modules \r
 267                 <filename>openils/lib/perl5/OpenILS/WWW/SuperCat/feed.pm</filename> and <filename>openils/lib/perl5/OpenILS/WWW/SuperCat.pm</filename>. An Evergreen restart is \r
 268                 required for the new format to be activated.</para>\r
 269                 <tip><para>Use an existing xsl stylesheet and perm module entry as a guide for your new format.</para></tip>\r
 270         </simplesect>\r
 271 </chapter>\r
 272 \r