Problem statement

There are cases in library management systems when items do not have barcodes but need to be requested. Typical situations include archival or rare materials, materials in the process of processing, materials that have not yet undergone an entire inventory and barcode, intangible resources, and materials without a barcode for technical reasons.

FOLIO supports requesting materials without a barcode in a single-tenant installation. Now, we are discussing the need to support this for the ECS setup and cross-tenant requests.

Related information

https://folio-org.atlassian.net/browse/MODTLR-180

Analysis

What is the current behavior? When trying to create an ECS request for an item that does not have a barcode, the secondary circulation request in the data tenant (lander) is created successfully, and then an error occurs when creating a virtual item in mod-circulation-item. This leads to a general error creating an ECS request and, moreover, to the occurrence of inconsistency (since the created secondary circulation request remains orphaned).

What’s happening? Firstly, it's possible to create a request without a barcode. The thing is, at the API level, the item UUID is specified in the request creation call. Accordingly, one can find the UUID in any way and create a request using it https://s3.amazonaws.com/foliodocs/api/mod-circulation/p/circulation.html#circulation_requests_post. Or another example – one can start creating a request for an instance TLR, and then switch to an ILR, then the UI will offer a list of items of the current instance, and one can select an item without a barcode. Anyway, in the lending tenant, the requested item exists, so we can find it by UUID and create a request for it. However, in the central tenant, before creating the request, we create a circulation item in the mod-circulation-item module – essentially, this is a virtual copy of the requested item. And it’s there, in mod-circulation-item, that a barcode is mandatory – it’s a constraint defined at the data schema level. If there is no barcode, an error occurs. The DCB flow doesn’t even consider the option of working with items without barcodes. So, one cannot create this virtual circulation item and, consequently, the request for it. This scenario is visualized in the figure below.

What should the discussed workflow look like? The workflow is as follows: a request needs to be created for an item without a barcode, then staff find the item on the shelf, change affiliation to the corresponding data tenant, add a barcode for the specific item there, and perform the first check-in. Thus, it’s assumed that from this point onwards, the circulation continues for the item with the barcode.

What is the proposed solution (briefly)? The point is to bypass the existing check for the presence of a barcode in a virtual item (for example, by using the item UUID). Then, when the real item has a real barcode, use the real barcode everywhere.

Proposed Solution

The solution consists of these main parts:

1. Bypass barcode check when creating a virtual item MODTLR-180

   1. The analysis showed that it is impossible to simply disable the check for the presence of a barcode - the fact is that for a heterogeneous ECS setup, the barcode is the only natural unique identifier of an item, and therefore it cannot simply be NULL

   2. Therefore, using the item's UUID as a (temporary) barcode is the optimal solution (module mod-circulation-item)

2. Add synchronization (specifically, the barcode) from the actual item to the circulation item MODTLR-191

   1. Domain events for item changes are already published to Kafka

   2. Add logic in mod-tlr to process these events and update the item barcode everywhere it’s required

      1. Update the circulation item with the new barcode (module mod-circulation-item)

      2. Update all DCB transactions with the new barcode (module mod-dcb)

      3. Update circulation storage request records with the new barcode (module mod-circulation-storage).

      4. Update a mediated request record with the new barcode (module mod-requests-mediated).

3. Add API endpoint(s) to enable updating the item barcode in DCB entities MODDCB-188

   1. Create transaction update API (to be able to update item barcode)

4. Update a mediated request with the real item barcode (module mod-requests-mediated) MODREQMED-109