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)
| Table of Contents |
|---|
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.
| Drawio | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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
Open Questions
- Can Caiasoft handle identifying Item by the Folio (internal) UUID rather than the barcode, for the purposes of retrieving metadata?
Resolved: Caiasoft's only starting point is the barcode on the item which can be scanned.
- How does the Request App distinguish a remote stored item (e.g. managed via Caiasoft) and trigger the appropriate custom actions?
- What are the states that Caiasoft can provided as to item delivery status? Only "in transit" or other states as well (e.g. "delivered")?
- Resolved: Caiasoft can only provide an "in transit" status for an item which has been shipped in response to a request. It has no further visibility into the item's state once it has left the warehouse.
- Decide whether to encapsulate all functionality in a new edge-caia module or extend edge-resolver to support barcode lookups?
- Resolved: Extend edge-resolver to provide barcode lookups as this is a feature that has general applicability beyond Caiasoft.
- How does Folio handle the receiving of items shipped from Caiasoft remote storage?
Initial guidance from Caiasoft
Accession – once an item barcode is added (accessed) to the Caiasoft database and has a location in the remote storage facility, the following needs to occur:
Caiasoft -> FOLIO – a call to API that searches by item barcode for bib info. The database will take that info to attach Title/Author/Volume/Call Number to the item record in the Caiasoft Database
Caiasoft -> FOLIO – the location field in the FOLIO system needs to be changed to the new location - i.e. location = storage (storage being a placeholder for the facility name that has been assigned in FOLIO for the remote storage location)
Caiasoft can initiate a JSON payload with whatever info is needed for this item update
Circulation – as items that are assigned to the remote storage location are requested, Caiasoft needs to be alerted of the request so the item can be delivered from storage.
FOLIO -> Caiasoft – JSON sent to the Caiasoft API to alert of a request.
See the Caiasoft API Guide, the circrequests API (page 7) is the current format. Note – if you have a current JSON format for requesting, please just send it to me and I’ll configure appropriately and send you a new POST URL to direct that payload to – no need to change what you have to fit our field names, etc.Caiasoft -> FOLIO – once an item is retrieved (in transit to the library), and then again when an item is refiled (back at rest in storage and available to request again) a status update should be sent to FOLIO.
Caiasoft can initiate a JSON payload with whatever info is needed for this item status update.**Note – for the status on retrieval – there needs to be an interim status of “in transit” or something similar – as you don’t want patrons notified that a book is ready for pickup when in fact it is still in route to the library. This is especially significant if remote storage delivery is only once a day and patron notifications are automatic.
Alternatively, Caiasoft has a GET API for item status, which folio could query at any time for current item status (page 21 of the guide) – however this seems inconvenient as FOLIO isn’t going to know the operations / exact moment an item is retrieved or refiled by a facility employee. This option is out there however for any other needs necessary for item status in storage.