Problem statement

Currently, the Central tenant cannot check in on any item that has not been previously requested. This is a consequence of multi-tenancy and the fact that items "reside" in collections in data tenants, not in the Central tenant. The circulation request mechanism addresses this problem by creating so-called circulation items in the Central tenant - virtual items representing the real items from data tenants.

However, there are some scenarios in which pre-requests are inconvenient or even impossible. These scenarios are listed in the Jira tickets CIRC-2231 and CIRC-2263.

Therefore, a solution is needed that will allow, in certain cases, to check items in in the Central Tenant even without pre-requests.

Related information

Architectural design

Proposed solution

This document discusses the following use cases:

New acquisitions typically undergo multiple check-ins, involving automated sorters and humans, before reaching their final shelving spot, with additional checks for offsite items and possibly initial cataloging, all without any requests or loans attached.
- When the acquisitions staff member receives the piece record they are also able to add the barcode to the item record (Typically this is when a barcode is added for Libraries) and the Item status is changed to "In process". After that, a librarian would typically check the item in to change its status to "In transit" and ultimately "Available".
Nobody knows where it should be routed - there are cases where a book is found without a known destination, and it's not associated with a request or loan.
Retrieval - A request is created in the Central tenant, retrieval staff print pick slips, locate and bring the item to their workstation, scan it into the Central tenant's Check-in app, and then send it in transit to the pickup service point.
Return - A staff member scans a checked-out item into the Check-in UI in the Central tenant, it's put in transit to its effective location, and upon being scanned at the effective location, the item becomes available.

The key commonality of the first two listed use cases is that there are no requests or loans associated with them, and check-ins must be performed in the Central Tenant without changing affiliation. The next two use cases involve requests and loans, but there too, check-ins must be conducted in the Central Tenant without changing affiliation.

Therefore, this solution is based on the idea of identifying during check-in the data tenant to which an item belongs to, and proxying the check-in action to that tenant. This approach will allow us to effectively use all the check-in capabilities available in a single-tenant environment.

Note: the check-in on FOLIO is performed solely by barcode. Thus, for the context being discussed, it’s assumed that the item is registered in the FOLIO inventory and has been assigned a barcode.

An important question revolves around which principle to follow when determining the tenant for processing a check-in request:

Route all selected check-in requests to the data tenant, and others to the Central Tenant

VS.

Route all selected check-in requests to the Central Tenant, and others to the data tenant

Here is the key concept for defining the conditions:

If there is no circulation item in the Central Tenant, then performing a check-in in this tenant makes no sense. Consequently, in this case, the only possible option is to proxy the check-in to the corresponding data tenant (assuming they will sort it out there).

Otherwise, if there is a circulation item in the Central Tenant, it is necessary to determine the current phase of the retrieval or return use case, and route the request to either the Central or the data tenant accordingly. Note that the default behavior here is to perform check-in operations locally in the Central Tenant and route/proxy them to lending tenants under defined conditions only!

All use cases, their assumed conditions, and expected outcomes are summarized in the table below. Once again, it is emphasized that for all of them, the check-in action is presumed to be proxied to the data tenant corresponding to the item.

Use case	Condition(s)	Expected result

Use case	Condition(s)	Expected result
New acquisitions	IsCentralTenant && EcsTlrFeatureEnabled && !DoesCirculationItemExist	Proxy check-in to the appropriate data tenant
Nobody knows where it should be routed	IsCentralTenant && EcsTlrFeatureEnabled && !DoesCirculationItemExist	Proxy check-in to the appropriate data tenant
Retrieval	See the refinement section below	Proxy check-in to the appropriate data tenant
Return	See the refinement section below	Proxy check-in to the appropriate data tenant

Work Breakdown Structure and Estimates

This solution builds upon some previously adopted architectural and technical decisions. As a result, significant work has already been completed earlier as part of https://folio-org.atlassian.net/browse/CIRC-2216 (MCBFF-38, MCBFF-37, and UICHKIN-437). (New endpoint POST /circulation-bff/loans/check-in-by-barcode has been created in MCBFF-37)

As a result, within the scope of this task, it is necessary to implement branching conditions in the logic of the module mod-circulation-bff. Backend development work estimates - 3-5 SPs.

Additionally, thorough testing of use cases will be required - check-ins for retrieval, return, new acquisitions, simple items without requests and loans, and items with a known request.

Module	Scope	Estimates, SPs	Jira	Release

Module	Scope	Estimates, SPs	Jira	Release
mod-circulation-bff	New acquisitions and Nobody knows where it should be routed	2	https://folio-org.atlassian.net/browse/CIRC-2263	CSP#1
mod-circulation-bff	Retrieval and Return	3	https://folio-org.atlassian.net/browse/CIRC-2231	TBD

Known Limitations or Consequences

Since the check-in actions are proxied to the data tenants in all discussed use cases, it follows that no traces or records of these actions remain in the Central Tenant (except for logs, the information that may be used for troubleshooting).
When making calls between tenants, system users are used. In practice, this may mean that if entity metadata stores information about the time and author of the last changes, it will specifically list the system user. However, this is true for all requests made on behalf of system users.

CIRC-2231 refinement

Default behavior - perform check-in operations locally and route/proxy them to lending tenants under defined conditions only!

Retrieval - need to find an item on the shelf and provide it to the patron

if (

ECS feature is enabled AND isCurrentTenantCentral
Circulation item exists in Central tenant (by item ID AND status = `In transit`)
Request in the Central tenant exists (by item AND patron AND phase = (Primary OR Intermediate) AND status = `Open - Not yet filled`)
ECS TLR request exists (by (Primary OR Intermediate) request ID = request.id from the previous step)
Secondary Request in Lending tenant exists (by id = ecsTlr.secondaryRequestId AND status = `Open - Not yet filled`)
Item status in the Lending tenant is Paged

) then { route check in to Lending tenant }

Return - need to route the item back to its data tenant