Multitenant Searching & Filtering

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


 Click here to expand...



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 InstanceAn Inventory instance that lives in the consortial tenant. Can be shared to other tenant in the consortium.
Shadow InstanceCopy 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:



Index Name


boolean value signaling where the corresponding FOLIO object is shared. Three values should be possible True, False & empty string.



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 NameColumn DescriptionColumn Datatype
tenantIdtenant Identifiervarchar
instanceidinstance identifier


jsonpayloadJSON(NOT JSONB)
created_datecreated datedate
updated_dateupdated datedate

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:

  1. Consume a message from CONSORTIUM_SEARCH_UPDATES Kafka topic

    1. This would indicate whether an instance or authority is updated.

  2. 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.

  3. 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.

  4. The new payload is processed like any instance payload retrieved in a non-consortia deployment of FOLIO.

  5. 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


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




  • 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

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.