Leveraging shadow instances for ECS requests
Problem statement
When creating a cross-tenant Secure request, creating the primary circulation request in the Secure tenant fails if there is no local holding for the requested instance in the Secure tenant.
Related information
Architectural design
Problem analysis
The issue stems from the fact that in the current implementation of the shared instance concept, shadow copies of instances are not automatically created in tenants. But they are created along with the creation of holding records. You can read more about this and its reasons here Sharing Instances With Consortium Members
Specifically, this leads to a situation where, at the time of creating a circulation request in the Secure tenant, there may be no shadow copy of the requested instance in that tenant. However, when creating a circulation request, the instance UUID is a mandatory parameter, and the logic of the mod-circulation module checks for the presence of the specified instance in the inventory. If the instance cannot be found, an error occurs, and the creation of the circulation request fails.
The DCB model addresses this same issue as follows: the mod-dcb module has a preset DCB instance record and holding, which serve as umbrella records and are created when the module is enabled for the tenant. Subsequently, when creating a circulation item and circulation request, the mod-dcb module simply uses its DCB umbrella records everywhere. Hardcoded data for the mod-dcb module https://github.com/folio-org/mod-dcb/blob/master/src/main/java/org/folio/dcb/utils/DCBConstants.java
However, the DCB model approach is not entirely suitable for implementing circulation requirements in an ECS environment with mod-tlr enabled. In particular, the following issues cannot be addressed when using the DCB preset instance:
it is impossible to track the number of requests in the queue for instance, and it is impossible to manage the queue and do reordering. All this is only possible with shadow instances. Using a single common instance would place all ECS requests into one large, unmanageable queue for the DCB instance. Therefore, separate shadow instances are necessary to be able to segment queues and perform queue reordering.
It is impossible to place a cross-tenant Secure title-level request. In this case, the item is unknown at the time of the request creation. It makes no sense to create a TLR on some general DCB instance. However, when shadow instances are available, TLRs are created specifically on them.
it is impossible to see information about the original instance in requests in the Requests UI App, and there are no links to instances (see the screenshot inline -
and the hardcoded DCB instance ID https://github.com/folio-org/ui-requests/blob/103a9f6c75e6d9fa63d5134d184475ec37be554f/src/constants.js#L425, https://github.com/folio-org/ui-requests/blob/master/src/components/TitleInformation/TitleInformation.js#L50)
Consequently, for an ECS environment with mod-tlr enabled, it seems prudent to work with shadow copies of shared instances instead of a single preset DCB instance.
Proposed solution
Before attempting to create a circulation request in any tenant,
check whether the required instance exists in that tenant,
if not, initiate the creation of a shadow copy of the shared instance in that tenant - use mod-consortia and its SharingInstanceService to share the specified instance with a specified tenant.
Then continue with the current circulation scenario.
The diagram below visualizes the described sequence of actions.
Scope – mod-tlr, efforts 3 to 5 SPs. This option is quick and simple, though over time, the number of shadow copies will grow.