Glossary

This is to create a unified list of terms and definitions.

• Secure patron - a real user who is a member of a designated group(s) and for whom special anonymity and privacy requirements must be observed

• Secure request - a request from Secure Patron that can only be processed by Authorized staff and which must not be associated with the Secure Patron for Unauthorized staff

• Fake patron (or Fake proxy patron) - 1) A non-real user created in the FOLIO system to be used when processing Secure requests by unauthorized staff, or 2) a real member of a secure patron’s staff can be an assigned proxy for the real secure patron and then request and borrow as a proxy; however, such proxy patron would also be a member of the same patron group and also needs to be hidden

• Authorized staff (or Authorized personnel) - library staff, who are authorized to process Mediated requests and have access to real Secure patron information

• Mediated Requests app - a new application that encapsulates the functionality for processing security and mediation requests

Solution Design

Provisions and Assumptions

1. The FOLIO installation will be built using a consortium-like approach, namely using individual tenants that exchange information with each other and work together

   1. It is possible to implement API calls both in the direction from Central Tenant to Secure Tenant and vice versa, in the direction of Secure Tenant to Central Tenant

   2. Tenants can exchange messages via Kafka - events can be accessible cross-tenant so that messages from one tenant can be read by another tenant. This is part of the shared (between tenants) Kafka topics optimization. This is the RFC describing the approach https://github.com/folio-org/rfcs/blob/master/text/0002-kafka-tenant-collection-topics.md

2. We are introducing a new Mediated Requests app. This application will allow us to put together the logic associated with securing, reviewing, and approving requests with minimal impact on standard Circulation flows

3. Secure Patrons

   1. There are currently 5 patron groups for secure patrons. They are as follows: Congress-Committee Chair, Congress-Former Member, Congress-Member, Congress-Official, Congress-Staff

   2. All Secure Patrons are users of the Central Tenant. They are created by Authorized staff - UPD: No, they’ll be in the Secure tenant

   3. Information about Secure Patrons and the very their existence is not secured and is available to Library Staff; however, we may need to block Extended Information, Contact Information, Fees/Fines, Loans, and Requests blocks from Unauthorized staff - they can be empty (need to check if the functionality to hide accordeons according to the permissions is available, and what blocks can be hidden currently) - UPD: since these patrons are part of Secure tenant, there’s no need in additional hiding

   4. Dedicated circulation rules would be created for the secure patron groups

   5. For every Secure Patron record in mod-users an External system ID value must be specified, corresponding to the ID from OPAC/EDS/Locate

4. Fake Proxy Patrons

   1. All Fake Proxy Patrons are users of the Central Tenant. They are created automatically by the Mediated Requests App

   2. Fake Proxy Patrons will have the same patron groups (and therefore the circulation rules) as Secure Patrons

   3. What information should be provided for such users? Should this be real-like information (allowing you to think that this is a real user) or random (allowing you to understand that this user is NOT real easily) - this includes first and last names, addresses, etc.

      1. On the UI of the Users App, there are checks for the presence of data in the following fields Last Name, Patron group, Status, Email, Preferred contact

      2. However, on the backend side the set of checks is less - see https://folio-org.atlassian.net/browse/MODUSERS-337 for more details. Even more, it seems like literally, no field is mandatory at the backend while the POST user API is called

      3. The current idea is to specify Priority Patron as the Last Name for all Fake Proxy Patrons - UPD: Secure as the first and Patron as the last name

   4. The specific loan rules and policies would be created for secure loans and associated with the mentioned patron groups. Having the idea to store both Secure Patrons and Fake Proxy Patrons within the same patron groups, there will be no discrepancies in circulation rules for them (another idea mentioned was to invoke those indirectly when a loan is created against a Proxy User - like Proxy User → Secure User → Patron Group → Loan Rule/Policy).

   5. Are there any known requirements for generating barcodes for such users? - UPD: no barcode for Fake patrons

5. Fake Proxy Patron life cycle

   1. When using Fake Proxy Patron there can be at least 2 options - A) create a new user for each request or B) have some kind of pool of users and reuse them in some random way. During the discussion, we agreed that option A would be the target for implementation as the simplest, most understandable, and cheapest to implement. We can return to discussing the details of option B later. The line and comments below are left for historical purposes

      1. The assumption is Fake Proxy Patron record would be created at the time that the request/loan is created. But only if the app is configured for “secure mode” - i.e. not for regular secure loan requests

      2. Is it possible/needed to remove Fake Proxy Patron? If yes, is it necessary to clear the entire history, including requests, circulation logs, etc. (it can be a complex task)?

      3. Or, can Fake Proxy Patron be reused? Maybe one can create some kind of pool of Fake Proxy Patrons that will be reused

      4. (the main criteria for evaluation and selection here are the required level of protection, the number of similar requests and patrons)

6. The connection between Secure Patron and Fake Proxy Patron is stored only in the Mediated Requests App and is available only to Authorized Staff

7. Placing a Loan request in mod-circulation

   1. Authorized staff, working in the Mediated Requests App, will be able to create and place a (regular) Loan Request in the Requests App for the selected Mediated request

   2. This may look similar to the Create request functionality in the Users App or the Inventory App; in this case, the fields in the new request will be pre-populated with data about the requested instance/item and requester

   3. Important: when creating a loan request in the Central Tenant, Fake Proxy Patron will be indicated there as a requester

   4. At the same time, an ID of a circulation request will be stored back in the Mediated Requests App for trackability

   5. Assumption: there will be no additional restrictions in this case compared to regular circulation requests

   6. Assumption: For regular circulation requests, some actions are available (for example, Change Item, etc.). Those circulation requests that are related to Mediated requests have no additional restrictions

   7. LC will use Title Level Requests. Both page and hold request types will be available and used - UPD: actually, both TLR and ILR

8. Expectations if the requested asset cannot be found

   1. The library will do everything it can to order/acquire a suitable item to fulfill the request

   2. It will be rare to have an Instance record with no holding or item records. They have stated that in 1999 all items were given at least a stub instance, holding, and item record when they implemented Voyager

   3. When an instance record exists but the item record does not, the request will be placed on the instance (title level), and the item will be ordered; ordering of missing items is currently a manual process in .. and is out of scope for Mediated requests app

   4. If an item is ordered or purchased, authorized staff will create a stub inventory and item record, likely using Fast add

   5. If an item is found or ordered, then an item record will be created on the Instance record that exists, and the request can be fulfilled

   6. Once the record exists, it will fulfill the request that has been placed

   7. If no item is ever available to fulfill the request, the request remains in perpetuity

   8. Item statuses that can be used - On order, In Process, Open not yet filled (see more on Item status )

   9. LC won't use FOLIO Orders now (maybe later)

9. After the library staff has found the required item, it must be delivered to the specified (dedicated!) service point, where it will be processed by the Authorized staff (the item’s barcode is scanned, the item is checked, etc.) Next, the item will be transferred to another authorized team for checkout and organization of delivery to a real Secure Patron

10. After returning the item from the real Secure Patron, it can be checked in by any library staff. In this case, it is necessary to update the Loan status (that which is with Fake Proxy Patron), as well as the Secure Loan status (that which is with Secure Patron)

11. Regarding searching by patron name in Requests. Currently, we can only search by requester barcode. Since the current workflow is to access the request or loan through the User record, using that functionality with congressional loans will work. We do not need to be able to search by secure patron requester name or barcode in Requests

12. It is necessary to work out a description of the possible statuses of Mediated Loan requests and a transition diagram between them. There should probably also be a connection between request status and Mediated Loan request

Component Diagram

Below is a visualization of the proposed design.

Work Breakdown Structure

Below is the proposed work breakdown structure:

• edge-patron - 5 w.d.

  • Assumption: feature flags for Secure Request and Secure Tenant ID are configured via environment variables

  • Expected logic: if we did not find a patron in the Central Tenant AND if the Secure Request feature is enabled, then call mod-users in the Secure Tenant - UPD: Locate is expected to call an appropriate edge-patron so no need in additional logic in the edge-patron module

  • Enhanced logic (including fallback-tenant approach) is out of scope now

    • In edge-patron, it is necessary to implement the concept of fallback-tenant (i.e. the ability to poll other tenants of the consortium besides the current one) and certain fallback behavior logic to react to responses from tenants

      • Implementation must be as generalized and configurable as possible

      • Configuration parameters known at the current time: Tenant ID - whether the patron ID is expected in response - URL for the next call

      • Currently known scenarios

        • Central tenant - yes - mod-patron

        • Secure tenant - no - mod-requests-mediated

      • Settings will be stored in mod-patron

      • add a form for fallback-tenant settings (create, edit, delete)

      • add a DB schema for storing fallback-tenant settings

      • add an endpoint to request fallback-tenant settings

• mod-patron - get patron group by userId, check if the patron group is a secure one, and if yes - then create a secure request to mod-requests-mediated

  • how often can secure patronGroups be changed? - mod-settings vs. mod-requests-mediated

  • alternative: this can be a flag of the patron group, no? - but in this case, we would need to configure a dedicated permission to work with it

  • should we have a true/false flag or an Enumeration

• ui-users / mod-users - need to be able to hide some blocks on UI (see above); need to review API endpoints, set a set of API endpoints, and protect them by permissions (hint: requiredPermissions vs. desiredPermissions)

  • Maybe some other module can be affected 'cause info about a user is a composition of data from separate modules (sounds like a BFF way)

  • Check with Eureka if they support desiredPermissions? - Taras Shpachenko: As for now, this is not supported by Eureka platform; however, it’ll be included in Phase 4 (starting in ~Dec’23 or Jan'24; we can assume it should be aligned somehow with Q timeline - talk to Craig)

  • RA: review the mod-users API

• mod-circulation/mod-tlr - TLR support is required, see https://eis.atlassian.net/wiki/spaces/PRO/pages/459310930

• ui-requests

  • Nothing if it is acceptable to store information about Real Patrons and their requests within the Secure tenant, otherwise you will need to change the API for resolution Fake Patrons -> Real Patrons

• ui-checkin

  • Nothing if it is acceptable to store information about Real Patrons and their requests within the Secure tenant, otherwise you will need to change the API for resolution Fake Patrons -> Real Patrons

• ui-checkout

  • Nothing if it is acceptable to store information about Real Patrons and their requests within the Secure tenant, otherwise you will need to change the API for resolution Fake Patrons -> Real Patrons

• ui-circulation-log

  • Nothing if it is acceptable to store information about Real Patrons and their requests within the Secure tenant, otherwise you will need to change the API for resolution Fake Patrons -> Real Patrons

• ui-mediated-requests

  • create/set up the module - there are some guides but they may not be up-to-date; see folio-spring-based library (try mod-password-validator as a simple example), check they can be built, deployed, and published, that they are included in lists of modules, etc. Pass TCR later

  • UI form to see a list of all Secure Requests, with the option to search and filter

  • UI form to create a new Secure request (for direct requesting channel)

  • Notification about new Secure requests created via the Locate/EDS channel that are pending approval (a periodic activity triggered by some timer)

  • UI form to see all the details for a particular Secure Request (similar to what we have in the Requests app), with action items to cancel, edit, duplicate it

  • An action item to approve a particular Secure request (which should start the circulation workflow)

  • A link to regular Circulation requests associated with particular Secure requests

• mod-mediated-requests

  • create/set up the module - there are some guides but they may not be up-to-date; see folio-spring-based library (try mod-password-validator as a simple example), check they can be built, deployed, and published, that they are included in lists of modules, etc. Pass TCR later

  • database (note: relational structure)

    • table for storing information about Secure requests

    • table to store relationships between Real and Fake patron records

  • business logic

    • CRUD operations for Secure requests

    • Search & Filter

      • by status (e.g., for approval of new requests)

      • by item barcode, or by fake proxy barcode

    • API endpoint for a new Secure request (will be used by both UI and mod-patron), basic validation (what kind of validation may be required )

    • API endpoint for searching/filtering by status

    • API endpoint to approve (i.e., update the status)

    • Fake Proxy Patron functionality

      • Call mod-users API to create a new user (i.e., Fake Proxy Patron) and get Fake Proxy Patron userId in response

      • Store Fake Proxy Patron userId in pairs with Secure Patron userId

    • Circulation workflow functionality

      • Based on the ownership of the requested title/item, decide whether a local Circulation request or a Consortium Circulation request (ECS TLR) is needed

      • Call mod-circulation API to create a new local Circulation request

      • Call mod-tlr API to create a new ECS TLR (fake Proxy Patron userId, title/instance info, dedicated pickup service point (it can be linked to the request policy applicable to the Auth staff according to the circulation rules) - will it be fixed, or can it be changed under some conditions? )

      • Update the Secure request with this Circulation request ID

• mod-circulation-bff

Workflow and Sequence Diagrams

Open

Open