About Features Downloads Getting Started Documentation Events Support GitHub

Love VuFind®? Consider becoming a financial supporter. Your support helps build a better VuFind®!

Site Tools


Warning: This page has not been updated in over over a year and may be outdated or deprecated.
configuration:ils:alma

This is an old revision of the document!


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.

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.

Alma.ini

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

<WRAP center round alert 60%> This setting is not working at the moment. Will be implemented in future release! This documentation is for future reference. </WRAP>

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 settingy only have an effect when you use AlmaDatabase in the Authentication section of the config.ini file.

recordType

This is a mandatory setting. 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. 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. Define here to which user group the newly created account should be added 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 is able to choose a username. This username will be a user ID in the users 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 the „Create New Account“ form of VuFind, he 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. Define the period of time that should be added to the point in time a user created his account. The result will be the expiry date of his account in Alma. 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. Define the period of time that should be added to the point in time a user created his account. The result will be the purge date of his account in Alma. 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 now 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 retreive 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 Unit does 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.

<WRAP center round important 60%> Please be aware that you have to adapt this list every time you add, remove or change Fulfillment Units and/or locations in Alma! </WRAP>

<WRAP center round info 60%> ExLibris announced to add an API for getting fulfillment conditions dynamically. So it could be that in future releases, this setting won't be necessary anymore. </WRAP>

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



Authentication

Some notes on authenticating VuFind users against Alma.

If a user wants to log in to his account in VuFind, you have multiple choices how he can do that. 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 users 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 users password and some other data (username, eMail, …) is saved in the VuFind database. When the user wants to log in in VuFind, the AlmaDatabase method will check that username and password in the Alma database, but it will check also if a user with the given username exists in Alma. Only then the user is allowed to log in.

Creating user accounts

<WRAP center round info 60%> 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) </WRAP>

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 privided 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 wants to become a user of the library. Your staff will then receive the users 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 users password is not saved in Alma. But for sure it must be saved somewhere.

Thats 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
  • 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.1530883488.txt.gz · Last modified: 2018/07/06 13:24 by demiankatz