The Problem
It isn’t easy to communicate to patrons what serials they have access to and in what form (print, online). They can find these details, sure, but it’s scattered across our library’s web presence. What’s most frustrating is that we clearly have all the necessary information but the systems offer no built-in way to produce a clear display of it. My fellow librarians noted that “it’d be nice if the catalog showed our exact online holdings” and my initial response was to sigh and say “yes, that would be nice”.
To illustrate the scope of the problem, a user can search for journals in a few of our disparate systems:
- we use a knowledgebase to track database subscriptions and which journals are included in each subscription package
- the public catalog for our Koha ILS has records for our print journals, sometimes with a MARC 856$u 1 link to our online holdings in the knowledgebase
- our discovery layer has both article-level results for the journals in our knowledgebase and journal-level search results for the ones in our catalog
While these systems overlap, they also serve distinct purposes, so it’s not so awful. However, there are a few downsides to our triad of serials information systems. First of all, if a patron searches the knowledgebase looking for a journal which we only have in print, our database holdings wouldn’t show that they have access to print issues. To work around this, we track our print issues both in our ILS and the knowledgebase, which duplicates work and introduces possible inconsistencies.
Secondly, someone might start their research in the discovery layer, finding a journal-level record that links out to our catalog. But it’s too much to ask a user to search the discovery layer, click into the catalog, click a link out to the knowledgebase, and only then discover our online holdings don’t include the particular volume they’re looking for. Possessing three interconnected systems creates labyrinthine search patterns and confusion amongst patrons. Simply describing the systems and their nuanced areas of overlap in this post feels like challenge, and the audience is librarians. I can imagine how our users must feel when we try to outline the differences.
The 360 XML API
Our knowledgebase is Serials Solutions 360KB. I went looking in the vendor’s help documentation for answers, which refers to an API for the product but apparently provides no information on using said API. Luckily, a quick search through GitHub projects yielded several using the API and I was able to determine its URL structure: http://{{your Serials Solution ID}}.openurl.xml.serialssolutions.com/openurlxml?version=1.0&url_ver=Z39.88-2004&issn={{the journal’s ISSN}}
It’s probably possible to search by other parameters as well, but for my purposes ISSN was ideal so I didn’t bother investigating further. If you send a request to the address above, you receive XML in response:
<ssopenurl:openURLResponse xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:ssdiag="http://xml.serialssolutions.com/ns/diagnostics/v1.0" xmlns:ssopenurl="http://xml.serialssolutions.com/ns/openurl/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xml.serialssolutions.com/ns/openurl/v1.0 http://xml.serialssolutions.com/ns/openurl/v1.0/ssopenurl.xsd http://xml.serialssolutions.com/ns/diagnostics/v1.0 http://xml.serialssolutions.com/ns/diagnostics/v1.0/diagnostics.xsd">
<ssopenurl:version>1.0</ssopenurl:version>
<ssopenurl:results dbDate="2017-02-15">
<ssopenurl:result format="journal">
<ssopenurl:citation>
<dc:source>Croquis</dc:source>
<ssopenurl:issn type="print">0212-5633</ssopenurl:issn>
</ssopenurl:citation>
<ssopenurl:linkGroups>
<ssopenurl:linkGroup type="holding">
<ssopenurl:holdingData>
<ssopenurl:startDate>1989</ssopenurl:startDate>
<ssopenurl:providerId>PRVLSH</ssopenurl:providerId>
<ssopenurl:providerName>Library Specific Holdings</ssopenurl:providerName>
<ssopenurl:databaseId>ZYW</ssopenurl:databaseId>
<ssopenurl:databaseName>CCA Print Holdings</ssopenurl:databaseName>
<ssopenurl:normalizedData>
<ssopenurl:startDate>1989-01-01</ssopenurl:startDate>
</ssopenurl:normalizedData>
</ssopenurl:holdingData>
<ssopenurl:url type="source">https://library.cca.edu/</ssopenurl:url>
<ssopenurl:url type="journal">
https://library.cca.edu/cgi-bin/koha/opac-search.pl?idx=ns&q=0212-5633
</ssopenurl:url>
</ssopenurl:linkGroup>
</ssopenurl:linkGroups>
</ssopenurl:result>
</ssopenurl:results>
<ssopenurl:echoedQuery timeStamp="2017-02-15T16:14:12">
<ssopenurl:library id="EY7MR5FU9X">
<ssopenurl:name>California College of the Arts</ssopenurl:name>
</ssopenurl:library>
<ssopenurl:queryString>version=1.0&url_ver=Z39.88-2004&issn=0212-5633</ssopenurl:queryString>
</ssopenurl:echoedQuery>
</ssopenurl:openURLResponse>
If you’ve read XML before, then it’s apparent how useful the above data is. It contains a list of our “holdings” for the periodical with information about the start and end (absent here, which implies the holdings run to the present date) dates of the subscription, which database they’re in, and what URL they can be accessed at. Perfect! The XML contains precisely the information we want to display in our catalog.
Unfortunately, our catalog’s JavaScript doesn’t have permission to access the 360 XML API. Due to a browser security policy resources must explicitly say that other domains or pages are allowed to request their data. A page needs to include the Access-Control-Allow-Origin HTTP header to abide by this policy, called Cross-Origin Resource Sharing (CORS), and the 360 API does not.
We can work around this limitation but it requires extra code on our part. While JavaScript from a web page cannot request data directly from 360, we can write a server-side script to pull data. That server-side script can then add its own CORS header which lets our catalog use it. So, in essence, we set up a proxy service that acts as a go-between for our catalog and the API that the catalog cannot use. Typically, this takes little code; the server-side script takes a parameter passed to it in the URL, sends it in a HTTP request to another server, and serves back up whatever response it receives.
Of course, it didn’t turn out to be that simple in practice. As I experimented with my scripts, I could tell that the 360 data was being received, but I couldn’t parse meaningful pieces of information out of it. It’s clearly there; I could see the full XML structure with holdings details. But neither my server-side PHP nor my client-side JavaScript could “find” XML elements like <ssopenurl:linkGroup> and <ssopenurl:normalizedData>. The text before the colon in the tag names is the namespace. Simple jQuery code like $('ssopenurl:linkGroup', xml), which can typically parse XML data, wasn’t working with these namespaced elements.
Finally, I discovered the solution by reading the PHP manual’s entry for the simplexml_load_string function: I can tell PHP how to parse namespaced XML by passing a namespace parameter to the parser function. So my function call turned into:
// parameters: 1) serials solution data since $url is the API we want to pull from // 2) the type of object that the function should return (this is the default) // 3) Libxml options (also the default, no special options) // 4) (finally!) ns, the XML namespace // 5) "True" here means ns is a prefix and not a URI $xml= simplexml_load_string( file_get_contents($url), 'SimpleXMLElement', 0, 'ssopenurl', True );
As you can see, two of those parameters don’t even differ from the function’s defaults, but I still need to provide them to get to the “ssopenurl” namespace later. As an aside, technical digressions like these are some of the best and worst parts of my job. It’s rewarding to encounter a problem, perform research, test different approaches, and eventually solve it. But it’d also be nice, and a lot quicker, if code would just work as expected the first time around.
The Catalog
We’re lucky that Koha’s catalog both allows for JavaScript customization and has a well-structured, easy-to-modify record display. Now that I’m able to grab online holdings data from our knowledgebase, inserting into the catalog is trivial. If you wanted to do the same with a different library catalog, the only changes come in the JavaScript that finds ISSN information in a record and then inserts the retrieved holdings information into the display. The complete outline of the data flow from catalog to KB and back looks like:
- my JavaScript looks for an ISSN on the record’s display page
- if there’s an ISSN, it sends the ISSN to my proxy script
- the proxy script adds a few parameters & asks for information from the 360 XML API
- the 360 XML API returns XML, which my proxy script parses into JSON and sends to the catalog
- the catalog JavaScript receives the JSON and parses holdings information into formatted HTML like “Online resources: 1992 to present in DOAJ“
- the JS inserts the formatted text into the record’s “online resources” section, creating that section if it doesn’t already exist
Is there a better way to do this? Almost certainly. The six steps above should give you a sense of how convoluted the process is, hacking around a few limitations. Still, the outcome is positive: we stopped updating our print holdings in our knowledgebase and our users have more information at their fingertips. It obviates the final step in the protracted “discovery layer to catalog” search described in the opening of this post.
Our next steps are obvious, too: we should aim to get this information into the discovery layer’s search results for our journals. The general frame of this project would be the same; we already know how to get the data from the API. Much like working with a different library catalog, the only edits are in parsing ISSNs from discovery layer search results and finding a spot in the HTML to insert the holdings data. Finally, we can also remove the redundant and less useful 856$u links from our periodical MARC records now.
The Scripts
These are highly specific to our catalog, but may be of general use to others who want to see how the pieces work together: