This document will illustrate how search will operate in a consortium using a central index for all members of a consortium.

Glossary

Click here to expand...

Term	Description
Primary Affiliation	AKA home tenant. Identifer of the tenant of a Real User
Active Affiliation	Current tenant with which FOLIO actions are performed. Only possible if a Shadow User exists in the tenant.
Shadow User	a user created in a destination tenant to allow the principal in an originating tenant to act by proxy in the destination tenant.
Real User	a user created in a tenant. Acts as a primary link to shadow users in other tenants.
Home Tenant	Tenant where the actual user record(Real User) lives
Target Tenant	Tenant context where FOLIO actions are performed
Consortial Tenant	Tenant where mod-consortia is enabled
Central Tenant	AKA Consortial Tenant
Member Tenant	Tenant belonging to a member of a consortium.
Shared Instance	An Inventory instance that lives in the consortial tenant. Can be shared to other tenant in the consortium.
Shadow Instance	Copy of a Shared Instance in a Member Tenant.

API Schema Changes

tenantId will be added to the following objects returned by mod-search
- Instances
- 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
1. This would indicate whether an instance or authority is updated.
For an updated instance, objects are retrieved from consortium_instances table by instanceId.
1. 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	Yes: return shared records only No: return local records only Yes & No: return shared & local records UIIN-2407 - Getting issue details... STATUS
Held By	This existing facet needs to be able to show locations for items under shared instances as well as items under local instances. UIIN-2395 - Getting issue details... STATUS

Active Affiliation

~~A new query parameter “active_affiliation“ will be added to signal the active affiliation for a search request.~~ 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.

Multitenant Searching & Filtering