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

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
configuration:ils:alma [2018/07/06 13:39] demiankatzconfiguration:ils:alma [2024/02/14 19:08] (current) demiankatz
Line 3: Line 3:
 :!: The Alma driver was introduced in release 5.0. :!: The Alma driver was introduced in release 5.0.
  
-This is the documentation for the Alma driver. It connects VuFind to the ILS [[https://www.exlibrisgroup.com/products/alma-library-services-platform/|Alma]] from ExLibris.+This is the documentation for the Alma driver. It connects VuFind® to the ILS [[https://www.exlibrisgroup.com/products/alma-library-services-platform/|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 
  
-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 ===== ===== Alma.ini =====
  
-Below you will find information about the settings that can be customized in ''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] ==== ==== [Catalog] ====
Line 77: Line 91:
  
 === idType === === 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 [[https://developers.exlibrisgroup.com/alma/apis/xsd/rest_user.xsd?tags=POST#user_identifier|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.+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 [[https://developers.exlibrisgroup.com/alma/apis/xsd/rest_user.xsd?tags=POST#user_identifier|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: <code>idType = 03</code> Example: <code>idType = 03</code>
Line 87: Line 101:
  
 === emailType === === 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 [[https://developers.exlibrisgroup.com/alma/apis/xsd/rest_user.xsd?tags=POST#email_types|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.+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 [[https://developers.exlibrisgroup.com/alma/apis/xsd/rest_user.xsd?tags=POST#email_types|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: <code>emailType = personal</code> Example: <code>emailType = personal</code>
Line 102: Line 116:
  
 ==== [FulfillmentUnits] ==== ==== [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.+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. 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.
Line 130: Line 144:
  
 ==== [Requestable] ==== ==== [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. 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.
  
Line 151: Line 168:
 </code> </code>
  
 +==== [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:ils:alma#in_alma_webhooks|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:<code>secret = YOUR_WEBHOOK_SECRET_FROM_ALMA</code>
 ===== Authentication ===== ===== Authentication =====
-Some notes on authenticating VuFind users against Alma.+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 how he can do that. For example there are identity providers (IdP) like SAML, Shibboleth, LDAP, etc. you can use (see ''[Authentication]'' section in [[https://github.com/vufind-org/vufind/blob/master/config/vufind/config.ini|config.ini]]. [[https://developers.exlibrisgroup.com/alma/integrations/user-management/authentication/inst_idp|Alma can also make use of these IdP]]. So if you have one of the supported IdP, everything should be fine for you.+If a user wants to log in to his account in VuFind®, you have multiple choices as to how that can be done. For examplethere are identity providers (IdP) like SAML, Shibboleth, LDAP, etc. you can use (see ''[Authentication]'' section in [[https://github.com/vufind-org/vufind/blob/dev/config/vufind/config.ini|config.ini]]. [[https://developers.exlibrisgroup.com/alma/integrations/user-management/authentication/inst_idp|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.+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'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.
  
-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 ===== ===== 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 detailssee "Authentication" above). 
-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) ==== 
-==== 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 ratherthe 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 detailssee documentation about "Authentication" above).
-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) ==== ==== 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.+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'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.+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'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.+That'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 ===+=== 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/vufind-org/vufind/blob/master/config/vufind/permissions.ini|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 [[https://knowledge.exlibrisgroup.com/Alma/Implementation_and_Migration/Implementation_Guides/03Technical_Requirements_for_Alma_and_Discovery_Implementation#Alma_Platform_IP_Range|this site on the ExLibris knowledge center]] or enter the URL to your Alma system to a service like [[https://www.site24x7.com/find-ip-address-of-web-site.html|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:<code>+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/vufind-org/vufind/blob/dev/config/vufind/permissions.ini|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 [[https://knowledge.exlibrisgroup.com/Alma/Implementation_and_Migration/Implementation_Guides/03Technical_Requirements_for_Alma_and_Discovery_Implementation#Alma_Platform_IP_Range|this site on the ExLibris knowledge center]] or enter the URL to your Alma system to a service like [[https://www.site24x7.com/find-ip-address-of-web-site.html|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: 
 + 
 +<code>
 [alma.Webhooks] [alma.Webhooks]
 permission[] = "access.alma.webhook.user" permission[] = "access.alma.webhook.user"
Line 189: Line 214:
  
   * Webhook listener URL: ''YOUR_VUFIND_URL/Alma/Webhook''   * Webhook listener URL: ''YOUR_VUFIND_URL/Alma/Webhook''
-  * Secret: ''ENTER_RANDOM_ALPHANUMERIC_STRING_HERE''+  * Secret: ''ENTER_RANDOM_ALPHANUMERIC_STRING_HERE'' [same value must be added to ''Alma.ini'']
   * Message type: ''JSON''   * Message type: ''JSON''
   * Subscriptions:   * Subscriptions:
     * Check ''Users''     * Check ''Users''
-    * Select ''User Groups'' for which an account in VuFind should be created (probably all of them) +    * Select ''User Groups'' for which an account in VuFind® should be created (probably all of them)
-\\ +
 ---- struct data ---- ---- struct data ----
 +properties.Page Owner : 
 ---- ----
  
configuration/ils/alma.1530884354.txt.gz · Last modified: 2018/07/06 13:39 by demiankatz