Table of Contents
Alma
The Alma driver was introduced in release 5.0.
This is the documentation for the Alma driver. It connects VuFind® to the ILS Alma from ExLibris.
Features
An unordered list of features implemented to the Alma driver:
- Create new user account
- Log in to user account and show details
- Place hold requests
- Show current hold / ILL / storage retrieval requests
- Cancel hold requests
- Show current loans
- Renew loans
- Show account blocks
- Show fines/fees
Alma.ini
The driver is configured in $VUFIND_HOME/config/vufind/Alma.ini
. Please be aware that you should copy this file to the local
folder of your VuFind® installation: $VUFIND_LOCAL_DIR/config/vufind/Alma.ini
and make changes only there. Below you will find information about the settings that can be customized in Alma.ini
.
[Catalog]
This section is responsible for the connection to the Alma APIs.
apiBaseUrl
Set the base URL to the API of your Alma system here. Possible URLs are listed on this site of the ExLibris Developer Network.
Example:
apiBaseUrl = "https://api-eu.hosted.exlibrisgroup.com/almaws/v1"
apiKey
Add your API key for the Alma API here. To get an API key, you have to log in to the ExLibris Developer Network and add an “Application” to it. You could name that “VuFind”. For the new application, add at least these APIs: Bibs, Configuration, Courses, Users
. Choose the plan “Prod read/write” for at least: Bibs, Users
. Other APIs can be set to “read only”. Please note that you should not share your API key with others. It should be kept secret.
Example:
apiKey = "your_secret_api_key_here"
[Holds]
In this section you can define how hold requests are placed to Alma via the Alma API.
HMACKeys
Here you can define what information should be passed to the hold request logic. At a minimum, the following values need to be set: id:item_id:holding_id
. These values are necessary for item level hold requests. If you would like to activate title level hold requests, you need to add description
and level
(see example below). Please be aware that, if you want to use title level hold requests, you have to set title_level_holds_mode
to “driver”
in config.ini.
Example (item level requests):
HMACKeys = id:item_id:holding_id
Example (title level requests):
HMACKeys = id:item_id:holding_id:description:level
defaultRequiredDate
Define the “not required after” date for hold requests. Format is “days:months:years”
Example:
defaultRequiredDate = 0:1:0
extraHoldFields
Additional fields that should be displayed in the “place hold request” form. Supported values are comments
, requiredByDate
, pickUpLocation
and requestGroup
.
Example:
extraHoldFields = comments:requiredByDate:pickUpLocation
defaultPickUpLocation
This setting is not working as of release 5.0. It will be implemented in a future release! This documentation is for future reference.
Provide a pick up location that should be pre-selected in the drop down list that shows all pick up locations in the “place hold request” form.
Example:
defaultPickUpLocation = "ALMA_LIBRARY_CODE"
[NewUser]
Here you can define some default values that will be sent to Alma when a new user account is created. These settings only have an effect when you use AlmaDatabase
in the Authentication
section of the config.ini file.
recordType
This is a mandatory setting that defines the record type of the new user account in Alma. For patrons, you normally want PUBLIC
. Possible values are listed at the ExLibris Developer Network.
Example:
recordType = PUBLIC
accountType
This is a mandatory setting that defines if the new user account is managed in Alma internally or in another system (e. g. LDAP). If you use AlmaDatabase
as your authentication system, this should always be set to INTERNAL
.
Example:
accountType = INTERNAL
status
This is a mandatory setting. You can choose if the newly created user account should be active or inactive. Normally you want a new user account to be ACTIVE
. Possible values are listed at the ExLibris Developer Network.
Example:
status = ACTIVE
userGroup
This is a mandatory setting that defines which user group the newly created account should be added to in Alma. Possible values are listed at the ExLibris Developer Network (log in with your institution account first) or directly in Alma (go to Alma Configuration → User Management → User Groups
). Use the code, not the description of the user group.
Example:
userGroup = ALUMNI
idType
This is a mandatory setting. When a patron creates an account with the “Create New Account” form in VuFind®, he or she is able to choose a username. This username will be a user ID in the user's account in Alma. But in Alma, a user account can have multiple IDs of different types. So here you need to define which type of ID the username should get in Alma. Possible values are listed at the ExLibris Developer Network (log in with your institution account first to see possible values for your institution). Use the code, not the description of the ID type.
Example:
idType = 03
preferredLanguage
This is a mandatory setting. Set the default language of the newly created user account in Alma here. Normally this is your local language. Possible values are listed at the ExLibris Developer Network (log in with your institutional account first to see possible values for your institution) or directly in Alma at Alma Configuration → General → Institution Languages
. Use the code, not the description of the language.
Example:
preferredLanguage = de
emailType
This is a mandatory setting. When a patron creates an account with VuFind®'s “Create New Account” form, he or she is able to add an email address. In Alma, a user account can have multiple email addresses of different types. So here you need to define which type of email address the newly created user account should get in Alma. Possible values are listed at the ExLibris Developer Network (log in with your institutional account first to see possible values for your institution). Use the code, not the description of the email type.
Example:
emailType = personal
expiryDate
This is an optional setting to define the period of time that the new account will exist before expiring. The duration will be added to the account creation date to set the expiry date of the user's Alma account. Use the DateInterval notation of PHP to express the period. If not set, 1 year (P1Y) will be used as default value.
Example (1 year, 6 month, 10 days):
expiryDate = P1Y6M10D
purgeDate
This is an optional setting to define the period of time that the new account will exist before being purged. The duration will be added to the account creation date to set the purge date of user's Alma account. Use the DateInterval notation of PHP to express the period. If not set, the purge date of the Alma user account will be left empty.
Example (3 years, 4 months):
purgeDate = P3Y4M
[FulfillmentUnits]
In Alma you can create so called “Fulfillment Units”. Alma assumes that similar locations do have similar fulfillment conditions (e. g. for how long a book can be loaned). For that reason, it is possible to cluster multiple locations to a “Fulfillment Unit”. In VuFind®, we particularly need to know if a user of a certain user group is allowed to place a hold request on a certain book or not.
Unfortunately, Alma does not (yet) offer an API that allows us to retrieve Fulfillment Units and the corresponding fulfillment conditions for the different user groups. That is why we have to build this setting in our Alma.ini.
In this [FulfillmentUnits]
section, we define which Fulfillment Units cover which locations. In the next section ([Requestable]
) we define which user group is allowed to place hold requests on which Fulfillment Unit.
If you have a lot of locations, you don't have to type the list manually. Instead, just export the data from your Alma system at Alma Configuration → Fulfillment → Fulfillment Units → [Choose Fulfillment Unit] → Fulfillment Unit Locations
to your favourite spreadsheet software and use the CONCATENATE()
formula (or similar) to generate the list.
Please be aware that you have to update this list every time you add, remove or change Fulfillment Units and/or locations in Alma!
ExLibris announced that it will be adding an API for getting fulfillment conditions dynamically. So it could be that in future releases, this setting won't be necessary anymore.
Use only the codes of the Fulfillment Units and locations for this setting, not their descriptions.
The format is FULFILLMENT_UNIT_CODE[] = LOCATION_CODE
.
Example:
STACKS[] = stack1 STACKS[] = stack2 STACKS[] = stack3 LIMITED[] = periodicalroom LIMITED[] = musicrefs SHORTLOAN[] = office1 SHORTLOAN[] = office2
[Requestable]
This section only applies prior to VuFind® 6.0; starting with VuFind® 6.0, the ILS driver automatically determines which requests are legal, rendering this configuration unnecessary.
Here you can specify which user group is allowed to place hold requests on which Fulfillment Unit. For more details on the concept of Fulfillment Units, see the description for the [FulfillmentUnits]
section above.
Use only codes of Fulfillment Units, locations and user groups, not their descriptions.
If you specify N
the given user group is not allowed to place hold requests on the Fulfillment Unit. With Y
the placement of hold requests is allowed.
The format for this setting is FULFILLMENT_UNIT_CODE[USER_GROUP_CODE] = N
Example:
STACKS[STAFF] = Y STACKS[STUDENT] = Y STACKS[GUEST] = Y LIMITED[STAFF] = Y LIMITED[STUDENT] = N LIMITED[GUEST] = N SHORTLOAN[STAFF] = Y SHORTLOAN[STUDENT] = Y SHORTLOAN[GUEST] = N
[Webhook]
Webhooks are used by Alma for communicating with VuFind®. They are sending messages from Alma to VuFind® where they can be processed. To use webhooks, they have to be activated in Alma. Also, you have to give them permissions in permissions.ini on the VuFind® side. For more details on webhooks, see also the documentation on creating new user accounts in Alma below.
secret
This must be exactly the same value as the one that you type into the “Secret” field at the webhook configuration page in Alma.
Example:
secret = YOUR_WEBHOOK_SECRET_FROM_ALMA
Authentication
This section provides some notes on authenticating VuFind® users against Alma.
If a user wants to log in to his account in VuFind®, you have multiple choices as to how that can be done. For example, there are identity providers (IdP) like SAML, Shibboleth, LDAP, etc. you can use (see [Authentication]
section in config.ini. Alma can also make use of these IdP. So if you have one of the supported IdP, everything should be fine for you.
But there is a problem if you do not have such an IdP. VuFind® would offer the possibility to use the ILS
authentication option. The ILS
options would authenticate a user directly against the ILS (Alma) so that he is able to log in to his account in the ILS (Alma) via VuFind®. But that option requires that the user's password is saved on the ILS side. ExLibris announced - due to a security certificate that they want to implement - that saving passwords in Alma will not be possible in the (near?) future. For that reason, a new authentication option was introduced: the AlmaDatabase
option.
That means: If you don't have an IdP that you can use, you can use the AlmaDatabase
to integrate user accounts between VuFind® and Alma. The user's password and some other data (username, email, …) is saved in the VuFind® database. When the user wants to log in to VuFind®, the AlmaDatabase
method will check that username and password in the VuFind® database, but it will check also if a user with the given username exists in Alma. Only then will the user be allowed to log in.
Creating user accounts
This is only relevant if you don't have an institutional identity provider (IdP) like SAML, Shibboleth, LDAP, … and use the AlmaDatabase
method for authentication (for details, see “Authentication” above).
In VuFind® (Alma API)
When a user wants to create an account for your library, he can use the “Create New Account” form in VuFind®. If you use the AlmaDatabase
method in config.ini, this form (or rather, the code behind the form) will add the information provided by the user to the VuFind® database and it will also create a user account in Alma via its API. The password of the user will only be saved in the VuFind® database (for details, see documentation about “Authentication” above).
In Alma (Webhooks)
It is possible to create a new user account directly in Alma. The typical situation for that is when a user comes to the library information desk and tells the staff that he or she wants to become a user of the library. Your staff will then receive the user's information and add a new account directly in Alma.
If you have an IdP, everything should be fine because both Alma and VuFind® are able to integrate with the most common ones. But if you need to use VuFind® as your user database, how would it know about the new account? If you read the documentation about “Authentication” above, you know that the user's password is not saved in Alma. But for sure it must be saved somewhere.
That's where the Alma webhook comes into effect. The webhook does this: As soon as you create, update or delete a user account in Alma, it sends a user object with all relevant information to a specified URL. This URL will be a VuFind® URL. The code that is executed when the URL is called will receive the new or updated user information and update the VuFind® database accordingly.
Provide access for webhook to VuFind®
On the VuFind® side, the webhook receiving code is activated by default. For security reasons, the access is restricted. You can provide the access to it via the permissions.ini file. There, you have to allow the IP address of your Alma system to communicate with VuFind®. To find out this IP address, go to this site on the ExLibris knowledge center or enter the URL to your Alma system to a service like this one. Here is an example of an entry in the permissions.ini
file to allow webhook access. Replace the ipRange[]
setting with the IP address of your Alma system:
[alma.Webhooks] permission[] = "access.alma.webhook.user" permission[] = "access.alma.webhook.challenge" require = ALL ipRange[] = "1.2.3.4"
Activate webhook in Alma
Please be aware that you have to activate Webhooks in Alma itself. Set the configuration in Alma like this:
- Webhook listener URL:
YOUR_VUFIND_URL/Alma/Webhook
- Secret:
ENTER_RANDOM_ALPHANUMERIC_STRING_HERE
[same value must be added toAlma.ini
] - Message type:
JSON
- Subscriptions:
- Check
Users
- Select
User Groups
for which an account in VuFind® should be created (probably all of them)