Tech Blog

Integrating Blacklight with Alma

As an open library management system, Alma can integrate with third party discovery platforms. In previous blog posts, we’ve shown how to harvest repository information from Alma into an AWS CloudSearch (Lucene) instance, and how to integrate with Alma to obtain real time availability and and fulfillment services. In this post, we should how to use the documented techniques to integrate Alma with the Blacklight discovery solution.


To begin, follow the Blacklight Quick Start instructions to set up a vanilla Blacklight installation. Use either the built-in Solr instance, or deploy your own Solr instance using the included configuration. All of the code and files referenced below are available in the Alma/Blacklight Github repository.

Harvest into Solr

We need to get some records into our Solr index. First, configure an OAI-based publishing profile in Alma. Specify the set of records you want to include, and call the OAI set spec “blacklight.” Then run the publishing job for the publishing profile.

Now that the records are published, we need to harvest them. For that, we’ve defined a rake task called oai_harvest. We’re using a rake task so that it can be automated and scheduled to run later. At first, we need to do an initial harvest of all records. The task saves the last run time so that subsequent executions will harvest records incrementally. Our task uses the Solrmarc library to index the MARC records in Solr.

The oai_harvest task does the following:

  • Retrieves the last run time
  • Constructs a properly formed OAI request
  • For each set of records retrieved from Alma,
    • Identifies any deleted records and deletes them from the Solr index
    • Creates a file with the remaining records to be indexed
    • Executes SolrMarc on the saved file
    • Extracts the resumption token to retrieve the next batch of records
  • Save the current run time as the starting point for the next execution

The output of the oai_harvest execution looks as follows (with no records to process):

$ rake oai_harvest

2016-07-18 13:54:54 - Starting...
2016-07-18 13:54:54 - Set 'from' time to: 2016-07-18T07:50:09Z
2016-07-18 13:54:54 - Set 'to' time to: 2016-07-18T10:54:54Z
2016-07-18 13:54:54 - Calling OAI with query string ?verb=ListRecords&set=blacklight&metadataPrefix=marc21&until=2016-07-18T10:54:54Z&from=2016-07-18T07:50:09Z
2016-07-18 13:54:59 - Found 0 deleted records.
2016-07-18 13:54:59 - 0 records retrieved
2016-07-18 13:54:59 - Storing 'to' time
2016-07-18 13:54:59 - Complete

Real Time Availability

We now have records in our Solr instance and we can perform searches in Blacklight. The next step is to add functionality to check the real time availability of the returned records and display feedback to the user. For this we will use the retrieve BIB API. This API has an mms_id parameter which accepts a list of document IDs, and x_avail parameters which indicate that we’re interested in availability information.

To add availability information to the search results, we need to add the following:

  • An Alma module in app/models/concerns/Alma.rb, which exposes a method called get_bibs_availability. The method calls the retrieve BIBs API, parses the result, and returns a structure which indicates online and print availability. For print, we indicate if there are items which can be loaned.
  • A method in the catalog controller which calls the method above and passes in the relevant MMS IDs.
  • A route for availability in the catalog resource in config/routes.rb
  • A new view in app/views/catalog/_show_availability.html.erb, which adds a physical and online button for each document
  • A JavaScript function in app/assets/javascript/catalog.js which collects all of the document IDs which were returned, calls the catalog controller, and updates the CSS class of the print and online buttons
  • Two overridden views in app/views/catalog/:
    • _document.html.erb where we render the availability partial
    • _document_list.html.erb) which calls the JavaScript function to update availability for both full page and AJAX search results

The screenshot below shows availability indicated by the colorful buttons in the Blacklight search results:


Fulfillment Services

Each bibliographic record returned from Alma has¬†detailed fulfillment options. For titles which have on-line versions (digital and electronic), we want to display the available full text and delivery services. For print titles, we want to display each of the locations and its copies, along with detailed item status and loan policy information. We also want to provide the ability for patrons to place requests. Instead of adding all of that code and complexity to our application, we “outsource” that functionality to Alma by implementing the fulfillment services as a mash-up. This approach provides an integrated and seamless experience for our users while removing the burden of replicating and maintaining complex fulfillment logic.

Details on how to build the URL for the fulfillment services page are available here. In the URL, we need to provide the MMS ID (saved in Solr as the document ID) and whether we want the print or on-line services (“get it” or “view it”). We’ve decided to expose the fulfillment services as a mash-up within the Blacklight search results page. This approach allows the user experience to remain within our discovery application.

The end results appears below:

Using this approach we can also leverage the Alma infrastructure to display digital objects stored in Alma. Following the instructions provided in the integration documentation, we added the appropriate links to our Blacklight search results page. Now digital materials are opened in a lightbox above the discovery interface, maintaining the integrated user experience.


Blacklight provides functionality to logged in users such as bookmarks, search history, and saved searches. Ideally, we want to provide a single sign on experience and not provide on-off user names for library discovery. This can be accomplished by leveraging the institutional identify management system. In addition, Alma now supports social login for both staff and patrons. This means we can allow users to log in with their social network credentials to gain access to additional features. Check the documentation for full details on how to set up social login in Alma. We followed the Blacklight authentication guide to add Alma social login as a custom authentication method.

To enable social login in Blacklight, we need to:

  • Add the ‘jwt’ gem to the Gemfile to parse the JWT received from Alma
  • Add the authentication related routes to config/routes.rb
  • Add a from_jwt method to the User model in app/models/user.rb to create or update a user object based on the JWT received from Alma
  • Add a sessions controller in app/controllers/sessions_controller.rb which:
    • Accepts the JWT from Alma, validates it, and creates a User object
  • Add a current_user method to app/controllers/application_controller.rb

Now when users click on the Login link, they are taken to Alma where they complete the social login flow. Then they’re redirected to Blacklight, a session is created, and they are logged in.

Single Sign on with the Mash-Up

The fulfillment services feature in Alma supports single sign on via SAML or social via OAuth. In our case, we’ve authenticated the user with social login, so we’ve passed a ‘social’ parameter to the URL of the mash-up. Now the user sees fulfillment options appropriate to their user account, and can perform requests on the selected item.

Patron Details

As a final step in the integration, we will now provide patron details from Alma in Blacklight. Blacklight expects a route called ‘edit_user_registration’ and uses it as the destination when clicking on a signed-in user’s name. We have connected that route to the show method of a (patron) card controller. The show method retrieves user details from Alma and displays them in a simple view. We’ve expanded the controller and added views to provide some additional functionality for the patron based on the user APIs. Other functionality might include:

  • View or update user information
  • View or cancel requests
  • View or renew loans
  • View or pay fines

Wrapping Up

We’ve now successfully integrated Alma with Blacklight, showing search results, real time availability, fulfillment services, and patron information. Of course, the possibilities for customization are endless so this is just the beginning. But the code provided in Alma/Blacklight Github repository should be a good starting point.


Leave a Reply