D2IR has 32 different endpoints for managing circulation flow.

Circulation Use Cases

1. Request an Inn-Reach Item - This is the most common use case. A borrowing patron requests an Inn-Reach item fulfilled by another integrated library system (ILS). It includes calls to 16 of 32 available endpoints.

2. Cancel a Circulation Request - Both owning and borrowing sites can cancel an inn-reach item request.

3. Borrower Renew Item - The borrowing site can make Borrow Renew Item request if renewing an inn-reach item is allowed per consortium loan policy.

4. Owing Site Recall Item - An owning site only recalls items after the inn-reach items are shipped.

5. Local Hold and Local Checkout - This is the case that a borrowing patron requests an item fulfilled by its own library. This is probably rare since the borrowing patron would request the item directly from his/her own library, which won’t be restricted by the consortium loan policy.

6. Local Patron Checkout Local Item - This is not an Inn-Reach item request and no circulation transaction created for such request on the Central.

7. + 4 more particular circulation endpoints for particular use cases

Q: Which of listed use cases should be included into MVP? Would the most common use case #1Request an Inn-Reach Item be enough for MV
A: Use cases #1 #2 #3 #4 #7 are to be delivered in MVP, while #5 (need to be confirmed with III) and #6 (plus Verify patron) can be potentially considered as non-MVP. Worth noting that mentioned scope of non-MVP is much less then MVP scope, so that this separation won't bring much benefits.

How D2IR Circulation is aligned with FOLIO Circulation?

Options:

• Implement fully separated D2IR Circulation
  
  • Circulation implements is one of the most complex workflows, so that making the same from scratch most likely will take more than reasonable efforts
• Add D2IR specific behavior to FOLIO Circulation
  • adding external system specific behavior directly to FOLIO Circulation is a thing to be avoided as a general pattern - any changes in D2IR might require updates in Circulation etc.
  • also, it would add more complexity to current implementation which may lead to regression issues
• Implement D2IR Circulation on top of FOLIO Circulation
  • the main idea of this approach is to re-use all the existing FOLIO Circulation capabilities (its workflows, statuses, check-in / check-out, API) and encapsulate additional D2IR specific features in mod-inn-reach; the main challenge is to define communication points between mod-inn-reach and mod-circulation
  • mod-inn-reach as a proxy
  • hook on Circulation status change

Use case analysis

#1 Request an Inn-Reach Item

Owning site

• Create Item Hold received
  • Check item is available, create item hold, create a transaction with received trackingId ; more details on MODINREACH-83 - Getting issue details... STATUS  and  MODINREACH-91 - Getting issue details... STATUS
• Check out to Borrowing site will be in new INN Reach UI App (scan barcodes, invoke standard FOLIO Check-out and send Item shipped)
• add about Report Item Received (update transaction status, no updates to local item or loan)
• add about Item in Transit (update transaction status, no updates to local item or loan)
• Check in will be in FOLIO Check-In App (scan barcodes) - mod-inn-reach needs to know about this fact to update its transaction and send Final Item Check-in
  
  • Inventory item status should be changed from Check Out to Available (or In Transit) - and we can track this change; another option - track changes with particular Circulation Request

Borrowing site

• Assumption: a patron is known on Borrowing site
• Create Patron Hold received
  • Item and instance are not known on Borrowing site, so it's required to create Instance, Holding, Item (using Inventory API) but mark them that they are temporary, and are to be excluded from search; more details on MODINREACH-85 - Getting issue details... STATUS
  • When the Patron Hold request originates, the item's barcode is not included in the information provided by the owning site. That information only sent as part of the "Item shipped" message received from the central server by the borrowing site. The barcode should be updated on the "temporary" item record that was created in FOLIO for this transaction (see potential exception(s) below)
• In an ideal workflow, library staff would simply use the existing Check-in app to "receive" shipped INN-Reach items, rather than a dedicated check-in interface in the INN-Reach app (with the options to "receive" an item via the transaction detail action menu), and mod-inn-reach would react to those check-in events and issue the appropriate calls to the central server (eg. "Report Item Received"). One way to accomplish this without significant modification to mod-circulation or ui-checkin might be to set the status on the temporary item records created by the mod-inn-reach to "in process", so that when the item is checked in/received it's status would be updated to "in-transit" or "awaiting pickup" and an inventory update event would be triggered and handled by mod-inn-reach.
  • An exception to this exists if the owning site does not send the item shipped message, in which case staff at the borrowing site need to receive an unshipped item and send the appropriate message back to the central server and update the local item record to include the received barcode (the current plan is for this to take place via the transaction search interface > transaction details > actions menu)
  • Another possible exception to this flow would be a duplicate barcode (i.e. the barcode of the requested item is identical to an existing barcode in the local FOLIO inventory). For now, mod-inn-reach should accept the item shipped message but require the staff to receive the item via the INN-Reach app using the "Receive item" action in the transaction detail for the patron hold. The staff would then be prompted to enter either the barcode with a prefix or suffix or an entirely different barcode altogether.
  • RA: Brooks Travis - it's still unclear to me why we plan using INN Reach UI App for check out but the existing Check-in app for check in? Won't this confuse users?  Just thinking - what if we'll propose new interface for INN Reach related check in / check out as a single point for library staff? Maybe, using INN Reach UI App for check in can be more efficient for handling mentioned exceptions, e.g. it would be possible to add any prefix/postfix. And there would be no need in new statuses in mod-circulation. What drawbacks can be find with the approach with INN Reach UI App for check in?
• The item is either checked out to the patron using the check out app in FOLIO or it expires from the hold shelf
• After item is returned by patron or expires from the hold shelf, it should be checked-in to Borrowing site using the FOLIO Check-in app
  • A borrowed item that is checked in at the borrowing site will be routed to the service point associated with the effective location of the item. When checked in there, an Item in Transit message should be sent to the central server (Item in transit).
    • this can be tracked by item status change in Inventory
  • An item that expires from the hold shelf will trigger a "Return uncirculated item" call to the central server when cleared from the hold shelf via check-in in the FOLIO Check-in app.
• Once Final Item Check-in received (triggered by the owning site receiving the returned item), Borrowing site can remove temporary Instance/Holding/Item from its inventory (??)

Flags in inventory allowing to suppress records

Will an item with these flags still be available in Elasticsearch?

#2 Cancel a Circulation Request

Owning Site

• Assumption: Item hold transaction has been successfully created, along with optional FOLIO request record for the item in FOLIO inventory (see below for handling an item hold request for an item that is not available)
• Action: Owning site receives a Cancel Item Hold request from the central server:
  • mod-inn-reach processes request and checks transaction status
  • IF the item has not been shipped, then the FOLIO request associated with the item hold transaction is cancelled (this is a terminating transaction and should close the transaction) - mod-inn-reach uses mod-circulation API to cancel item request
  • IF the item has been shipped (ITEM_SHIPPED), then an out of sequence error should be returned (see D2IR API Reference, pg. 47)
• Action: The FOLIO request associated with the INN-Reach item hold transaction is cancelled by staff at the owning site
  • How can mod-inn-reach understand the FOLIO request associated with the INN-Reach item hold transaction is cancelled?
  • An Owning Site Cancels Request call is made to the central server (this terminates the transaction at the Borrowing site)
  • See also use case #4 and its Recall Item request

Borrowing Site

• Assumption: Patron hold transaction has been created, along with corresponding local FOLIO request and inventory records
• Action: Patron cancels the FOLIO request that corresponds to the INN-Reach patron hold:
  • How does patron cancel the request? How can mod-inn-reach understand this fact?
  • IF the item has not yet been shipped (ITEM_SHIPPED), then the INN-Reach module should issue a Cancel Item Hold request to the central server for the associated trackingId (This is a terminating transaction and should close the transaction)
  • IF the item has been shipped, then the item should be routed for return and the appropriate call made to the central server's Return Uncirculated endpoint
    • Will this terminate the transaction on the Borrowing site? Or will it be required to wait until previously shipped item is received, and then return it?
• Action: Owning site cancels the item hold associated with the patron hold:
  • IF the central server can locate another item to fulfill the request, then a new Create patron hold call is made to the borrowing site with the same trackingId. This should update the existing transaction and associated temporary inventory records (if necessary). The existing FOLIO request record is untouched.
  • IF the central server cannot locate another item to fulfill the request, then a Cancel request call will be made by the central server, terminating the transaction as CANCEL_REQUEST.
    • It will be also required to clean up previously created temporary records for instance/holding/item

#3 Borrower Renew Item

Owning Site

• Assumption: The item associated with the item hold transaction has been check out to the borrowing site and shipped or received unshipped by the borrowing site
• Action: The owning site receives a Borrower Renew Item request from the central server
  • The owning site must accept this request, even if the due date associated with the request is not acceptable (outside the current due date of the local loan for the item and no renewals are available)
    • If the due date is unacceptable, the owning site may issue a Recall Item request to the central server with the new due date
    • Looks like to actions with inventory or circulation are required, doesn't it?

Borrowing Site

• Assumption: The item associated with a patron hold transaction has been loaned to the requesting patron at the borrowing site
• Action: The patron requests to renew the item via FOLIO (staff UI, mod-patron, etc.)
  • How will item renew be performed in FOLIO? How will mod-inn-reach be informed about this request?
  • Will mod-inn-reach have to make any calls to mod-circulation or mod-inventory?
  • IF the loan is renewable according to local FOLIO circulation rules/loan policy, then the local loan is renewed and the Borrower Renew Item request is made to the central server by the INN-Reach module with the new due date information (see D2IR API Reference, pg. 53)
  • IF the loan is NOT renewable according to local FOLIO circulation rules/loan policy, then the renewal request fails and no action is taken by the INN-Reach module
  • IF the loan is renewable according to local circulation rules/policies at the borrowing site, but the due date is not acceptable at the owning site, the borrowing site will receive a recall request for the item and should update the due date of the local loan for the item and notify the patron of the due date change and a local recall for the item should be made at the borrowing site (this may require an additional setting to indicate the user that should be associated with the recall request)

#4 Owning Site Recall Item

Discuss the difference between Owning Site Cancel (in use case #2) and this Recall item requests.

Owning Site

• Assumption: Item hold transaction and associated FOLIO request transaction have been created
• Action: Item is recalled at the Owning site
  •   Who and how will cancel (or recall) on the Owning site, and how will mod-inn-reach be notified?
  • IF the item has been shipped, issue a Recall item request to the central server and handle the item as usual
  • IF the item has not been shipped, issue an Owning site cancel request to the central server (see use case #2)

Borrowing Site

• Assumption: Patron hold and associated FOLIO request transactions have been created
• Action: Borrowing site receives Recall item request from central server
  • Need to discuss in more details
  • IF the item has been circulated, create a local FOLIO recall request for the item (with the new due date from the owning site) and notify the patron
  • IF the item has NOT been circulated, return uncirculated

#5 Local Hold and Local Checkout

Borrowing Site

• Assumption: Both the requesting patron and the requested item are from the same local server
• Action: Local server receives Create local hold transaction request
  • Attempt to create a local FOLIO request on behalf of the local user for the local item
    • Return an error if the request is not allowed
    • Are any communication with mod-circulation or mod-inventory required?
• Action: Local patron checks out the requested item
  • Local checkout request is made to the central server (this is a terminating transaction and should close the INN-Reach transaction)

#6 Local Patron Checkout Local Item

Owning Site

• Assumption: An item in the local FOLIO inventory has been contributed to the union catalog
• Action: A contributed item is checked out by a local patron
  • An Update Item Status request should be made to the central server to update the circulation status of the item (NOTE: This is really part of ongoing record contribution, not circulation flow, per se)

#7 Other Operations: Transfer Request

Borrowing Site

• Assumption: An INN-Reach patron hold transaction and associated FOLIO Inventory and Request records have been created
• Action: Borrowing site receives a "Transfer Request" message from the central server with a new itemId
  • Create a new Item in Inventory with the new itemId using the same logic as was used to create the original item

Owning Site

• Assumption: An INN-Reach item hold transaction and corresponding FOLIO item-level request have been created.
• Action: The item-level FOLIO request is "moved" to another item in local inventory using the Requests app "move request" functionality
  • mod-inn-reach should be aware of this change so it can update the local transaction record and call the "transfer request" endpoint on the central server according to the D2IR API reference (pg. 64)
    
    • Staff moving the request in FOLIO Requests may not be aware that the request is an INN-Reach request, so relying on the INN-Reach transactions detail action menu for this is not feasible.

Analysis outcome

Component diagram

Communication between mod-inn-reach and other Folio modules

Main principles of communication between mod-inn-reach and mod-circulation / mod-inventory:

• mod-inn-reach has explicit dependency on mod-inventory and uses its API
  • create an instance
  • create a holding
  • create an item
  • remove an item
  • remove a holding
  • remove an instance
  • ...
• mod-inn-reach has explicit dependency on mod-circulation and uses its API
  • create item request (?)
  • remove item request
  • ...
• changes in inventory item statuses will be consumed in mod-inn-reach as domain events (existing mechanism)
• will any similar from mod-circulation be required in mod-inn-reach?

What information should be stored in mod-inn-reach circulation transaction?

MODINREACH-8 - Getting issue details... STATUS

Work breakdown structure

Below is the list of Folio modules involved, and scope of new features or updates required:

• mod-circulation / mod-circulation-storage
  
  • Assumption: Circulation API provides all required operations
  • Introduce a domain event streaming into Direct Kafka approach to send events in case of changes (similar to implementation in Inventory)
  • Where to locate this (mod-circulation or mod-circulation-storage)? Agree on Kafka topics naming. Agree on event structure.
  • Note: Volaris - knows Kafka but no experience with Circulation; Vega - best expert in Circulation but not familiar with Kafka; Folijet - implemented Direct Kafka approach for Inventory but no knowledge in Circulation
• mod-inventory / mod-inventory-storage
  
  • Assumption: Inventory API provides all required operations
  • Assumption: no additional functionality is required
• edge-inn-reach
  • implement 32 Circulation endpoints; all the requests are to be proxied to mod-inn-reach
• ui-inn-reach
  • Circulation configuration
  • Owning site Check-out UI - check with BT
  • Borrowing Site Receiving (check-in) UI (needed to handle barcode collisions between INN-Reach items and existing lnventory)
  • Transaction details - list of transaction, their statuses, details etc. - list, filtering, sorting, search, detail view, actions
•  mod-inn-reach
  • Mock D2IR Central Server for testing / verification - not sure if this is required
  • Configure edge-inn-reach endpoint to handle requests from D2IR Central server
  • Create mod-inn-reach service to handle requests from D2IR Central server
  • Implement Kafka consumer for Circulation events (create new consumer)

• Need to have some test data on Rancher env for testing (check with devops - David Crosly, John Malconian)
• Clean up previously created temporary records for instance/holding/item after Final Item Check-In
• Add the 2nd tenant to Rancher env