Multitenant Searching & Filtering
This document will illustrate how search will operate in a consortium using a central index for all members of a consortium.
Glossary
API Schema Changes
tenantId
will be added to the following objects returned by mod-searchInstances
Holdings
Items
Authorities
Call Numbers
- Contributors
Index Document Schema Changes
The following fields will be added to documents in the search index:
Name | Description | Index Name |
---|---|---|
shared | boolean value signaling where the corresponding FOLIO object is shared. Three values should be possible True, False & empty string. | Instance |
tenantId | identifier of the tenant that owns the document. Even though documents will be in the consortial tenant index, those document still need to indicate their originating tenant. | Instance(should also be added to holding & item sub-objects of the instance), Contributor, Instance Subject, Authorities |
FOLIO Tenant Module Configuration
Only the consortial tenant will have mod-search enabled. Other tenants will not have mod-search.
Since mod-search will not be enabled for member tenant, Kafka topic for the tenants in the consortium will have to be created to support contributor and instance subject indexing.
Search Index Population
mod-search is currently subscribed to Kafka topics to determine when FOLIO objects; e.g. instances, MARC authorities; are created or updated. mod-search will query to get the latest version of the FOLIO object and post it to the search engine configured.
Additional functionality to support consortial interactions is as follows:
When mod-search determines a recent update to a FOLIO objects and the tenant is in a consortium, it will determine the central tenant identifier for the consortium. If the tenant is in a consortium, it will insert the object payload into a table in the central tenant. In addition, a Kafka message is sent to a topic which is consumed by a Consortium Indexing Handler to get the inserted payload, together with other records that would constitute a single index document. The index document is inserted into index owned by the central tenant.
Payload retrieved from mod-inventory will be stored in two tables in the central tenant, consortium_instances and consortium_authorities. Both tables will have the following columns
Column Name | Column Description | Column Datatype |
---|---|---|
tenantId | tenant Identifier | varchar |
instanceid | instance identifier | UUID |
json | payload | JSON(NOT JSONB) |
created_date | created date | date |
updated_date | updated date | date |
The primary key for the table should be tenantId & instanceId. There should also be an index on instanceId.
Consortium Indexing Handler
The consortium indexing handler will rebuild an instance when the instance or its holdings and items are created/updated.
General steps for the indexing handler as follows:
Consume a message from CONSORTIUM_SEARCH_UPDATES Kafka topic
This would indicate whether an instance or authority is updated.
For an updated instance, objects are retrieved from consortium_instances table by instanceId.
This can return more than one object; a Shared Instance in the central tenant and its Shadow Instances.
A whole new payload is created with the Shared Instance as the starting point. Holdings & items objects are copied from Shadow Instances into the holdings & items properties of the Shared Instance.
The new payload is processed like any instance payload retrieved in a non-consortia deployment of FOLIO.
Processed payload is indexed into the search engine.
The instance document schema currently fields such as holdingsIdentifiers, holdings, itemsIdentifiers, items. A Shared Instance lives in the consortial tenant while Shadow Instances live in member tenants. Both Shared Instance and it Shadow Instances will have the same UUID. FOLIO users are allowed to have holdings and items on the Shadow Instances only. When an Holding or Item is updated on a Shadow Instance, mod-search will post the update to the index document representing the Shared Instance in the central index belonging to the consortial tenant.
Update Use Cases
Holding B is updated: Whole index document is recreated for Shared Instance A.
Holding B is deleted: Whole index document is recreated for Shared Instance A with Holding B and Item B removed.
Item B is updated: Whole index document is recreated for Shared Instance A.
Holding A is updated: Whole index document is recreated for Shared Instance A.
Item A is updated: Whole index document is recreated for Shared Instance A.
Shared Instance A is updated: Whole index document is recreated for Shared Instance A.
System Users
A system user is typically created for each tenant with mod-search enabled. This system user is used to query objects in FOLIO e.g. instances from mod-inventory-storage. For indexing records for the consortium, the system user needs to be able to access all tenants in the consortium. This is accomplished by assigning an affiliation for the system user in the consortial tenant to other tenants in the consortium. Appropriate permissions will need to be assigned to the shadow users of the consortial tenant system user. More details on Shadow Users and making requests to other tenants by login into consortial tenant and changing x-okapi-tenant header to target a tenant in the consortium; Consortium Authentication
Shadow Instance Locations
An endpoint will be available at /consortia/<consortiumId>/sharing/instances to get locations of shadow instances in various tenants. A CQL query parameter will be added to filter by sourceTenantId and instanceIdentifier with values set for the Shared Instance. It response will be where shadow instances have been created. More Info here LINK
Searching
Since only the consortial tenant can have mod-search enabled, search requests will always be received within the context of the consortial tenant. This will give access to the central index available at the consortial tenant.
Every user in the consortium needs to have a Shadow User in the consortial tenant. This will be handled by mod-consortia when a primary affiliation is created in a member library tenant.
The UI would then retrieve FOLIO objects by their id while setting the X-Okapi-Header to the tenantId in the resulting objects from mod-search.
New Facets
Name | Values |
---|---|
Shared | |
Held By |
Active Affiliation
The active affiliation of a search request will be tenant context with which a search request is made. A “Local Record” can be different depending on the active affiliation for the search. For example, If there are three records in mod-search: Consortial Tenant Record, Tenant A Record & Tenant B Record.
An active affiliation of “Tenant A” means that Consortial Tenant Record is a shared record and Tenant A Record is a local record while Tenant B Record is not returned by mod-search.
An active affiliation of “Tenant B” means that Consortial Tenant Record is a shared record and Tenant B is a local record while Tenant A Record is not returned by mod-search.
An active affiliation of “Consortial Tenant” means that Consortial Tenant Record is a shared and local record while Tenant A Record & Tenant B Record are not returned by mod-search.