FOLIO: smarter handling of request types.

config/vufind/Folio.ini

@@ -116,10 +116,19 @@ defaultRequiredDate = 0:1:0
 ; "pickUpLocation", "proxiedUsers" and "requestGroup"
 extraHoldFields = requiredByDate:pickUpLocation
 
-; By default, a "Hold" type request is placed when an item is unavailable. Set to
-; "Recall" if a recall is preferred, or "Page" if a page is preferred.
+; By default, a "Hold" type request is placed when an item is unavailable and a Page
+; when an item is available. This setting overrides the default behavior for
+; unavailable items and for all title-level requests. Legal values: "Page", "Hold" or
+; "Recall"
 ;default_request = Hold
 
+; It is possible that the default_request method will not work in every situation; if
+; you uncomment one or more of the values below, alternate request types will be
+; attempted in the order listed if the initial request fails.
+;fallback_request_type[] = Page
+;fallback_request_type[] = Hold
+;fallback_request_type[] = Recall
+
 ; Hide the place hold/recall/page link when an item is in the configured
 ; list of locations. This can either match the full location name exactly or
 ; do a regex match depending on how you set the excludeHoldLocationsCompareMode

module/VuFind/src/VuFind/ILS/Driver/Folio.php

@@ -1539,6 +1539,57 @@ protected function getModuleMajorVersion(string $moduleName): int
         return $version;
     }
 
+    /**
+     * Support method for placeHold(): get a list of request types to try.
+     *
+     * @param string $preferred Method to try first.
+     *
+     * @return array
+     */
+    protected function getRequestTypeList(string $preferred): array
+    {
+        $backupMethods = (array)($this->config['Holds']['fallback_request_type'] ?? []);
+        return array_merge(
+            [$preferred],
+            array_diff($backupMethods, [$preferred])
+        );
+    }
+
+    /**
+     * Support method for placeHold(): send the request and process the response.
+     *
+     * @param array $requestBody Request body
+     *
+     * @return array
+     * @throws ILSException
+     */
+    protected function performHoldRequest(array $requestBody): array
+    {
+        $response = $this->makeRequest(
+            'POST',
+            '/circulation/requests',
+            json_encode($requestBody),
+            [],
+            true
+        );
+        if ($response->isSuccess()) {
+            $json = json_decode($response->getBody());
+            return [
+                'success' => true,
+                'status' => $json->status,
+            ];
+        }
+        try {
+            $json = json_decode($response->getBody());
+        } catch (Exception $e) {
+            $this->throwAsIlsException($e, $response->getBody());
+        }
+        return [
+            'success' => false,
+            'status' => $json->errors[0]->message ?? '',
+        ];
+    }
+
     /**
      * Place Hold
      *
@@ -1569,20 +1620,21 @@ public function placeHold($holdDetails)
                 'instanceId' => $instance->id,
                 'requestLevel' => 'Title',
             ];
+            $preferredRequestType = $default_request;
         } else {
             // Note: early Lotus releases require instanceId and holdingsRecordId
             // to be set here as well, but the requirement was lifted in a hotfix
             // to allow backward compatibility. If you need compatibility with one
             // of those versions, you can add additional identifiers here, but
             // applying the latest hotfix is a better solution!
             $baseParams = ['itemId' => $holdDetails['item_id']];
+            $preferredRequestType = ($holdDetails['status'] ?? '') == 'Available'
+                ? 'Page' : $default_request;
         }
         // Account for an API spelling change introduced in mod-circulation v24:
         $fulfillmentKey = $this->getModuleMajorVersion('mod-circulation') >= 24
             ? 'fulfillmentPreference' : 'fulfilmentPreference';
         $requestBody = $baseParams + [
-            'requestType' => $holdDetails['status'] == 'Available'
-                ? 'Page' : $default_request,
             'requesterId' => $holdDetails['patron']['id'],
             'requestDate' => date('c'),
             $fulfillmentKey => 'Hold Shelf',
@@ -1596,28 +1648,11 @@ public function placeHold($holdDetails)
         if (!empty($holdDetails['comment'])) {
             $requestBody['patronComments'] = $holdDetails['comment'];
         }
-        $response = $this->makeRequest(
-            'POST',
-            '/circulation/requests',
-            json_encode($requestBody),
-            [],
-            true
-        );
-        if ($response->isSuccess()) {
-            $json = json_decode($response->getBody());
-            $result = [
-                'success' => true,
-                'status' => $json->status,
-            ];
-        } else {
-            try {
-                $json = json_decode($response->getBody());
-                $result = [
-                    'success' => false,
-                    'status' => $json->errors[0]->message,
-                ];
-            } catch (Exception $e) {
-                $this->throwAsIlsException($e, $response->getBody());
+        foreach ($this->getRequestTypeList($preferredRequestType) as $requestType) {
+            $requestBody['requestType'] = $requestType;
+            $result = $this->performHoldRequest($requestBody);
+            if ($result['success']) {
+                break;
             }
         }
         return $result;

module/VuFind/tests/fixtures/folio/responses/successful-place-hold-legacy.json

@@ -14,7 +14,7 @@
     {
         "expectedMethod": "POST",
         "expectedPath": "/circulation/requests",
-        "expectedParamsRegEx": "/{\"itemId\":\"record1\",\"requestType\":\"Page\",\"requesterId\":\"foo\",\"requestDate\":\".*\",\"fulfilmentPreference\":\"Hold Shelf\",\"requestExpirationDate\":\"2022-01-01\",\"pickupServicePointId\":\"desk1\"}/",
+        "expectedParamsRegEx": "/{\"itemId\":\"record1\",\"requesterId\":\"foo\",\"requestDate\":\".*\",\"fulfilmentPreference\":\"Hold Shelf\",\"requestExpirationDate\":\"2022-01-01\",\"pickupServicePointId\":\"desk1\",\"requestType\":\"Page\"}/",
         "body": "{ \"status\": \"success\" }"
     }
 ]

module/VuFind/tests/fixtures/folio/responses/successful-place-hold-no-expiration-date.json

@@ -13,7 +13,7 @@
     {
         "expectedMethod": "POST",
         "expectedPath": "/circulation/requests",
-        "expectedParamsRegEx": "/{\"itemId\":\"record1\",\"requestType\":\"Page\",\"requesterId\":\"foo\",\"requestDate\":\".*\",\"fulfillmentPreference\":\"Hold Shelf\",\"requestExpirationDate\":null,\"pickupServicePointId\":\"desk1\"}/",
+        "expectedParamsRegEx": "/{\"itemId\":\"record1\",\"requesterId\":\"foo\",\"requestDate\":\".*\",\"fulfillmentPreference\":\"Hold Shelf\",\"requestExpirationDate\":null,\"pickupServicePointId\":\"desk1\",\"requestType\":\"Page\"}/",
         "body": "{ \"status\": \"success\" }"
     }
 ]

module/VuFind/tests/fixtures/folio/responses/successful-place-hold.json

@@ -14,7 +14,7 @@
     {
         "expectedMethod": "POST",
         "expectedPath": "/circulation/requests",
-        "expectedParamsRegEx": "/{\"itemId\":\"record1\",\"requestType\":\"Page\",\"requesterId\":\"foo\",\"requestDate\":\".*\",\"fulfillmentPreference\":\"Hold Shelf\",\"requestExpirationDate\":\"2022-01-01\",\"pickupServicePointId\":\"desk1\"}/",
+        "expectedParamsRegEx": "/{\"itemId\":\"record1\",\"requesterId\":\"foo\",\"requestDate\":\".*\",\"fulfillmentPreference\":\"Hold Shelf\",\"requestExpirationDate\":\"2022-01-01\",\"pickupServicePointId\":\"desk1\",\"requestType\":\"Page\"}/",
         "body": "{ \"status\": \"success\" }"
     }
 ]

module/VuFind/tests/fixtures/folio/responses/unsuccessful-place-hold.json

@@ -14,6 +14,6 @@
         "status": 500,
         "expectedPath": "/circulation/requests",
         "expectedMethod": "POST",
-        "expectedParamsRegEx": "/{\"itemId\":\"record1\",\"requestType\":\"Page\",\"requesterId\":\"foo\",\"requestDate\":\".*\",\"fulfillmentPreference\":\"Hold Shelf\",\"requestExpirationDate\":\"2000-01-01\",\"pickupServicePointId\":\"desk1\"}/",
+        "expectedParamsRegEx": "/{\"itemId\":\"record1\",\"requesterId\":\"foo\",\"requestDate\":\".*\",\"fulfillmentPreference\":\"Hold Shelf\",\"requestExpirationDate\":\"2000-01-01\",\"pickupServicePointId\":\"desk1\",\"requestType\":\"Page\"}/",
         "body": "{ \"status\": \"failure\", \"success\": false, \"errors\": [ { \"message\" : \"requestExpirationDate cannot be in the past\" } ] }" }
 ]