refs #20679 [finc] reduce DAIA/PAIA requests

* update FincILS.ini with latest contents of DAIA.ini and PAIA.ini
* Fix PAIA notification caching
* Cache PAIA fees response
* Cache PAIA user details

co-authored by André Lahmann <lahmann@ub.uni-leipzig.de>

local/config/vufind/FincILS.ini

 ; General configuration
 [General]
+; Set the time to live (ttl) for cached data (default is 30 seconds).
+;cacheLifetime = 90
+
 ; This setting defines the connection timeout for testing the availability of the ILS
 ; in seconds (default is 1 second).
 ilsTestTimeout = 30
@@ -13,6 +16,12 @@ queryIls[] = 'getFacetAvail:Local'
 ;[DAIA]
 ; The base URL for the DAIA webservice.
 ;baseUrl        = "http://localhost/daiawachtl/daia/"
+
+; Set a DAIA specific timeout in seconds to be used for DAIA http requests (defaults
+; to Zend defaults or as defined in
+; vendor/vufind-org/vufindhttp/src/VuFindHttp/HttpService.php)
+;timeout = 30
+
 ; The prefix prepended to the VuFind record Id resulting in the document URI
 ; used for the DAIA request (default = ppn:) (the prefix usually defines the
 ; field which the DAIA server uses for the loookup - e.g. ppn: or isbn:).
@@ -22,7 +31,7 @@ queryIls[] = 'getFacetAvail:Local'
 ;daiaResponseFormat = json
 
 ; Set multiQuery to true if your DAIA webservice supports queries with multiple
-; ids (cf. http://gbv.github.io/daiaspec/daia.html#query-api).
+; ids (cf. https://gbv.github.io/daia/daia.html#query-parameters).
 ; Default is false.
 ;multiQuery = false
 
@@ -31,7 +40,7 @@ queryIls[] = 'getFacetAvail:Local'
 ; daiaContentTypes is not set, Content-Type HTTP header is NOT checked.
 ;
 ; expected Content-Types for DAIA XML format:
-; (seperate multiple values by commata, for example:
+; (separate multiple values by commas, for example:
 ; daiaContentTypes['xml'] = "application/xml, text/xml"
 ;daiaContentTypes['xml'] = "application/xml"
 
@@ -43,8 +52,17 @@ queryIls[] = 'getFacetAvail:Local'
 ; Enable caching for DAIA items (default is false).
 ;daiaCache = false
 
-; Set the time to live (ttl) for cached DAIA data (default is 30 seconds).
-;daiaCacheLifetime = 90
+; DAIA does not support placing holds (this functionality is covered by PAIA) but is
+; able to provide a link to the OPAC to perform such an action. Regarding placing
+; holds/recalls such link is usually given as href for an unavailable service.
+; Uncomment the below section Holds with the setting 'function' to show a link to
+; the OPAC (if it was provided in the DAIA response) instead of a VuFind
+; Holds-Button.
+; If PAIA is used in combination with the DAIA driver, handling holds etc. should be
+; left to the logic in the PAIA driver - thus keep this section commented out if you
+; are using PAIA as well.
+; [Holds]
+; function = getHoldLink
 
 ;FincILS configuration
 ; refer to ticket #4499 for further info on configuring it
@@ -60,7 +78,8 @@ queryIls[] = 'getFacetAvail:Local'
 ; vendor/vufind-org/vufindhttp/src/VuFindHttp/HttpService.php)
 ;timeout = 30
 
-; Enable caching for PAIA items (default is false).
+; Enable caching for PAIA items (default is false). TTL for cached data will be the
+; same as for DAIA cache (see cacheLifetime setting in DAIA.ini).
 ;paiaCache = false
 
 ; A PAIA auth server acts as OAuth authorization server (RFC 6749) with
@@ -84,6 +103,66 @@ queryIls[] = 'getFacetAvail:Local'
 ;root_username            = 'root'
 ;root_password            = ''
 
+; Driver configuration, usually you can leave it untouched
+
+; Without customization the PAIA driver will offer to place a recall for items with
+; unavailable service loan but set href for loan. The recall will be performed via
+; PAIA request.
+; The pre-defined HMACKeys (id:item_id:doc_id) should suffice to place a recall. No
+; extra fields are allowed (if you need those you might be able to cover this
+; functionality in a custom driver by using PAIA confirm/conditions).
+[Holds]
+; HMACKeys - A list of form element names that will be analyzed for consistency
+; during form processing. Most users should not need to change this setting.
+HMACKeys = "id:item_id:doc_id"
+
+; PAIA status which should be mapped to Holds
+; status are:   1 = reserved (not available yet but later)
+;               2 = ordered (and not yet ready to be picked up)
+;               3 = held by patron
+;               4 = provided (and ready to be picked up)
+status = "1:4"
+
+; Without customization the PAIA driver will offer to place a storageretrievalrequest
+; for items with available service loan and set href for loan. The
+; storageretrievalrequest will be performed via PAIA request (technically the same as
+; for recall, but with different frontend templates etc.).
+; The pre-defined HMACKeys (id:item_id:doc_id) should suffice to request an item. No
+; extra fields are allowed (if you need those you might be able to cover this
+; functionality in a custom driver by using PAIA confirm/conditions).
+[StorageRetrievalRequests]
+; HMACKeys - A list of form element names that will be analyzed for consistency
+; during form processing. Most users should not need to change this setting.
+HMACKeys = id:item_id:doc_id
+
+; PAIA status which should be mapped to StorageRetrievalRequests
+; status are:   1 = reserved (not available yet but later)
+;               2 = ordered (and not yet ready to be picked up)
+;               3 = held by patron
+;               4 = provided (and ready to be picked up)
+status = "2"
+
+; All kinds of transactions by a specific patron. Transactions are eg checked out
+; items
+[Transactions]
+; PAIA status which should be mapped to Transactions
+; status are:   1 = reserved (not available yet but later)
+;               2 = ordered (and not yet ready to be picked up)
+;               3 = held by patron
+;               4 = provided (and ready to be picked up)
+status = "3"
+
+; The PAIA driver supports renewals in MyResearch views. The renewal will be
+; performed via PAIA renew.
+; The pre-defined HMACKeys (id:item_id:doc_id) should suffice to renew an item. No
+; extra fields are allowed (if you need those you might be able to cover this
+; functionality in a custom driver by using PAIA confirm/conditions).
+[Renewals]
+; HMACKeys - A list of form element names that will be analyzed for consistency
+; during form processing. Most users should not need to change this setting.
+HMACKeys = "id:item_id:doc_id"
+
+; FincILS specific
 ; Enable EmailHold to allow placing orders via Email instead of direct ILS
 ; interaction.
 ;[EmailHold]

module/finc/src/finc/ILS/Driver/PAIA.php

@@ -304,13 +304,23 @@ class PAIA extends \VuFind\ILS\Driver\PAIA
             throw new ILSException('You are not entitled to read fees.');
         }
 
-        try {
-            $fees = $this->paiaGetAsArray(
-                'core/' . $patron['cat_username'] . '/fees'
-            );
-        } catch (\Exception $e) {
-            // all error handling is done in paiaHandleErrors so pass on the excpetion
-            throw $e;
+        if ($this->paiaCacheEnabled) {
+            $fees = $this->getCachedData($this->_feesCacheKey($patron));
+        }
+
+        if (!isset($fees) || $fees == null) {
+            try {
+                $fees = $this->paiaGetAsArray(
+                    'core/' . $patron['cat_username'] . '/fees'
+                );
+            } catch (\Exception $e) {
+                // all error handling is done in paiaHandleErrors so pass on the excpetion
+                throw $e;
+            }
+
+            if ($this->paiaCacheEnabled) {
+                $this->putCachedData($this->_feesCacheKey($patron), $fees);
+            }
         }
 
         // PAIA simple data type money: a monetary value with currency (format
@@ -755,18 +765,34 @@ class PAIA extends \VuFind\ILS\Driver\PAIA
     }
 
     /**
-     * Helper function to generate cache key
-     * @param array $patron
+     * Helper function to generate cache key for fees.
+     *
+     * @param array $patron Array with patron information
+     *
      * @return string
      */
-    private function notificationsCacheKey($patron)
+    private function _feesCacheKey($patron)
+    {
+        return $patron['cat_username'] . '_fees';
+    }
+
+    /**
+     * Helper function to generate cache key for notifications.
+     *
+     * @param array $patron Array with patron information
+     * 
+     * @return string
+     */
+    private function _notificationsCacheKey($patron)
     {
         return $patron['cat_username'] . '_notifications';
     }
 
     /**
      * Helper function to retrieve notification ID
+     *
      * @param string $messageId
+     *
      * @return string
      */
     protected function getPaiaNotificationsId($messageId)
@@ -797,8 +823,8 @@ class PAIA extends \VuFind\ILS\Driver\PAIA
         }
 
         if ($this->paiaCacheEnabled) {
-            $response = $this->getCachedData($this->notificationsCacheKey($patron));
-            if (!empty($response)) {
+            $response = $this->getCachedData($this->_notificationsCacheKey($patron));
+            if ($response !== null) {
                 return $response;
             }
         }
@@ -833,7 +859,7 @@ class PAIA extends \VuFind\ILS\Driver\PAIA
         }
 
         if ($this->paiaCacheEnabled) {
-            $this->putCachedData($this->notificationsCacheKey($patron), $response);
+            $this->putCachedData($this->_notificationsCacheKey($patron), $response);
         }
 
         return $response;
@@ -866,7 +892,7 @@ class PAIA extends \VuFind\ILS\Driver\PAIA
         }
 
         if (!$keepCache && $this->paiaCacheEnabled) {
-            $this->removeCachedData($this->notificationsCacheKey($patron));
+            $this->removeCachedData($this->_notificationsCacheKey($patron));
         }
 
         return $response;
@@ -887,7 +913,7 @@ class PAIA extends \VuFind\ILS\Driver\PAIA
         }
 
         if ($this->paiaCacheEnabled) {
-            $this->removeCachedData($this->notificationsCacheKey($patron));
+            $this->removeCachedData($this->_notificationsCacheKey($patron));
         }
 
         return true;
@@ -1384,19 +1410,26 @@ class PAIA extends \VuFind\ILS\Driver\PAIA
             throw new ILSException('You are not entitled to read patron.');
         }
 
-        $responseJson = $this->paiaGetRequest(
-            'core/' . $patron,
-            $this->getSession()->access_token
-        );
+        $cacheKey = function ($patron) {
+            return $patron . '_user_details';
+        };
 
-        try {
-            $responseArray = $this->paiaParseJsonAsArray($responseJson);
-        } catch (ILSException $e) {
-            // all error handling is done in paiaHandleErrors so pass on the
-            // excpetion
-            throw $e;
+        $response = null;
+
+        if ($this->paiaCacheEnabled) {
+            $response = $this->getCachedData($cacheKey($patron));
         }
-        return $this->paiaParseUserDetails($patron, $responseArray);
+
+        if ($response === null) {
+            // all error handling is done in paiaHandleErrors so pass on the excpetion
+            $response = $this->paiaGetAsArray('core/' . $patron);
+            
+            if ($this->paiaCacheEnabled) {
+                $this->putCachedData($cacheKey($patron), $response);
+            }
+        }
+
+        return $this->paiaParseUserDetails($patron, $response);
     }
 
     /**