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.
Alma provides the following delivery services:
|Service Name||Level||URL (prefixed by https://ALMA_DOMAIN)||Use for|
|Alma Viewer||representation||General/mixed material|
|representation||Images in book format|
|representation||External IIIF viewers|
|file||External IIIF viewers|
|File (binary)||file||File download|
|Thumbnail||all||see Thumbnail Delivery Service|
- first (lowest ID) derivative
- first master
- first remote
- 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:
File IDs can be obtained by:
- The representation’s files tab in the Alma resource editor
- Retrieve Representation Files API
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 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:
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).
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).
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:
- By calculating the directory path algorithmically
- By using the Export Digital Titles Job
- From the Resource Editor
- Retrieve Representation Files Details API
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.
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: