Access

NAVIGATE CONTENT
Ex Libris Developer Network Alma Documentation Integrations Digital Digital Access

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 Viewer

representation
/view/delivery/[MMS_ID | REPRESENTATION_ID] *

OR

/discovery/delivery/[VID]/[MMS_ID | REPRESENTATION_ID] *
General/mixed material
file/discovery/delivery/[VID]/[REPRESENTATION_ID]#[FILE_ID]Opening specific file within representation
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].json *

OR

/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
Thumbnailallsee Thumbnail Delivery Service
* 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

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
  • VID: The Primo View ID. For non-VE institutions, this is [institutioncode]:AlmaGeneralView, e.g. 01UNI_INST:AlmaGeneralView.
  • 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.

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.

 

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 Classic 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 Classic Primo or other discovery applications. For Classic 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 and Authentication

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)”.

When attempting to access a representation that is restricted by a user-determined access rights policy as a guest will prompt the user to log in. Alma delivery supports the authentication methods supported by Alma.

  • Primo institutions with an external authentication system that supports standard protocols should configure their system in Alma.
  • Single sign-on (SSO) is supported from Primo to Alma viewers, but not the other direction (except SAML).

 

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), whereas MODS records will hold the storage path in mods:location/mods:url.

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: