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
start a sharing action for an instance
|/consortia/<consortiumId>/sharing/instances/<actionId>||GET||get a sharing action by ID|
/consortia/<consortiumId>/sharing/instances?query=sourceTenantId=college and instanceIdentifer=<UUID>
get sharing actions by the criteria
Sharing Action Schema
identifier of the action
tenant identifier of the instance to be shared
OKAPI tenant identifiers
identifier of the instance to be shared
tenant identifier of the instance’s destination after sharing is complete
OKAPI tenant identifiers
status of the sharing action
IN_PROGRESS, COMPLETE, ERROR
cause of the err’ing share action. Only present when sharing action has status of ERROR
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
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.
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.
Notify consumers that sharing should of an instance should occur.
sourceTenantId, instanceIdentifier, targetTenantId
Notify consumers that sharing of an instance is complete
sourceTenantId, instanceIdentifier, targetTenantId, error