Umlaut in terms of DLF ILS Discovery API model

I realized it would be useful to analyze Umlaut in terms of the DLF ILS Discovery API model.

Umlaut needs to talk to my OPAC/ILS in order to display local holdings, with availability and location, as well as a button to place a request/hold with the ILS.

DLF Task Force Model Functions Used

What Umlaut currently does is described very well by the DLF task force model functions, which I’ll list in the order that Umlaut calls them:

6.3.3 Search (Level 2) (Identify ILS records with certain ISBNs, ISSNs, LCCNs, OCLCnums, or as a last resort title and author keyword matches–along with specifications of format limits in some cases, only serials, etc.).

6.3.1 GetAvailability (Level 1) [Specifically of type ‘item’] (Figure out location and availability for items for the bibs identified previously, to display).

8.3.1 GoToBibliographicRequestPage (Level 1) (Umlaut puts a ‘request’ button on the Umlaut page, and sends user to the ILS/OPAC to actually make the request, when clicked).

Also, Umlaut doesn’t currently do this, but I would love it to use:

7.2.5 GetServices (Level 3)  (To figure out whether the ‘request’ button should even be displayed in the first/place, and possibly additionally tell the user more about what they can with this item possibly not involving the ‘request’ button).

I haven’t implemented that mainly because hacking it into Horizon is a pain (although not impossible with direct-sql access to the underlying Sybase db, as you have with Horizon. I understand what it would take, it would just not be fun).

Interesting that one Level 2 service is required for Umlaut to do what it does.

Suggests Umlaut Implementation Improvements

I hacked all these in before the DLF recommendations even existed, so they aren’t written in terms of the DLF services. (And it’s to the DLF reccommendations credit that they properly and accurately describe my real world use case).  But it strikes me that it would be of benefit to re-write the Umlaut code so it is specifically factored and described in terms of those services. It would make it very clear what needs to be done to add support for a new ILS/OPAC too—add classes that can provide that search(), getAvailability(), and goToBibliographicRequestPage() functionality for your particular ILS–and already written common Umlaut code will take care of the rest.   If your ILS miraculously already supported the DLF functionality, that might already be done for you, but if not, you know exactly what you need to write, hacking into your ILS somehow.

(Incidentally, I personally suspect that even in a hypothetical future case where your ILS claims to support those functions, there will be enough idiosyncracies that you’d still need to write some specific Umlaut code to rationalize and normalize things a bit. This doesn’t disturb me greatly though, one step at a time. Realistic expectations.)

Ross was actually already moving the Umlaut code in that direction of having clearly defined ILS-specific functional modules for an ILS, that are then used by common Umlaut code–although he too was writing before the DLF task force, so it wasn’t written in exactly those terms. The DLF task force spec is actually an aid in architecting such a system, they’ve already helped you factor out your functionality.  But anyway, I inherited Umlaut from Ross with this aspect being not entirely finished, and for expediency didn’t finish carrying out that direction. But I ought to refactor Umlaut in that direction, specifically around the DLF task force model. If any other institution actually expresses a real interest in Umlaut, that’ll probably be my motivation to do so.


There are a few practical kinks that would keep the code from being a perfect 1-to-1 mapping of the DLS task force model functions. For instance, in a single request to HIP for ‘6.3.3 Search (Level 2)’, I actually get back complete bib records from HIP, not just local bib #s. And HIP is slow enough at all this, that you really wouldn’t want to make a second request to HIP just for the sake of sticking to the model. So I imagine an Umlaut adapter for 6.3.3 Search could optionally return MARC bibs, in which case Umlaut woudln’t need to make a call to etc.) 6.3.1 GetAvailability — or could just return bibIDs, sticking to the DLF task force model, in which case Umlaut would proceed to making a seperate 6.3.1 GetAvailability call after all. No big deal.

Somewhat more troubling…

Also, GetAvailabilty is going to be a little bit tricky for serials. Horizon identifies not just two levels for serials (Bib and Item), but three:  Bib, which can contain zero to many Copies (which might better be called ‘Runs’ or maybe something else, but Horizon calls them ‘copies’) which can contain 0 to many ‘Items’.  At the ‘Copy’ level is where summary holdings statements are stored, which are very important for Umlaut to get and display for a useable interface. It’s only at the ‘Item’ level that a request can be placed though.  It’s generally at the ‘Copy’ level that ‘Location’ is associated with–at least the way we use Horizon. I think it’s theoretically possible for Bib or Item to have possibly different ‘locations’ too.

I’m not sure the simple DLF schema for availability is actually capable of supporting this. It’s good that the DLF schema is kept simple, but for getting what I actually need for serials from Horizon, I’m not sure it would work. I think some other ILSs use a three-level model for serials (and occasionally multi-volume works) too, no?


2 thoughts on “Umlaut in terms of DLF ILS Discovery API model

  1. 6.3.3 Search is intended to retrieve full expanded records, not just bib identifiers. I hope the document doesn’t suggest that only identifiers are returned!

    Our initial intention for GetAvailability was intended to be able to support more complex return schemas than just the dlf:simpleavailability element. For instance, it could return ISO 20775, which is capable of accommodating all levels of info, I believe.

    There is a simpler resonse, though. GetAvailability is really intended to provide copy-specific info for requesting. So if you are displaying summary holdings in Umlaut, there’s no reason not to obtain that less-volatile information via the initial search response. Then GetAvailability can be used for more volatile item-level information (actually, in this scenario the search response should be able to give you everything you need). The only issue I see here is with elements like ‘location’ that in the dlf:simpleavailability response. However, this is an option element that could be excluded. Or you could mashup the copy-level ‘location’ information with the item-level information in the GetAvailability response. Since every ILS has a different data model, it’s difficult to design a schema or response that accommodates them all without any of this type of re-normalization.

  2. Thanks Emily. I see now that 6.3.3 Search can/should return full records in MARC on request. Actually, wait, the issue was not full MARC, but availability info. On re-reading the 6.3.3 search, it doesn’t say anything about availability, my assumption was that 6.3.3 search would always return only bib information, without availability. But maybe that’s because my ILS doesn’t include item-level availability in it’s MARC; it does say that it can return MARC, maybe your ILS includes item level information in MARC, so we had different assumptions?

    Oh boy, this stuff sure does get tricky when you get to actually implementing it. Which is why I hope ‘the community’ can find a way to keep supporting/clarifying/ammending this model API, it’s going to need some tweaking once we actually start putting it through it’s paces.

    Still confused about your ‘simpler’ approach to the serials problem. Are you suggesting that 6.3.3 Search ought to return the summary holdings information attached to the copies? I guess that depends on how the provider implements 6.3.3 Search, which is still a bit loose, but that makes sense. But then when I find out about items from GetAvailability, I also need to know what ‘copy’ (ie ‘run’) a given ‘item’ belongs to, so it can be displayed appropriately. I don’t think there’s anthing in dlf:simpleavailability that would have that info. Of course it could be extended, but it’s just a roadblock in the ideal that an API consumer wouldn’t need any ILS-specific code, it could just know that it has GetAvailability returning dlf:simpleavailability. Instead, my consumer will need to know that Horizon GetAvailability has some special stuff in it, which should be handled appropriately? Or am I misunderstanding?

    But yeah, I suspect that ideal will not be reached in practice anyway. One step at a time.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s