Warning: This page has not been updated in over over a year and may be outdated or deprecated.
configuration:ils:alma
Differences
This shows you the differences between two versions of the page.
Next revision | Previous revisionNext revisionBoth sides next revision | ||
configuration:ils:alma [2018/05/08 15:26] – created demiankatz | configuration:ils:alma [2019/04/01 17:18] – [[Requestable]] demiankatz | ||
---|---|---|---|
Line 3: | Line 3: | ||
:!: The Alma driver was introduced in release 5.0. | :!: The Alma driver was introduced in release 5.0. | ||
- | // Details coming | + | This is the documentation for the Alma driver. It connects VuFind to the ILS [[https://www.exlibrisgroup.com/ |
+ | |||
+ | ===== 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/ | ||
+ | |||
+ | |||
+ | |||
+ | ===== Alma.ini ===== | ||
+ | |||
+ | The driver is configured in '' | ||
+ | |||
+ | ==== [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 [[https:// | ||
+ | |||
+ | Example: | ||
+ | < | ||
+ | |||
+ | === apiKey === | ||
+ | Add your API key for the Alma API here. To get an API key, you have to log in to the [[https:// | ||
+ | |||
+ | Example: | ||
+ | < | ||
+ | |||
+ | ==== [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: '' | ||
+ | |||
+ | Example (item level requests): < | ||
+ | |||
+ | Example (title level requests): < | ||
+ | |||
+ | === defaultRequiredDate === | ||
+ | Define the "not required after" date for hold requests. Format is " | ||
+ | |||
+ | Example: < | ||
+ | |||
+ | === extraHoldFields === | ||
+ | Additional fields that should be displayed in the "place hold request" | ||
+ | |||
+ | Example: < | ||
+ | |||
+ | === 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" | ||
+ | |||
+ | Example: < | ||
+ | |||
+ | ==== [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 '' | ||
+ | |||
+ | === recordType === | ||
+ | This is a __mandatory__ setting that defines the record type of the new user account in Alma. For patrons, you normally want '' | ||
+ | |||
+ | Example: < | ||
+ | |||
+ | === 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 '' | ||
+ | |||
+ | Example: < | ||
+ | |||
+ | === 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 '' | ||
+ | |||
+ | Example: < | ||
+ | |||
+ | === 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 [[https:// | ||
+ | |||
+ | Example: < | ||
+ | |||
+ | === idType === | ||
+ | This is a __mandatory__ setting. When a patron creates an account with the " | ||
+ | |||
+ | Example: < | ||
+ | |||
+ | === 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 [[https:// | ||
+ | |||
+ | Example: < | ||
+ | |||
+ | === emailType === | ||
+ | This is a __mandatory__ setting. When a patron creates an account with VuFind' | ||
+ | |||
+ | Example: < | ||
+ | |||
+ | === 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 [[https:// | ||
+ | |||
+ | Example (1 year, 6 month, 10 days): < | ||
+ | |||
+ | === 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 [[https:// | ||
+ | |||
+ | Example (3 years, 4 months): < | ||
+ | |||
+ | ==== [FulfillmentUnits] ==== | ||
+ | In Alma you can create so called " | ||
+ | |||
+ | Unfortunately, | ||
+ | |||
+ | In this '' | ||
+ | |||
+ | 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 '' | ||
+ | |||
+ | :!: 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 '' | ||
+ | |||
+ | 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 '' | ||
+ | |||
+ | Use only codes of Fulfillment Units, locations and user groups, not their descriptions. | ||
+ | |||
+ | If you specify '' | ||
+ | |||
+ | The format for this setting is '' | ||
+ | |||
+ | 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 [[configuration: | ||
+ | |||
+ | === secret === | ||
+ | This must be exactly the same value as the one that you type into the " | ||
+ | |||
+ | Example:< | ||
+ | ===== 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 '' | ||
+ | |||
+ | But there is a problem if you do not have such an IdP. VuFind would offer the possibility to use the '' | ||
+ | |||
+ | That means: If you don't have an IdP that you can use, you can use the '' | ||
+ | |||
+ | ===== Creating user accounts ===== | ||
+ | :!: This is only relevant if you don't have an institutional identity provider (IdP) like SAML, Shibboleth, LDAP, ... and use the '' | ||
+ | |||
+ | ==== In VuFind (Alma API) ==== | ||
+ | When a user wants to create an account for your library, he can use the " | ||
+ | |||
+ | ==== 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 " | ||
+ | |||
+ | 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 [[https://github.com/ | ||
+ | |||
+ | < | ||
+ | [alma.Webhooks] | ||
+ | permission[] = " | ||
+ | permission[] = " | ||
+ | require = ALL | ||
+ | ipRange[] = " | ||
+ | </ | ||
+ | |||
+ | === Activate webhook in Alma === | ||
+ | Please be aware that you have to [[https:// | ||
+ | |||
+ | * Webhook listener URL: '' | ||
+ | * Secret: '' | ||
+ | * Message type: '' | ||
+ | * Subscriptions: | ||
+ | * Check '' | ||
+ | * Select '' | ||
+ | |||
+ | |||
---- struct data ---- | ---- struct data ---- | ||
---- | ---- | ||
configuration/ils/alma.txt · Last modified: 2024/02/14 19:08 by demiankatz