Poppy upgrade: Investigate how title-level request (TLR) changes impact us

[hudajkhan]

It looks like FOLIO title level requests might use circulation rules to determine eligibility. Does sul-requests need changes to support these circ rules?

Based on bullet from Poppy changes slides/notes from lib sys

Steve notes:

First steps

• Need to find out if we're planning to enable the new circ setting
• Need to parse the consideration regarding edge-patron. Interaction with the new setting is not 100% clear to me.

The 'addition' note from the Poppy release notes:

Institutions will now be able to choose to have title level request holds fail OR always succeed, following Circulation rules. (Through Orchid, holds can always be placed, regardless of Circulation rules).

The referenced setting:

Settings > Circulation > Title level requests. Select the box next to "Fail to create title level hold when request is blocked by circulation rule" to prevent holds from succeeding when Circulation rules do not allow them.

The consideration:

Via discovery: The TLR endpoint used by edge-patron tries Page, Recall, then hold when TLR is enabled. If you allow recalls, by policy, it will never fall back to TLR hold (if holds are also allowed by policy).

---

sul-request code reference:

Submit FOLIO job: execute will place title hold if barcodes are empty:

https://github.com/sul-dlss/sul-requests/blob/main/app/jobs/submit_folio_request_job.rb#L55

place_title_hold:
https://github.com/sul-dlss/sul-requests/blob/main/app/jobs/submit_folio_request_job.rb#L114
Uses instance id, and requests folio_client.create_instance_hold

FOLIO Client create_instance_hold:
https://github.com/sul-dlss/sul-requests/blob/main/app/services/folio_client.rb#L127
Uses mod-patron

Under title level requests in this release notes section: https://folio-org.atlassian.net/wiki/spaces/REL/pages/16319169/Changes+and+required+actions , the linked issue refers only to UI changes (i.e. error messages obtained through the UI). For reference: https://folio-org.atlassian.net/browse/UXPROD-3981

I've asked on a FOLIO channel if mod-patron or edge-patron provide any error messages in this case (when the "fail to create title level hold" option is checked).
--> Response from folio slack thanks to Julian Ladisch:

curl -HX-Okapi-Tenant:diku -HContent-type:application/json -c cookies -d '{"username":"diku_admin","password":"admin"}' https://folio-snapshot-okapi.dev.folio.org/bl-users/login-with-expiry

curl -w"\n" -D - -HX-Okapi-Tenant:diku -HContent-type:application/json -b cookies -d '{"requestDate":"2024-02-16T12:12:12","pickupLocationId":"3a40852d-49fd-4df2-a1f9-6e2641a6e91f"}' https://folio-snapshot-okapi.dev.folio.org/patron/account/2205005b-ca51-4a04-87fd-938eefa8f6de/instance/5bf370e0-8cca-4d9c-82e4-5170ab2a0a39/hold

HTTP/2 500
date: Fri, 16 Feb 2024 17:55:56 GMT
content-type: text/plain
Failed to place a request for the instance. Reasons:
validation failure:
reason: "Cannot create page TLR for this instance ID - no pageable available items found", parameters: key: instanceId, value: 5bf370e0-8cca-4d9c-82e4-5170ab2a0a39%nvalidation failure:
reason: "Recall requests are not allowed for this patron and item combination", parameters: key: requestType, value: Recall%nvalidation failure:
reason: "Hold requests are not allowed for this patron and title combination", parameters: key: requesterId, value: 2205005b-ca51-4a04-87fd-938eefa8f6de%nkey: instanceId, value: 5bf370e0-8cca-4d9c-82e4-5170ab2a0a39

Currently a 500 response is returned, however, you should no rely on this because a 4xx response (400 or 422) is more appropriate and the module might fix this.

[hudajkhan]

Title level request setting
The checkbox stating "Fail to create title level hold when request is blocked by circulation rule" is currently checked in Folio-test. This is a checkbox that is now available as part of Poppy.

Record used for testing
We will be testing with https://searchworks.stanford.edu/view/5720882, which corresponds to https://folio-test.stanford.edu/inventory/view/90a58896-19ea-5c8f-a844-eef8621aac01 . This on order record has no holdings and no items. This record may be a migrated record, since any new instances created in FOLIO now will also have items.

FOLIO UI and Title Level Requests:

• With the title level request box unchecked, using my account as the requester, the request dropdown shows "hold" as an option.

• With the title level request checkbox selected, using my account as the requester, the request type dropdown now shows an error message "None available for this title and patron combination".

API request
Sul-requests folio-client has a method for requesting an instance level hold. Right now, when running request locally and asking for a hold request on this item, the code re-routes to SubmitIlliadRequestJob. To allow for the API request to trigger SubmitFolioRequestJob instead, I replaced SubmitIlliadRequestJob with SubmitFolioRequestJob on this line https://github.com/sul-dlss/sul-requests/blob/main/app/models/requests/hold_recall.rb#L46 .

In SubmitFolioRequestJob, the code calls the method "place_title_hold" https://github.com/sul-dlss/sul-requests/blob/main/app/jobs/submit_folio_request_job.rb#L114 which, in turn, will use Folio Client and call mod_patron API https://github.com/sul-dlss/sul-requests/blob/main/app/jobs/submit_folio_request_job.rb#L123). The corresponding mod_patron API reference is "POST /patron/account/{id}/instance/{instanceId}/hold" as described on https://s3.amazonaws.com/foliodocs/api/mod-patron/p/patron.html.

• With the title level request box unchecked, using my account as the requester, the API request goes through. The console shows:

[ActiveJob] [SubmitFolioRequestJob] [da602408-f254-48ed-9cfb-c9816d50a256] Submitting title hold request for user 0ff8c778-17e0-4d67-bf5b-7ee7911967c8 and instance 90a58896-19ea-5c8f-a844-eef8621aac01 for pickup up at a5dbb3dc-84f8-4eb3-8bfe-c61f74a9e92d
20:11:54 web.1  | [ActiveJob] [SubmitFolioRequestJob] [da602408-f254-48ed-9cfb-c9816d50a256] FOLIO response: {:requested_items=>[{:barcode=>"90a58896-19ea-5c8f-a844-eef8621aac01", :msgcode=>"209", :response=>{"requestId"=>"73cbb1c5-29f9-4542-a31f-cfc8a968e785", "item"=>{"instanceId"=>"90a58896-19ea-5c8f-a844-eef8621aac01", "title"=>"Villes et sociétés urbaines en Afrique noire : enseignement de recherche 1981-1982 / sous la direction de C. Coquery-Vidrovitch ... [et al.].", "author"=>"Coquery-Vidrovitch, Catherine; Université de Paris VII Laboratoire \"Connaissance du tiers-monde.\""}, "requestDate"=>"2024-02-27T03:11:53.000+00:00", "expirationDate"=>"2025-02-26T07:59:59.000+00:00", "status"=>"Open - Not yet filled", "pickupLocationId"=>"a5dbb3dc-84f8-4eb3-8bfe-c61f74a9e92d", "queuePosition"=>1, "patronComments"=>""}}]}

• With the title level request checkbox selected, using my account as the requester, an error response is returned.
  The console shows:

[SubmitFolioRequestJob] [ae5061bd-44d7-4bd2-b796-4f6f4b9d8369] Submitting title hold request for user 0ff8c778-17e0-4d67-bf5b-7ee7911967c8 and instance 90a58896-19ea-5c8f-a844-eef8621aac01 for pickup up at a5dbb3dc-84f8-4eb3-8bfe-c61f74a9e92d

Error performing SubmitFolioRequestJob (Job ID: 89fd5dd8-0e9e-465c-a62e-f672099be51d) from Async(default) in 2589.4ms: RuntimeError (Hold request request for user_id: 0ff8c778-17e0-4d67-bf5b-7ee7911967c8, instance_id: 90a58896-19ea-5c8f-a844-eef8621aac01 was not successful. status: 500, Failed to place a request for the instance. Reasons: 
20:10:49 web.1  | validation failure:
20:10:49 web.1  | reason: "Cannot create page TLR for this instance ID - no pageable available items found", parameters: key: instanceId, value: 90a58896-19ea-5c8f-a844-eef8621aac01%nvalidation failure:
20:10:49 web.1  | reason: "Request has no loan or recallable item", parameters: key: loan, value: null%nvalidation failure:
20:10:49 web.1  | reason: "Hold requests are not allowed for this patron and title combination", parameters: key: requesterId, value: 0ff8c778-17e0-4d67-bf5b-7ee7911967c8%nkey: instanceId, value: 90a58896-19ea-5c8f-a844-eef8621aac01):

The error is a 500 response (although conversations on FOLIO slack indicate a 4xx may be returned in the future). There are multiple reasons returned for the failure: no pageable items found, no loan or recallable item, and hold requests are not allowed for this patron and title combination (which is the error that displays in the UI).