JIRA Feature | UXPROD-2696 |
Architect | Mikhail Fokanov |
Development Team | Firebird |
Dev Lead | Slava Khandramai |
PO | Stephanie Buck |
Page status | Draft |
Module involved | Dev Lead | Review |
---|---|---|
Inventory-storage | ||
Remote Storage | ||
Dematic Edge | Viachaslau Khandramai (Deactivated) |
Page Tree | ||
---|---|---|
|
High-level architecture
A remote storage location is a physical location where books and other physical items are stored.
Note: Accession queue, accession table and remote location settings are 3 tables in Postgres database (in the corresponding schema for tenant).
Remote-storage related business logic
Inventory-storage module
- The module should send messages (hereinafter update notifications) on every update/create/delete to the corresponding Kafka topic (e.g. instance-updates, holding-updates, item-updates)
Remote-Storage module
- The module should be used for storing and retrieving all remote-storages settings
- The module should be used to set remote-storage for the location from UI. This info should be stored in Locations table in remote-storage DB schema
- There module has access to the Accession queue table in the same DB schema
- The module subscribes for holding/items update notifications. If permanent or temporary location is changed from the one which is not marked as Remote (e.g. doesn't exist in Locations table) to the one which is marked as remote and corresponding remote-storage accession setting is set to "Folio-initiated", this item/holding is added to the Accession queue
- The module should provide API for adapter modules, namely:
- The REST method to retrieve items for accession list by: flag isAccessioned, remote-storage name, date, limit.
- The REST method to set flag isAccessioned to true
- The REST method to retrieve configuration of the remote storage (e.g. name, URL, etc.)
Note: In order to increase performance remote-storage settings and remote-storage locations could be cached. If there is one instance of module the cache eviction can be simply managed (as all updates are done through this module). If there are several instances of module cache eviction can be managed by some some eviction policy or the cache could be made distributed.
Requesting a Remote Storage Item for Circulation
Remote-storage module should listen to events in PubSub, which are provided for audit functionality.
- If there is a page request for this item and item’s effective location (retrieved from inventory-storage and cached) is remote - circulation Request is sent to retrieval requests queue. Retrieval requests queue is database table like the accession queue database table. The same pooling from dematic-edge module mechanism should be used for it.
- Remote Storage response indicates whether an item is successfully requested or rejected (with rejection details).
- If item was successfully requested, item is deleted from the retrieval request queue.
- If an item is failed to be requested because of the server error, FOLIO keeps the item in the queue.
- If an item is rejected because of a logical reason (item not found, item is locked, item is out of the container etc) then the item is deleted from the queue and error is reported.
- Edge-dematic module should provide API for check-in items in its service point (e.g. remote service point)
Dematic edge module
- Module will have connection to remote-storage module API
- The module should send items to Dematic (for Dematic Staging director) based on schedule or time interval, which is configured in remote-storage settings
- The module should response with the list of items (for Dematic EMS)
Dematic edge module deployment details
Dematic StagingDirector connection should be established from the dematic edge Folio module. Therefore Dematic edge module needs to know the name of all tenants, which has StagingDirector connection. In order to provide it before the deployment the list of tenant names (e.g. ids) should be put to AWS parameters store. The tenant names list separated by comma (e.g. diku, someothertenantname) should be stored in AWS param store (like it is put for API_KEYs) in the variable with key: stagingDirector_tenants.
API endpoints of remote-storage module
Method | URL | Permissions | Description |
---|---|---|---|
POST | /remote-storage/configurations | remote-storage.configurations.item.post | Creates a remote storage configuration |
GET | /remote-storage/configurations | remote-storage.configurations.collection.get | Retrieves all remote storage configurations |
GET | /remote-storage/configurations/{configurationId} | remote-storage.configurations.item.get | Retrieves a remote storage configuration by id |
PUT | /remote-storage/configurations | remote-storage.configurations.item.put | Updates a remote storage configuration |
DELETE | /remote-storage/configurations/{configurationId} | remote-storage.configurations.item.delete | Deletes a remote storage configuration by id |
API provides the following URLs for working with mappings between Folio locations and remote storage configurations:
Method | URL | Permissions | Description |
---|---|---|---|
POST | /remote-storage/mappings | remote-storage.mappings.item.post | Creates new or updates an existing location mapping |
DELETE | /remote-storage/mappings/{folioLocationId} | remote-storage.mappings.item.delete | Deletes location mapping by Folio location id |
GET | /remote-storage/mappings | remote-storage.mappings.collection.get | Get list of all remote storage mappings |
GET | /remote-storage/mappings/{folioLocationId} | remote-storage.mappings.item.get | Get remote storage mapping for location id |
API to provide access to accession queue
Method | URL | Permissions | Description |
---|---|---|---|
POST | /remote-storage/accession/{remoteStorage} | remote-storage.accession.item.post | Method to set accessioned to current date for the list of items, in order to mark the items in accession queue for the specified remote-storage configuration as accessioned. The list of items is provided in { "itemBarCodes" : ["barCode1","barCode2", ...] } |
GET | /remote-storage/accession/{remoteStorage} | remote-storage.accession.item.get | Retrieves entities from the accession queue as list. Parameters: remoteStorage - remote-storage configuration isAccessioned - boolean - optional query parameter (default false), is used to get only entities, that hasn't been accessioned (e.g. findByRemoteStorageAndAccessionedNotNull();) limit - optional query parameter |
Dematic edge endpoints *
Method | URL | Description | Example of response |
---|---|---|---|
POST | /edge-dematic/lookupNewAsrItems/{remoteStorage} | Method to set accessioned to current date for the list of items, in order to mark the items in accession queue for the specified remote-storage configuration as accessioned. The list of items is provided in { "itemBarCodes" : ["barCode1","barCode2", ...] } | |
GET | /edge-dematic/lookupNewAsrItems/{remoteStorage} | Retrieves entities from the accession queue as list. Parameters: remoteStorage - remote-storage configuration id. The response should be in XML, e.g.: | <?xml version="1.0" encoding="UTF-8" standalone="yes" ?> |
GET | /edge-dematic/lookupAsrRequests/{remoteStorage} | Empty response (if there is no items for accession):
|
Note: * Dematic StagingDirector does not use an API and connect to the Folio system via TCP socket.
JIRA Feature | UXPROD-2696 |
Architect | Mikhail Fokanov |
Development Team | Firebird |
Dev Lead | Slava Khandramai |
PO | Stephanie Buck |
Page status | Draft |
Module involved | Dev Lead | Review |
---|---|---|
Inventory-storage | ||
Remote Storage | ||
Dematic Edge | Viachaslau Khandramai (Deactivated) |
Page Tree | ||
---|---|---|
|
High-level architecture
A remote storage location is a physical location where books and other physical items are stored.
Note: Accession queue, accession table and remote location settings are 3 tables in Postgres database (in the corresponding schema for tenant).
Remote-storage related business logic
Inventory-storage module
- The module should send messages (hereinafter update notifications) on every update/create/delete to the corresponding Kafka topic (e.g. instance-updates, holding-updates, item-updates)
Remote-Storage module
- The module should be used for storing and retrieving all remote-storages settings
- The module should be used to set remote-storage for the location from UI. This info should be stored in Locations table in remote-storage DB schema
- There module has access to the Accession queue table in the same DB schema
- The module subscribes for holding/items update notifications. If permanent or temporary location is changed from the one which is not marked as Remote (e.g. doesn't exist in Locations table) to the one which is marked as remote and corresponding remote-storage accession setting is set to "Folio-initiated", this item/holding is added to the Accession queue
- The module should provide API for adapter modules, namely:
- The REST method to retrieve items for accession list by: flag isAccessioned, remote-storage name, date, limit.
- The REST method to set flag isAccessioned to true
- The REST method to retrieve configuration of the remote storage (e.g. name, URL, etc.)
Note: In order to increase performance remote-storage settings and remote-storage locations could be cached. If there is one instance of module the cache eviction can be simply managed (as all updates are done through this module). If there are several instances of module cache eviction can be managed by some some eviction policy or the cache could be made distributed.
Requesting a Remote Storage Item for Circulation
Remote-storage module should listen to events in PubSub, which are provided for audit functionality.
- If there is a page request for this item and item’s effective location (retrieved from inventory-storage and cached) is remote - circulation Request is sent to retrieval requests queue. Retrieval requests queue is database table like the accession queue database table. The same pooling from dematic-edge module mechanism should be used for it.
- Remote Storage response indicates whether an item is successfully requested or rejected (with rejection details).
- If item was successfully requested, item is deleted from the retrieval request queue.
- If an item is failed to be requested because of the server error, FOLIO keeps the item in the queue.
- If an item is rejected because of a logical reason (item not found, item is locked, item is out of the container etc) then the item is deleted from the queue and error is reported.
- Edge-dematic module should provide API for check-in items in its service point (e.g. remote service point)
Dematic edge module
- Module will have connection to remote-storage module API
- The module should send items to Dematic (for Dematic Staging director) based on schedule or time interval, which is configured in remote-storage settings
- The module should response with the list of items (for Dematic EMS)
Dematic edge module deployment details
Dematic StagingDirector connection should be established from the dematic edge Folio module. Therefore Dematic edge module needs to know the name of all tenants, which has StagingDirector connection. In order to provide it before the deployment the list of tenant names (e.g. ids) should be put to AWS parameters store. The tenant names list separated by comma (e.g. diku, someothertenantname) should be stored in AWS param store (like it is put for API_KEYs) in the variable with key: stagingDirector_tenants.
API endpoints of remote-storage module
Method | URL | Permissions | Description |
---|---|---|---|
POST | /remote-storage/configurations | remote-storage.configurations.item.post | Creates a remote storage configuration |
GET | /remote-storage/configurations | remote-storage.configurations.collection.get | Retrieves all remote storage configurations |
GET | /remote-storage/configurations/{configurationId} | remote-storage.configurations.item.get | Retrieves a remote storage configuration by id |
PUT | /remote-storage/configurations | remote-storage.configurations.item.put | Updates a remote storage configuration |
DELETE | /remote-storage/configurations/{configurationId} | remote-storage.configurations.item.delete | Deletes a remote storage configuration by id |
API provides the following URLs for working with mappings between Folio locations and remote storage configurations:
Method | URL | Permissions | Description |
---|---|---|---|
POST | /remote-storage/mappings | remote-storage.mappings.item.post | Creates new or updates an existing location mapping |
DELETE | /remote-storage/mappings/{folioLocationId} | remote-storage.mappings.item.delete | Deletes location mapping by Folio location id |
GET | /remote-storage/mappings | remote-storage.mappings.collection.get | Get list of all remote storage mappings |
GET | /remote-storage/mappings/{folioLocationId} | remote-storage.mappings.item.get | Get remote storage mapping for location id |
API to provide access to accession queue
Method | URL | Permissions | Description |
---|---|---|---|
POST | /remote-storage/accession/{remoteStorage} | remote-storage.accession.item.post | Method to set accessioned to current date for the list of items, in order to mark the items in accession queue for the specified remote-storage configuration as accessioned. The list of items is provided in { "itemBarCodes" : ["barCode1","barCode2", ...] } |
GET | /remote-storage/accession/{remoteStorage} | remote-storage.accession.item.get | Retrieves entities from the accession queue as list. Parameters: remoteStorage - remote-storage configuration isAccessioned - boolean - optional query parameter (default false), is used to get only entities, that hasn't been accessioned (e.g. findByRemoteStorageAndAccessionedNotNull();) limit - optional query parameter |
Dematic edge endpoints *
Method | URL | Description | Example of response |
---|---|---|---|
POST | /edge-dematic/lookupNewAsrItems/{remoteStorage} | Method to set accessioned to current date for the list of items, in order to mark the items in accession queue for the specified remote-storage configuration as accessioned. The list of items is provided in { "itemBarCodes" : ["barCode1","barCode2", ...] } | |
GET | /edge-dematic/lookupNewAsrItems/{remoteStorage} | Retrieves entities from the accession queue as list. Parameters: remoteStorage - remote-storage configuration id. The response should be in XML, e.g.: | <?xml version="1.0" encoding="UTF-8" standalone="yes" ?> |
GET | /edge-dematic/lookupAsrRequests/{remoteStorage} | Empty response (if there is no items for accession):
|
Note: * Dematic StagingDirector does not use an API and connect to the Folio system via TCP socket.