Solution Overview

The following describes a solution design to integrate Folio with CAIASOFT,

Caia Software and Solutions provides management tools to administer the remote storage of physical library items. It is a form of warehouse inventory management. The Integration points between Folio and Caiasoft are as follows:

When an item is added to the Caiasoft database:
- simple bibliographic metadata is retrieved from Folio and updated in the Caiasoft database
- the item's location in Folio is updated to reflect its location in a remote storage facility as determined by Caiasoft
When an item is requested for circulation
- a notification is sent to Caiasoft so that the item can be delivered from storage
- a notification is sent to Folio once the item in in transit
When an item is returned from circulation and placed back in remote storage:
- a notification is sent to Folio to inform of the item's availability (status)

This solution requires treating the Caiasoft managed remote storage as merely a shelving location, albeit a "special" one that requires distinct functionality to integrate to Caiasoft.

One or more remote storage locations managed by Caiasoft are created as a predefined Location(s) for the tenant (referred to as Caiasoft Locations in this document)
When an Item is assigned one of these remote storage locations, its Permanent Location is set to a corresponding Caiasoft Location
Circulating an Item from a remote storage location is managed through the Request app and APIs.
Creating a page request for an item with its Permanent Location set to a Caiasoft Location causes a retrieval API call to Caiasoft (when appropriate) to trigger a retrieval to a designated service point for pickup by a patron.
When an item is returned to the remote storage location, it follows the shelving protocol for that Caiasoft Location.

Solution Shortcomings

The solution proposed here is a circulation-centric solution which must accommodate the limitations and many deficiencies of the current Folio circulation and loan rules implementation. A more desirable solution would have been an item-centric solution where individual items could have been followed and tracked as they move from remote storage to library to patron. Unfortunately, this would have required that the internal Folio circulation system be able to coexist with other circulation systems (such as Caiasoft) and not impose so many restrictions on other parts of Folio that are not part of its Domain (such as Inventory).

When the native Folio circulation system (circulation, requests, loan rules) is eventually rewritten it should present an opportunity to improve integration with external circulation systems.

The current solution treats external storage as merely a shelving location and therefore does not offer the ability to provide accurate tracking of items.

Solution Details

Adding an item to Caiasoft (Accession)

Providing bibliographic metadata from Folio to Caiasoft

Caiasoft will call into Folio Edge API (/resolve/inventory/items/) to retrieve bibliographic data related to item. The item will be identified by barcode. The returned JSON response is described here: item.json
TODO: Create a new endpoint in the Resolver Edge API (Inventory) to handle a barcode as input.
- The existing Inventory internal API would be used to lookup a barcode (e.g. /inventory/items?barcode==\"xxxxxxxxx\").

Updating Folio item's location

When an item is assigned to remote storage (i.e. Caiasoft), Its location within Folio will be updated to reflect its shelving location is at CaiaSoft.
Specifically it will be the Item's (not the Holding's) Permanent Location that will be updated to reflect a Caiasoft managed remote storage predefined location (identified by Location Code).
One or more predefined Locations will need to be established as part of the Tenant's configuration, that correspond to the remote storage locations.

Requesting a Caiasoft Item for Circulation

Request item delivery from Caiasoft

Folio Request app recognizes that the Item's Effective Location is the Caiasoft managed remote location.
Folio Request app makes a call to the Caiasoft retrieval API to request retrieval/delivery of item.
TODO: Create a new Folio module (mod-caia) to encapsulate the calls out to the Caiasoft APIs. This module also plays a role implementing any business logic related to calls from Caiasoft into Folio.
TODO: A trigger must be created that will result in a call to the Caiasoft API. The trigger is initiated from the Request app when a request is placed for an item whose Effective Location is in remote storage.
- How to implement a generic version of such a trigger w/o accounting for a Caiasoft location as being a magical value? May involve defining logic around a "Location Type" (i.e. remote). A trigger could be generated by the pub-sub feature of Folio.

Notify Folio of delivery status.

Folio receives a notification from Caiasoft indicating that the item has been shipped and is "on its way". Whereupon the Folio Caiasoft business module (mod-caia) "checks-in" the item to a service point that represents the transport vehicle.
The library takes delivery of the item at the designated receiving dock, which is represented in Folio as a service point, where it is "checked-in" using the Folio Circulation app. (Depending on configuration this step may be skipped if delivery is received directly at the pick-up service point.)
The item is physically routed from the receiving dock to the specified pick-up service point, where it is "checked-in" from the Folio Circulation app
At this point the Circulation app may invoke secondary workflows (such as processing Hold requests or cancellations) as applies to any items.
The typical outcome will be that the item is now is available for pick-up by the patron.

Returning an Item to remote storage

The Item is designated for reshelving to its home location (the Caiasoft Location).
The Item is routed and shipped back to the Caiasoft managed remote storage. The Caiasoft business logic module (mod-caia) in called which triggers the pickup.
When the item is received in the remote storage, Caiasoft calls into edge_caia to notify Folio that the item is now in remote storage
Upon receipt of the notification edge_caia calls the appropriate logic in mod-caia which performs a "check-in" for the item at the corresponding Caiasoft service point.
At this point the Circulation app may invoke a secondary workflow due to pending requests that could trigger a retrieval of the item (again) from remote storage. This would happen without the use of a page Request.
The typical outcome will be that the item remains in remote storage and is now marked as available for requests.

The following diagram illustrates the workflows for retrieval and returning of items from/to Caiasoft managed remote storage.

Solution Deliverables

Identified New or Modified components.

mod-caia (NEW) : backend (internal) module to contain all Caiasoft business logic and specific integration to available Caiasoft APIs.
- interface to request a delivery from Caiasoft - produces remote call to Caiasoft API
- interface to call when item is delivered/received from remote storage (i.e. "off the truck")
- interface to call when item is received in remote storage (i.e, "back in remote storage")
edge-caia (NEW) : edge module for receiving calls into the Folio installation from Caiasoft.
- interface to receive change of transportation status from Caiasoft: "in-transit"; "received"; etc ... Will call appropriate APIs in mod-caia
edge-resolver (UPDATED) : existing edge-resolve enhanced to support resolving item by barcode - in addition to UUID.
- new Inventory/Item interface (endpoint) which accepts a barcode request, returns the (single) bibliographic data associated with the top item match

Caiasoft Managed Remote Storage