Tech Blog

Integrating with the Alma Services Page

In previous blog posts, we provided details and examples on how to integrate Alma with open-source discovery solutions. Some best practices have changed over time, so in this post we’ll describe how to use the Alma services page to provide fulfillment options for titles and items in your repository. The documentation for integrating with open-source discovery is available in the Developer Network, including information on the services page.

There are a number of options for how to integrate a local discovery solution, and deciding which option to deploy depends on defining the goals of the integration. For many institutions, Primo provides the best of both worlds- supporting a rich set of customization options while supporting required functionality out-of-the-box. For those institutions who wish to have more control over their discovery experience, there are a number of different topologies available, depending on the level of control desired and the effort the institution is willing to invest. In the chart below, we list some options in ascending order of control and investment:

Discovery InterfaceSearch EngineFulfillment Options
1Primo VEPrimo VEServices Page
2Open Source (e.g. Blacklight)Primo VE (via API)Services Page
3Open Source (e.g. Blacklight)Local (e.g. Solr)Services Page
4Open Source (e.g. Blacklight)Local (e.g. Solr)Custom (via APIs)

In our demo Blacklight implementation, we’ve implemented option #3, running an instance of Blacklight, using a local Solr search engine for search, and linking to the Services Page. For each result, we link to the services page URL, passing in the MMS ID in the rft.mms_id parameter:

module CatalogHelper
  include Blacklight::CatalogHelperBehavior

  def openurl_base
    "https://#{ENV['alma']}{ENV['institution']}&vid=#{ENV['vid'] || ENV['institution'] + ':DEFAULT'}"

  def openurl(mms_id, service='viewit')
    openurl_base + "&u.ignore_date_coverage=true&rft.mms_id=#{mms_id}" 

Our Primo view has been customized to remove the top navigation and with colors to match our Blacklight theme, thereby providing a more seamless experience for our users:

.top-nav-bar {
  display: none;

Single-Sign-On with SAML

In order for a user’s session to pass from our discovery interface to the Services Page, we’ve implemented single sign on using SAML. Using the ruby-saml Gem we added SAML support to our Blacklight instance. Below is the code we added to the sessions controller to support the SAML login and to validate that the user exists in Alma.

sessions_controller.rbView on Github

We made our SAML integration profile the first option in discovery settings (Configuration -> Discovery -> User Authentication), and enabled silent login (as documented in the Primo online help):

The result is a seamless login experience for our SAML-based users.


To view this demo in action, you can visit the online version of the demo app, or the code in this Github repository.

Leave a Reply