This document will illustrate the design for sharing instances between members of a consortium.

Shared/Shadow Instance Sharing

How to import a MARC file with mod-data-import

Standard job profile would be created for the purpose of a single record import
Create file definition at /data-import/uploadDefinitions
Upload file at /data-import/uploadDefinitions/<uploadDefinitionId>/files/<fileId>
Initialize data import at /data-import/uploadDefinitions/<uploadDefinitionId>/processFiles

Shadow Instance Synchronization

Additional Development

Consortia

Sharing Endpoints

URL

Method

Request Body

Response Body

Comment

/consortia/<consortiumId>/sharing/instances

POST

{
    "sourceTenantId": "college",
    "instanceIdentifier": "<UUID>",
    "targetTenantId": "mobius"
}

{
    "id": "<UUID>",
    "sourceTenantId": "college",
    "instanceIdentifier": "<UUID>",
    "targetTenantId": "mobius",
    "status": "IN_PROGRESS",
    "metadata": {
      "createdDate": "<DateTime>",
      ...
    }
}

start a sharing action for an instance

/consortia/<consortiumId>/sharing/instances/<actionId>

GET

{
    "id": "<UUID>",
    "sourceTenantId": "college",
    "instanceIdentifier": "<UUID>",
    "targetTenantId": "mobius",
    "status": "IN_PROGRESS",
    "metadata": {
      "createdDate": "",
      ...
    }
}

get a sharing action by ID

/consortia/<consortiumId>/sharing/instances?query=sourceTenantId=college and instanceIdentifer=<UUID>

GET

{
    "id": "<UUID>",
    "sourceTenantId": "college",
    "instanceIdentifier": "<UUID>",
    "targetTenantId": "mobius",
    "status": "IN_PROGRESS",
    "metadata": {
      "createdDate": "",
      ...
    }
}

get sharing actions by the criteria

Sharing Action Schema

Property	Description	Values
id	identifier of the action	UUID
sourceTenantId	tenant identifier of the instance to be shared	OKAPI tenant identifiers
instanceIdentifier	identifier of the instance to be shared	UUID
targetTenantId	tenant identifier of the instance’s destination after sharing is complete	OKAPI tenant identifiers
status	status of the sharing action	IN_PROGRESS, COMPLETE, ERROR
error	cause of the err’ing share action. Only present when sharing action has status of ERROR	String
metadata	extra items like createdDate, createdByUserId, updatedDate, updatedByUserId

There is a unique constraint on sourceTenantId, instanceIdentifier & targetTenantId. This means there will be a single sharing action present from a particular source to another target.

Record Sharing Permissions

It is the intent to control which FOLIO objects are allowed to be shared. This feature is not intended to be implemented soon according to UXPROD-4230 - Getting issue details... STATUS

Inventory

New Instance Sources; CONSORTIUM-FOLIO & CONSORTIUM-MARC

New instance sources will be added to Inventory called CONSORTIUM-FOLIO & CONSORTIUM-MARC. They would be used to denote instance that are a replica of a shared instance in a central tenant, Shadow Instances. Instances with SOURCE=CONSORTIUM-* will not be editable in the UI/API similar to SOURCE=MARC instances.

CONSORTIUM-FOLIO also means the the Shared Instance is source=FOLIO and CONSORTIUM-MARC means the Shared Instance is source=MARC.

New Property To Show Member Library Contributor

When a local instance is shared, original contributor of the instance should be saved in the Shared Instance for auditing purposes. An extra property within the metadata property of the instance should include contributingTenantId which will store tenant identifiers.

Creating A Shadow Instance

A instance created with source=CONSORTIUM-* will be regarded as a shadow instance. Inventory should allow creation of the instance even if some reference data is not present.

Converting a Local Instance To A Shadow Instance

Local instances will be converted via a PUT operation. The newly minted Shadow Instance will have its source field set to “CONSORTIUM-FOLIO” or “CONSORTIUM-MARC” depending on the source field of the Shared Instance and its contributingTenantId in its metadata set to originating tenant Id; the current tenant. These data points would be an overlay over data points retrieved from the Shared Instance that the Shadow Instance should reference.

Validation of the presence of a Shared Instance for a Shadow Instance should occur before accepting the creation of a Shadow Instance.

mod-inventory-storage will not allow update of HRID on an instance. A change will be made to allow update of HRID if updating the instance to a Shadow Instance.

Shadow Instance Instantiation

When holdings are set to be created under a Shared Instance with no corresponding Shadow Instance in the current tenant, Inventory will initiate the sharing process to create the Shadow Instance before adding holdings.

Data Import(DI)

Import an instance with a known identifier

Data Import should allow the instance identifier to be settable by the 999ff$i value in the source record. Currently this is not allowed in data import, a query parameter will be added to signal to DI to allow the field to be set and also create an instance with value in 999ff$i.

Modify Shared Instance Instead Of Shadow Instance

There are Data Import jobs that start in a member library tenant that should affect Shared Instances, but Shared Instances live in the central tenant. Enhancements need to be made to Data Import to allow update of a Shared Instance in the central tenant while processing other records for the member library tenant.

Inadequate Reference Data

The job profile in the member library tenant can contain reference data that may not be present in the central tenant. Reference data will not be copied into the central tenant to allow update of the shared instance. If reference data is not present, the update will fail with the error logged to the member library tenant data import.

When a Shadow Instance is matched and an action is supposed to occur on the Shadow Instance, the updates are made to the Shared Instance in the central tenant instead. Signal used to denote a Shadow Instance is source=CONSORTIUM-*.

MARC to MARC Matching

During matching check the current tenant and the consortial tenant for results. This is because a shadow instance will not have a MARC reference in the member library tenant. The shared instance might have a Marc reference if it has source=MARC.

Shadow Instance Creation

When a “Create Holding” action is required in a job profile and the Shadow Instance where the holding would live is not present, DI will initiate the consortium sharing process to create the Shadow Instance before creating the holding.

Kafka Topics

Name	Description	Event Schema
CONSORTIUM_INSTANCE_SHARING_INIT	Notify consumers that sharing should of an instance should occur.	sourceTenantId, instanceIdentifier, targetTenantId
CONSORTIUM_INSTANCE_SHARING_COMPLETE	Notify consumers that sharing of an instance is complete	sourceTenantId, instanceIdentifier, targetTenantId, error

Browser not supported