About Features Downloads Getting Started Documentation Events Support GitHub

Site Tools


configuration:ils:alma

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 retreival 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]

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 to Alma.ini]
  • Message type: JSON
  • Subscriptions:
    • Check Users
    • Select User Groups for which an account in VuFind should be created (probably all of them)
configuration/ils/alma.txt · Last modified: 2018/07/10 06:56 by mbirkner