Ready to Learn?Ex Libris products all provide open APIs

Discovering and Accessing Digital Content

Introduction

Alma provides an integrated delivery experience out-of-the-box. Staff users can access digital representations by clicking the “View it” link for a title in the search results. Patrons access digital material from a link in the “View it” tab in Primo. The ViewIt screen provides a list of digital services accessible to the user according to configured service display rules. For more information on configuring service display rules, see “Integrations with Primo -> Configuring Alma’s Delivery System -> Modifying Display Logic Rules” in the online help. Primo can be configured to show the digital material in a “lightbox” view, providing a seamless experience for users without leaving the Primo interface. See below for more information on the lightbox configuration.

If you have a custom discovery system you wish to integrate with Alma’s “View it” screen, see here. The following section provides information on additional access scenarios outside of those provided in Alma and Primo.

Delivery Services

Alma provides the following delivery services: 

Service NameLevelURL (prefixed by https://ALMA_DOMAIN)Use for
Alma Viewerrepresentation
/view/delivery/[MMS_ID | REPRESENTATION_ID] *
General/mixed material
Universal
Viewer
representation
/view/universalViewer?manifest=[MANIFEST_URL]
/view/universalViewer/REPRESENTATION_ID **

Images
Internet Archive
Book Reader
representation
/view/BookReaderViewer/REPRESENTATION_ID **
Images in book format
JSONrepresentation
/view/delivery/[MMS_ID | REPRESENTATION_ID] *
Accept: application/json
External viewers
IIIF Manifest
(v2.1)
representation
/view/iiif/presentation/[MMS_ID | REPRESENTATION_ID]/manifest *
External IIIF viewers
IIIF Canvas
(v2.1)
file
/view/iiif/presentation/REPRESENTATION_ID/canvas/FILE_ID
External IIIF viewers
File (binary)file
/view/delivery/REPRESENTATION_ID/FILE_ID
File download
* Delivery by MMS_ID redirects to a representation ID based on the following logic:
  1. first (lowest ID) derivative 
  2. first master
  3. first remote 

** Available as of October 2018 release. This endpoint also supports restricted objects.

Variables:

  • ALMA_DOMAIN: the Alma domain assigned to your institution (e.g. 'university' in https://university.alma.exlibrisgroup.com.
    • Note: Sandbox environments and older production environments with no Alma domain should send requests to their Alma instance and append the institution ID to /delivery, e.g. na01.alma.exlibrisgroup.com/view/delivery/01UNI_INST/REPRESENTATION_ID, https://eu.alma.exlibrisgroup.com/view/iiif/presentation/01UNI_INST/REPRESENTATION_ID/manifest 
  • REPRESENTATION_ID: The ID of the desired representation
  • FILE_ID: The ID of the desired file

Representation IDs and/or delivery URLs can be obtained in several ways, including:

  • The representation’s resource editor screen in Alma
  • Publishing, by specifying enrichment with digital inventory
  • SRU search, by specifying enrichment with digital inventory
  • Z39.50 search, by specifying enrichment with digital inventory
  • Retrieve Representations API

File IDs can be obtained by:

IIIF Manifestation/Canvas: Currently, Alma supports one file per canvas, and only images with open access (i.e. not restricted by login/user IP). 

JSON representations contain the same data that is displayed by the Alma viewer, including signed URLs, to be consumed by custom viewers. Note the required 'Accept: application/json' header. Cross-origin access (CORS) is allowed. When access rights criteria are not met, a 401/403 code is returned with the denied message in the 'X-Denied-Message' header. An example json response is available here

See also Thumbnail Delivery Service.

Lightbox configuration

The Alma representation view can be accessed directly (as described above) or from the Primo View It. When accessed from the ViewIt, the default behavior is for the viewer to be opened in a new tab. For a more integrated user experience, the viewer can be opened in a lightbox popup. This behavior allows the user to remain in the Primo or other discovery application user interface.

In order to have the viewer open in a lightbox, the following two lines should be added to the HTML page which hosts the ViewIt:

<link href="https://eu-st01.ext.exlibrisgroup.com/delivery/css/alma-delivery.css" media="screen" type="text/css" rel="stylesheet">
<script src="https://eu-st01.ext.exlibrisgroup.com/delivery/js/alma-delivery.js" type="text/javascript"></script>

These additions can be made in Primo or other discovery applications. For Primo, this is done in the header.html under the static_htmls directory (see help under Customizing Primo’s User Interface: Customizing Static HTML Files). 

Access Rights

When access rights deny access to a representation because the user is not logged in, Alma will return a "401 (unauthorized)" status. However, if access is denied despite the user being logged in, or if logging in won't grant access (e.g. access is restricted by IP range or embargo), Alma returns "403 (forbidden)". 

Export

To export the files related to a particular representation, a third party tool can be used to access the cloud storage and download the desired files. Files for a representation are stored in a single directory. A representation’s directory path can be obtained in one of the following ways:

The directory path can be calculated by performing an md5 hash on the representation ID, and then formatting the result in a pair-tree structure, with a slash between each two characters. Characters should be upper case. For example, the md5 hash for a representation ID of 12448642560001021 is 33a880608fa1db0e8c97c23624b20aff, and the path would be:

INSTITUTION_CODE/storage/alma/33/A8/80/60/8F/A1/DB/0E/8C/97/C2/36/24/B2/0A/FF/FILE_NAME

The Export Digital Titles Job will contain a storage path for each Alma representation (and a delivery URL for each remote representation) in a dc:identifier field for Dublin Core records. MARC records will hold the storage path in 856 subfield u and the file name(s) in repeated subfield f (delivery URL for remote representations in 856$$u).

Signed URLs

Files stored in Alma are private and cannot be accessed in a web browser without a valid signed URL. This prevents users from access files directly and bypassing access rights checks. If you are creating a custom viewer, your viewer will need a signed URL to access the files. A signed URL can be acquired in one of two ways: