Tech Blog

Using PDS and Alma for user authentication and authorisation for Relais inter-library loans system

At Swinburne University Library we have recently upgraded our Relais inter-library loans system to use PDS for authenticating users and Alma for user/group authorisation. In this blog post we’ll detail why and how to do this to aid other Relais/ExLibris sites.

Why

Historically with our Relais system user accounts had to be manually created for each student/staff that required ILL requests. Each of these accounts were not in-sync with our institutes login/identity management system. Creating extra work for our ILL staff and extra pain for the staff and students.
By using PDS for authentication with Relais our staff and student no longer need additional usernames and passwords, their current institutional login now works fine.
With Alma for authorication (user and group information) we can easily define in Alma which groups are allowed ILL access and mange access via this new login page.
By using Alma for authorisation we can in the future look to automate things like if a student has fines/blocks in Alma auto block ILL requests and forward them to a payments page etc.
With NCIP configured between Relais and Alma user accounts for eligible staff/students are automatically created in Relais reducing the work load on our ILL staff.

Background

  • This assumes NCIP has been setup between Relais and ExLibris Alma
  • That you have access to the Alma API
    • you need to setup an API key with access to production user details – read-only
This is a fork of the great work done by Steve Thomas of The University of Adelaide Library and Rachelle Anne Orodio of Monash University Library for use at Swinburne University Library by Justin Kelly

Changes from Steve’s code

  • Uses `curl` instead of `LWP::Simple get()`
    • Our server couldnt use `get()` for whatever reason so swapped it out for `curl`
  • Uses the Alma API to get user groups details
    • Our PDS didn’t provide user groups information, instead of reconfiguring PDS, the Alma API was used

Setup

Copy our perl files from our GitHub repository: https://github.com/justinkelly/Relais-PDS-login
Place the files `PDS.pm` and `illrequest.pl` onto a web-server that can run perl scripts.

illrequest.pl

Edit the file `illrequest.pl` and adjust the following settings
use lib "/var/www/cgi-bin/PDS";
Set this as the directory on the server where you will put these 2 perl files
Update `$libcode` with your Relais code
# Relais code
my $libcode = '<YOUR RELAIS CODE>';

 

Update `$institutecode` with your Alma institute code
# Alma institute code
my $institutecode = '<YOUR ALMA INSTITUTE CODE>';

 

Update `$relais` with your Relais patron login url
# Relais url
my $relais = '<YOUR RELAIS URL>';
## example format 
### Swinburne $relais = 'https://h7.relais-host.com/<YOUR RELAIS CODE>/loginpRFT.jsp?';
### Swinburne $relais = 'https://h7.relais-host.com/<YOUR RELAIS CODE>/loginp.jsp';
### Monash $relais = 'https://<YOUR RELAIS URL HERE>/user/login.html?group=patron';

Update `@almagroups` with the code numbers for the user groups that are allowed to place inter-library loan requests in Relais

## List which Alma user groups are allowed to borrow via ILL/Relais 
my @almagroups = ("03","11","12","13","34","81","82");

PDS.pm

 

Update the 3 configurations in `PDS.pm` with your PDS url, Alma API key and Primo institute code
##--------CONFIGURE-----------------------------------------------------
my $pds_url = "<YOUR PDS URL>";
my $alma_api_key = "<YOUR ALMA API KEY>";
my $institute = "<YOUR PRIMO INSTITUTE>";
##----------------------------------------------------------------------

Alma API key

To access the users group details from ExLibris Alma and Alma API key is required.
An API key can be created in the ExLibris Developers Network, refer below links, please make sure that the key is for your production server and is read-only
ExLibris Alma API – getting started documentation
User API details

Usage

Once the files are on a web-server (with perl) and configured just option on the ‘illrequest.pl’ page in your browser and you’ll be auto-forwarded to PDS

Once authenticated PDS will send you back to ‘illrequest.pl’ page

If you are authorised (in the current Alma user groups) you’ll be forwarded to Relais (logged in) request page.

If you are not in an eligible user group you’ll be presented with a notice page.

Issues/Questions

If you have any question or issues with using PDS and Alma with Relais please feel free to contact Justin Kelly

One Reply to “Using PDS and Alma for user authentication and authorisation for Relais inter-library loans system”

  1. You can configure a direct link from an open URL into relais by updating your service details for Relais in Alma under General Electronic Services. Using the Relais documentation you can configure book/article and general links, so that a request after logging in via PDS will take you direct to the article request form if it’s an article or the book request form if it’s a book. But you’ll need to add additional parameters to the cgi script to pass on the query string from the openURL link to Relais. We did something similar to Swinburne, but instead of doing a final check based on user group, we were forced to do ours on statistical categories. This allows eligible patrons once logged into Primo to be able to submit a direct request for an article/book in Relais without having to re-enter citation information.

Leave a Reply