Support DCB re-requests

Submitted	Oct 22, 2024
Approved
Status	DRAFT
Impact	Medium
Arch Ticket	https://folio-org.atlassian.net/browse/ARCH-282
Prod ticket	UXPROD-5001: Support DCB re-requestsOpen

Problem Statement

When a DCB request cannot be fulfilled by a supplier library, the supplying library cancels the request. When this happens, DCB removes the hold at the patron library and the request is then in a terminal state, completing the transaction. With the introduction of re-requesting capability for OpenRS, the DCB hub will search for another library that could fulfill the request and then select the item that best fills the request according to consortium policy (in the case of MOBIUS, select the item closest to the pickup location).

Requirements

Functional Requirements

See: UXPROD-5001: Support DCB re-requestsOpen

Non-Functional Requirements

[TBD]

Baseline Solution

DCB Integration

Solution Options

	Title	Description	Pros & Cons	Decision

Title

Description

Pros & Cons

Decision

1

Introduction of a new status

Introducing a new status allows to distinguish re-request flow from cancellation flow

Pros:

Allows to easily get a number of transactions that were sent to re-request flow in a Lending library

Cons:

It might require additional effort in DCB-hub

declined

2

Reuse of CANCELLED status

Any cancellation action in the Lending library before a transaction is OPEN status should be considered by DCB-hub as initiation of re-request flow

Pros:

Reuses existing flow, hence less effort

Cons:

Risk of inconsistency in case CANCELLED status would be propagated to borrowing library

accepted

Assumptions:

Changing the Lending library might be only initiated in the Lending library
Changing the item inside of one Lending library is not supported
Cancellation in the Lending role with transaction status CREATED means that the library cannot provide the item for circulation for any reason
The DCB-hub can choose a new Lending library for existing transaction

Target Solution #1

Required adjustments in the flow:

For the Lending role:

The cancellation in the Lending library should set a new transaction status ONLY in the lending transaction (status: CHANGE_LENDING)

For other roles:

DCB-hub should not propagate new status CHANGE_LENDING
If DCB-hub cannot find the Lending library, then the transaction should go CANCELLED state initiated by DCB-hub
The DCB API should support the PUT API in updating the body of the transaction with the new lending library. This action should be restricted only to BORROWING/PICKUP roles and only for the transaction in status CREATED
In the Lending library, the related request should be closed
In Borrowing and Pickup Libraries, it is required to recreate the circulation item, the related request should be updated (maybe MOVE request: TBC??) with a new item identifier.

Target Solution #2

Required adjustments in the flow:

For the Lending role:

no changes required

For other roles:

If DCB-hub cannot find the Lending library, then the transaction should go CANCELLED state initiated by OpenRS
The DCB API should support the PUT API in updating the body of the transaction with the new lending library. This action should be restricted only to BORROWING/PICKUP roles and only for the transaction in status CREATED
In the Lending library, the related request should be closed
When a new supplier is found by DCB, then related request should be closed in borrowing and pickup libraries and new one should be created with a new item identifier and lending library code. FOLIO should suppress notifications for re-request hold cancellation

API Change Details

The API for roles other than Lending should be introduced. The API should allow updates only for the update of the item object. In case any other field is updated it should lead to an error. The api should follow a format similar to transaction creation:

URL: PUT /transactions/{dcbTransactionId}

Body:

{
	"item": {
		"id": "^aaaaaaaa-aaaa-1aaa-8aaa-aaaaaaaaaaaa$",
		"title": "string",
		"barcode": "string",
		"materialType": "string",
		"lendingLibraryCode": "string"
	},
	"patron": {
		"id": "^aaaaaaaa-aaaa-1aaa-8aaa-aaaaaaaaaaaa$",
		"group": "string",
		"barcode": "string"
	},
	"pickup": {
		"libraryCode": "string",
		"servicePointId": "string",
		"servicePointName": "string"
	},
	"requestId": "string",
	"role": "BORROWING-PICKUP"
}