! still in state of translation from a German original

Abstract

Currently  FOLIO offers two disjoint APIs for discovery systems:

• edge_rtac: for item related availability (functional subset of DAIA)
• edge_patron: for ordering (functional subset of PAIA)

The basic axioms are:

1. Availability is a binary property that can be derived exclusively from the properties of the media.
2. The user functions do not require any information other than availability. If nevertheless, the search APIs should handle this.

When discussing real-world challenges, it quickly became clear that these axioms are not sufficient. All use cases are missing, where availability does not only depend on the properties of the medium, but can also be limited by the properties of the user.
This gap is documented here. Based on an example different solutions are discussed.

Related FOLIO tickets

• UXPROD-2422 (Discovery Integrations - Expose Circulation Rules Regarding Requests)
• UXPROD-2758 (Discovery Integrations - Expose Circulation Rules Regarding Renewal Options)
• UXPROD-1630 (Pre-Check Request Policy When Requests are Created and/or Moved)

Generic example

Environment

• A small library has two types of readers and all media are stored in closed stacks.
• Some of the media may be ordered by all readers, some only by group 'A' and others only by group 'B'.
• The library has a discovery system that does not require an initial registration.

Challenge

The discovery system should offer meaningful action elements (buttons) in two modes of operation.

1. Without prior registration (patron is unknown) There are four possibilities of display:
   1. The copy is basically not available. (Infotext for the reason: e.g. ordered, lost, ...)
   2. The copy is available and may be ordered by all patrons. (Button: "Please register and order")
   3. The copy is available but on loan. (Button: "Please register, reservation possibly possible")
   4. The copy is available but may only be ordered by one patron group. (Button: "Please register, ordering may be possible")
2. With prior registration (patron is known) there are again several options:
   1. The copy is basically not available. (Infotext for the reason e.g. on buy, lost, ...)
   2. The copy is available and
      1. the patron's group has the authority to place a hold. (Button: "order")
      2. the patron's group has no authority to place a hold. (Infotext: ...)
   3. The copy is available but on loan and
      1. the patron's group has the authority to place a hold. (Button: "reserve")
      2. the patron's group has no authority to place a hold. (Infotext: ...)

Task

For the first case of the example, an extended¹ edge_rtac should sufficient.
^{¹) Currently there is no information about the limitations/restrictions of the general availability available.}
In the second case, however, it is necessary to include knowledge about the patron. The full set of circulation rules has to be evaluated.

Currently neither edge_rtac nor edge_patron are able to fulfill the requirement.

Possible approaches

edge_rtac and edge_patron are designed to be distinct. There should be no overlap between the APIs. As demonstrated in the example
above, this cannot be always sustained. In this paragraph we discuss how to handle the need to combine attributes of objects and patrons.

Introduction of an additional API (For example edge_patron-rtac)

It seems obvious to add a new API. The advantage is that edge_rtac and edge_patron may stay unchanged. On the other hand every new interface brings new
complexity. Such an additional interface would have a lot of overlaps with edge_rtac and edge_patron. So edge_rtac and edge_patron it could be hard to decide which API to use. Also that third API may lead to produce duplicate code.

Extension of the availability information (edge_rtac)

To consider the patron's properties edge_rtac needs to know the login. On the other hand, edge_rtac has to work without the login.
This would result in two different working modes for edge_rtac: "Without login → vague information" vs. "With login → exact information". The second mode
would be quite similar to the third API discussed above. But as apart of  edge_rtac  the design would be comprehensible.
this approach has a slight disadvantage for discovery systems. It could¹ be necessary to refresh some pages after a login. E.g. the 'hit ist', because a login makes existing availability information stale.
^{1.) If the login is handled in a modal popup window}

Extension of the user interaction (edge_patron)

In contrast to edge_rtac, edge_patron already needs to handle with patron and item.but adding the same functionality here would have no advantage. It would still require two modes:

1. Before login: fetch the exact availability information via edge_rtac
   
2. After login: fetch the exact availability information via edge_patron

Partitioned expansion of both APIs

The non-overlapping design of edge_rtac and edge_patron can be preserved if both APIs are slightly extended in their context.

* edge_rtac should extend the basic availability with additional information about restrictions and extensions of the availability,
Even for attributes depending on the user groups edge_rtac does not need not to know the login. It should be sufficient if the API becomes more talkative and outputs as much loan relevant information as possible.

* edge_parton should offer a mock order function, to query the individual patrons state,
individual restrictions (lock, ...) and individual options (pickup location, ...).

The concept of a mock order can be adopted from the basically comparable API PAIA. The procedure is as follows:

1. If the patron wishes to place a hold, the discovery system sends an incomplete request to edge_patron (e.g. without pickup location). This will trigger a
   mock order in the circulation module. This mock should not write anything, but should evaluate all circulation rules and return the detected restrictions/options. (subset of possible pickup locations, possible delivery options, individual restrictions, ...).
2. With the result of the mock request, the discovery system generates a dialog box to:
   1. inform the reader patron why the order/registration is not possible for you. (E.g.: Blocked due to too many open charges).
   2. let the patron select order parameters. (pick-up location, delivery option, accepting cost, ...)
3. With the additional information the discovery system can send a complete request to the API, which triggers a regular
   order attempt.
   1. The discovery system displays a feedback with the status of the order.

The current behavior of edge_patron is already likely. To place a hold, currently at least the parameter 'pickup location id' is needed. Without edge_patron responds with an error message. At this point an mock order could be included
(Currently such a mock order is not yet supported by FOLIO, bur requested -> Tickets).

Summary

Even though all sketched approaches are possible in principle, the first three possibilities seem to be inconsistent.

• An additional API would confuse more than help.
• The extension only of 'edge_rtac', would disturb the flow in the discovery system
  
• Extending only 'edge_patron' would blur the clear separation to edge_rtac.

In contrast, the partitioned extension of both APIs fulfills the requirements without logical breaks.

Appendix

More application examples

Of course, there are many other real library challenges besides the example above that need to be covered with the approach discussed above. In the
following, further basic examples are outlined and it is examined whether the solution described above is sufficient.

Remote locations 1

Environment

1. A library has two library locations.
2. Local stock should not be able to be ordered.
3. Stock from site 'A' should be able to be ordered to site 'B'.
4. Stock from site 'B' should be able to be ordered to site 'A'.
5. The library has a discovery system that does not require registration for research.

Discussion

This example is only item depended. But still it has two aspects:

• edge_rtac
  The discovery system needs the information, that ordering is limited by location ("not local").
  
  
• edge_patron
  The mock order should return only issue pickup locations from other locations like that of the specimen. (a use case of UXPROD-2689)

Remote locations 2

Framework

1. In a departure from the previous example, there is a privileged group that is also allowed to order locally.
2. Additionally, there is a third group that is allowed to order locally for a handling fee.

Discussion

1. edge_rtac
   Orderability should be specified as a property of the group.
   

   possible response

   {"limitations": [
      {"place" [
         {"ordinary group": "non local"},
         {"privileged group": "also local"},
         {"payer group": "local for money"}
      ]}
   ]}

   
   

   Note: The example above isn't a realistic goal. But 'rtac' might provide all non classified attributes and notes of holding, location and item. this might be sufficient for the discovery system to visualize all  cases.
   

2. edge_patron
   The usable pickup locations are filtered by reader and copy.
   If the patron is member of the 'payer' group, the amount of the fee could be provided also from the mock order.

Reading room

Environment

1. A library has a collection order for an area. Media that have been procured for this purpose may not leave the building, but can be viewed.
2. Some of the media are stored in a closed magazine. For reading, these can only be ordered to special reading rooms. There the media can
   be used exclusively during the loan period.
3. Additionally, there is a trusted group that is allowed to order to other pickup locations in the house.

Discussion

1. edge_rtac
   The orderability constraint should be specified as a property of the group.
2. edge_patron
   The pickup locations are filtered based on reader and copy.

Short-term loan

Environment

1. For some media (blank book collection) shortened lending times apply from the usual standard

Discussion

1. edge_rtac
   To allow the API to indicate shortened lending times. The restriction should be specified as a property of the group.
2. edge_patron
   The pickup locations are filtered based on reader and copy

{"limitations": [
{"duration" [
{"normalos": "shortened loan, 3d"},
{"privileged": "shortened loan, 7d"}
]}
]}
Example