Support DCB virtual item renewal in FOLIO

Submitted	Jan 28, 2025
Approved
Status	ACCEPTED
Impact	medium
Arch Ticket	https://folio-org.atlassian.net/browse/ARCH-305
Prod ticket	https://folio-org.atlassian.net/browse/UXPROD-5116

Problem Statement

Currently, the renewal of a DCB virtual item by the borrowing library is not detected by DCB. The requirement for DCB is to detect virtual item renewals initiated in the borrowing library and trigger a corresponding renewal of the item in the supplier library. When a renewal occurs, the due date will change in accordance with the loan/circ rules that govern the loan.

OpenRS will detect a DCB virtual item renewal at the borrowing library and initiate the corresponding item renewal at the supplying library.

Requirements

See: https://folio-org.atlassian.net/browse/UXPROD-5116

Assumptions

Locate/OpenRS can renew the item through existing edge-patron’s API: POST /renew
Renewal count and maximum number of renewals are available in FOLIO (https://folio-org.atlassian.net/browse/MODDCB-169)

Baseline Solution

See: https://folio-org.atlassian.net/wiki/spaces/FOLIJET/pages/1402320

Target Solution

Solution options

Option	Description	Pros & Cons	Decision

Option

Description

Pros & Cons

Decision

Option 1: Renewal through edge-patron

The renewal happens through the existing edge-patron API.

Pros:

Less effort for implementation

Cons:

Introduces unnecessary dependency for additional API

REjected

Option 2: Renewal through edge-dcb

The renewal happens through a specific API of edge-dcb and available for synchronization for DCB Hub through existing API polling mechanism

Pros:

Follows existing approach for cross-tenant synchronization

Cons:

Requires introduction of additional API endpoint in edge-dcb

accepted

Option 1: Renewal through edge-patron

Key aspects:

The GET status API should be extended with renewal count and renewal maximum number in the borrowing or borrowing-pickup role.
The renewal status should be available only when the transaction status is ITEM_CHECKED_OUT
The GET status API should have a new optional section (renewalPolicy) in Response:

{
  "item": {
    "id": "^aaaaaaaa-aaaa-1aaa-8aaa-aaaaaaaaaaaa$",
    "title": "string",
    "barcode": "string",
    "materialType": "string",
    "lendingLibraryCode": "string"
    "renewalPolicy": {
      "renewalMaxCount": "integer",
      "renewalCount": "integer"
    }
  },
  "patron": {
    "id": "^aaaaaaaa-aaaa-1aaa-8aaa-aaaaaaaaaaaa$",
    "group": "string",
    "barcode": "string",
    "borrowingLibraryCode": "string"
  },
  "pickup": {
    "libraryName": "string",
    "libraryCode": "string",
    "servicePointId": "string",
    "servicePointName": "string"
  },
  "role": "BORROWER"
}

Sequence Diagram

The DCB Hub polls the status of the DCB transaction:

the transaction is in ITEM_CHECKED_OUT and role is borrowing or borrowing-pickup
mod-dcb gets renewal counts from mod-circulation
the DCB hub should receive information on renewal counts

The patron requests renewal:

the transaction is in ITEM_CHECKED_OUT and the DCB hub has information on renewal counts
the DCB hub renews the loan through the edge-patron API of the lending institution
the loan is renewed in the lending institution

Option 2: Renewal through edge-dcb

Key aspects:

Status retrieval from the borrowing library is the same as in option 1
The PUT /transaction/{dcbTransactionId}/renew API to allow the DCB hub to perform the renew operation

Sequence Diagram

The DCB Hub polls the status of the DCB transaction:

the transaction is in ITEM_CHECKED_OUT and the role is borrowing or borrowing-pickup
mod-dcb gets renewal counts from mod-circulation
the DCB hub should receive information on renewal counts

The patron requests renewal:

the transaction is in ITEM_CHECKED_OUT and the DCB hub has information on renewal counts
the DCB hub renews the loan through the edge-dcb API of the lending institution (PUT /transaction/{dcbTransactionId}/renew )
the loan is renewed in the lending institution, the transaction status is unchanged, and the response should contain the renewal counts