About Features Downloads Getting Started Documentation Events Support GitHub

Site Tools


configuration:ils:alma

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
configuration:ils:alma [2018/07/06 12:29]
mbirkner
configuration:ils:alma [2020/09/22 14:18] (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 **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 retreival requests 
 +  * Cancel hold requests 
 +  * Show current loans 
 +  * Renew loans 
 +  * Show account blocks 
 +  * Show fines/fees 
  
-The driver is configured in ''VUFIND_DIR/config/vufind/Alma.ini''. Please be aware that you should copy this file to the ''local'' folder of your VuFind installation: ''VUFIND_DIR/local/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] ====
 This section is responsible for the connection to the Alma APIs. This section is responsible for the connection to the Alma APIs.
 +
 === apiBaseUrl === === apiBaseUrl ===
 Set the base URL to the API of your Alma system here. Possible URLs are [[https://developers.exlibrisgroup.com/alma/apis#calling|listed on this site of the ExLibris Developer Network]].  Set the base URL to the API of your Alma system here. Possible URLs are [[https://developers.exlibrisgroup.com/alma/apis#calling|listed on this site of the ExLibris Developer Network]]. 
Line 25: Line 39:
 Example: Example:
 <code>apiKey = "your_secret_api_key_here"</code> <code>apiKey = "your_secret_api_key_here"</code>
-\\ \\ +
 ==== [Holds] ==== ==== [Holds] ====
 In this section you can define how hold requests are placed to Alma via the Alma API. In this section you can define how hold requests are placed to Alma via the Alma API.
 +
 === HMACKeys === === HMACKeys ===
-Here you can define what information should be passed to the hold request logic. As a minimum, following values need to be set: ''id:item_id:holding_id''. These values are necessary for item level hold requests. If you 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.+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 [[configuration:files:config.ini|config.ini]].
  
-Example (item level requests):<code>HMACKeys = id:item_id:holding_id</code>+Example (item level requests): <code>HMACKeys = id:item_id:holding_id</code> 
 + 
 +Example (title level requests): <code>HMACKeys = id:item_id:holding_id:description:level</code>
  
-Example (title level requests):<code>HMACKeys = id:item_id:holding_id:description:level</code> 
 === defaultRequiredDate === === defaultRequiredDate ===
 Define the "not required after" date for hold requests. Format is "days:months:years" Define the "not required after" date for hold requests. Format is "days:months:years"
  
-Example:<code>defaultRequiredDate = 0:1:0</code>+Example: <code>defaultRequiredDate = 0:1:0</code> 
 === extraHoldFields === === extraHoldFields ===
-Fields that should be displayed additionally in the "place hold request" form. Supported values are ''comments'', ''requiredByDate'', ''pickUpLocation'' and ''requestGroup''.+Additional fields that should be displayed in the "place hold request" form. Supported values are ''comments'', ''requiredByDate'', ''pickUpLocation'' and ''requestGroup''.
  
-Example:<code>extraHoldFields = comments:requiredByDate:pickUpLocation</code> +Example: <code>extraHoldFields = comments:requiredByDate:pickUpLocation</code>
-=== defaultPickUpLocation ===+
  
-<WRAP center round alert 60%> +=== defaultPickUpLocation === 
-This setting is not working at the momentWill be implemented in future release! This documentation is for future reference. +:!: // This setting is not working as of release 5.0It 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. 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:<code>defaultPickUpLocation = "ALMA_LIBRARY_CODE"</code> + 
-\\ \\ +Example: <code>defaultPickUpLocation = "ALMA_LIBRARY_CODE"</code> 
 ==== [NewUser] ==== ==== [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.+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 [[configuration:files:config.ini|config.ini]] file. 
 === recordType === === 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 [[https://developers.exlibrisgroup.com/alma/apis/xsd/rest_user.xsd?tags=POST|ExLibris Developer Network]].+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 [[https://developers.exlibrisgroup.com/alma/apis/xsd/rest_user.xsd?tags=POST|ExLibris Developer Network]]. 
 + 
 +Example: <code>recordType = PUBLIC</code>
  
-Example:<code>recordType = PUBLIC</code> 
 === accountType === === 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''.+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: <code>accountType = INTERNAL</code>
  
-Example:<code>accountType = INTERNAL</code> 
 === status === === 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 [[https://developers.exlibrisgroup.com/alma/apis/xsd/rest_user.xsd?tags=POST|ExLibris Developer Network]]. 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 [[https://developers.exlibrisgroup.com/alma/apis/xsd/rest_user.xsd?tags=POST|ExLibris Developer Network]].
  
-Example:<code>status = ACTIVE</code>+Example: <code>status = ACTIVE</code> 
 === userGroup === === 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 [[https://developers.exlibrisgroup.com/alma/apis/xsd/rest_user.xsd?tags=POST|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.+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://developers.exlibrisgroup.com/alma/apis/xsd/rest_user.xsd?tags=POST|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: <code>userGroup = ALUMNI</code>
  
-Example:<code>userGroup = ALUMNI</code> 
 === idType === === 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 [[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'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> 
 === preferredLanguage === === 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://developers.exlibrisgroup.com/alma/apis/xsd/rest_user.xsd?tags=POST|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. 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://developers.exlibrisgroup.com/alma/apis/xsd/rest_user.xsd?tags=POST|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:<code>preferredLanguage = de</code>+Example: <code>preferredLanguage = de</code> 
 === emailType === === 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 [[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 Accountform, 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> 
 === expiryDate === === 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 [[https://secure.php.net/manual/en/dateinterval.construct.php#refsect1-dateinterval.construct-parameters|DateInterval notation of PHP]] to express the period. If not set, 1 year (P1Y) will be used as default value. +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'Alma account. Use the [[https://secure.php.net/manual/en/dateinterval.construct.php#refsect1-dateinterval.construct-parameters|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):<code>expiryDate = P1Y6M10D</code>+ 
 +Example (1 year, 6 month, 10 days): <code>expiryDate = P1Y6M10D</code> 
 === purgeDate === === 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 [[https://secure.php.net/manual/en/dateinterval.construct.php#refsect1-dateinterval.construct-parameters|DateInterval notation of PHP]] to express the period. If not set, the purge date of the Alma user account will be left empty.+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'Alma account. Use the [[https://secure.php.net/manual/en/dateinterval.construct.php#refsect1-dateinterval.construct-parameters|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): <code>purgeDate = P3Y4M</code>
  
-Example (3 years, 4 months):<code>purgeDate = P3Y4M</code> 
-\\ \\  
 ==== [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 now 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 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.+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 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.+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. 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 update this list every time you add, remove or change Fulfillment Units and/or locations in Alma!
-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 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. 
-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.
  
-Use only the codes of the Fulfillment Units and locations for this setting, not their descriptions.\\ 
 The format is ''FULFILLMENT_UNIT_CODE[] = LOCATION_CODE''. The format is ''FULFILLMENT_UNIT_CODE[] = LOCATION_CODE''.
  
-Example:<code>+Example: 
 +<code>
 STACKS[] = stack1 STACKS[] = stack1
 STACKS[] = stack2 STACKS[] = stack2
Line 119: Line 143:
 </code> </code>
  
-\\ \\  
 ==== [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.
  
-Use only codes of Fulfillment Units, locations and user groups, not their descriptions.\\+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. 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'' The format for this setting is ''FULFILLMENT_UNIT_CODE[USER_GROUP_CODE] = N''
  
-Example:<code>+Example: 
 +<code>
 STACKS[STAFF] = Y STACKS[STAFF] = Y
 STACKS[STUDENT] = Y STACKS[STUDENT] = Y
Line 138: Line 167:
 SHORTLOAN[GUEST] = N SHORTLOAN[GUEST] = N
 </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 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).+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).
  
 ==== 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 177: 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)
-\\ + 
 + 
configuration/ils/alma.1530880197.txt.gz · Last modified: 2018/07/06 12:29 by mbirkner