Tech Blog

Use an External Viewer with the Digital Delivery Service

Avatarby Josh Weisman Ex Libris August 13, 2017 (Updated: November 28, 2018)
ALMA DIGITAL

In a previous post, we showed how to use the IA Book Reader with digital content managed in Alma. Our example used the BIB and file APIs to retrieve the information necessary to display our content in the viewer.

Several recent improvements to Alma allow us to make this flow more efficient. These new features include:

  • Digital delivery service: Alma now supports a CORS-enabled endpoint which returns a digital representation in JSON format. We can call this service directly from the browser and benefit from a cleaner interface with fewer API calls. The delivery service also checks access rights based on the user’s context (IP, etc.)
  • Viewer definition and rules: Alma now supports defining viewers along with rules which determine which viewer(s) will be offered to a user in the discovery context. This means we can configure our book reader as a viewer in Alma, and a patron can view a digitized book in an optimized experience directly from discovery

In this blog post, we’ll walk through the changes we made to our previous viewer to consume the new service, and the configuration required in Alma to link to our viewer.

Call the digital delivery service

We added support in our viewer for a “service” parameter. If received, we use the jQuery ajax method to retrieve the service provided. The URL is the same as for Alma delivery, only with an Accept header of application/json.

GET https://alma.exlibrisgroup.com/view/delivery/INSTITUTION/REP_ID
Accept: application/json

We set a few properties on the returned object to adapt to the way metadata properties are returned in the service (and to provide backwards compatibility with our previous REST API-based implementation).

$.ajax({
  dataType: "json", url: service, 
  xhrFields: { withCredentials: true } 
})
.done(
  function(data) {
    bib = data;
    bib.title = getMetadata('Title');
    bib.author = getMetadata('Creator');
  }
)

The delivery service returns the same metadata as configured for the Alma viewer in an array. To find the field we’re interested in, we can search in the array:

function getMetadata(name) {
  var item = bib.metadata.find(function(x) { return x.label == name});
  if (item) return item.value;
}

Handling Access Rights

The delivery service supports access rights in the context of the user’s browser session. Based on the access rights conditions, the service will return an appropriate HTTP status code (200, 403).

If we have access rights that depend on a logged-in user, we need to tell the browser to send the session cookie to Alma along with the AJAX service request. That’s done with the withCredentials parameter in the call above.

In our response handler, we can add code which handles a 403 response code.

.fail(
  function(jqXHR, textStatus, errorThrown) {
    var msg;
    if (errorThrown=='Forbidden') {
      msg = 'You don\'t seem to have access to this material.';
      msg += '\n(' + jqXHR.getResponseHeader('X-Denied-Message') +')';
    } else {
      console.log('errorThrown', errorThrown);
      msg = 'Cannot retrieve service. ';
    }
  alert(msg);
  }
);

Alma returns the configured access denied message in an “X-Denied-Message” header, which we can display to users:

Configure the viewer in Alma

In order for our viewer to be displayed in fulfillment options, we need to add it as a viewer service and set the rules under which it will appear. We go to “Viewer Services” in Alma Configuration and add a new viewer service. We add the URL to our viewer and include the representation PID placeholder in the appropriate location.

Next we need to update the rules. Alma allows us to base the display of our viewer on several parameters, including the bibliographic record’s material type, the representation’s usage type, or the file names. Here we choose to display the book reader for derivative copies of material type “book”:

And now when we view the fulfillment options, we see a link to our external viewer:

With the new delivery service, it’s easy to link to your external viewer from within Alma. The code for this post is available in this Github repository.

Leave a Reply