DCB Cancellation flow details

Owned by Magzhan Artykov
Last updated: May 30, 2024 by Tim Auger
5 min read

Scenarios:

  1. Manual DCB request cancellation in Lending library

    For more detailed steps regarding Lending flow please refer to this link.
    1.1 Create Transaction for LENDER role that will create Page Item request.
          Note: Item id and Item barcode needs to be valid.
          HTTP Method : Post
          URL: http://folio-dev-volaris-edge.ci.folio.org/dcbService/transactions/10
          PAYLOAD:

    Create DCB Transaction payload
    {
    "item": {
        "id": "100d10bf-2f06-4aa0-be15-0b95b2d9f9e3",
        "title": "A semantic web primer",
        "barcode": "90000",
        "materialType": "book",
        "lendingLibraryCode": "KU"
    },
    "patron": {
        "id": "ff249ee0-078b-467f-a70d-837353989769",
        "group": "staff",
        "barcode": "dcbDemo21",
        "borrowingLibraryCode": "E"
    },
    "pickup": {
        "servicePointId": "3a40852d-49fd-4df2-a1f9-6e2641a6e91f",
        "servicePointName": "Circ Desk 1",
        "libraryName": "Diku",
        "libraryCode": "diku"
    },
    "role": "LENDER"
}

    1.2 From the Lending Library UI find the created DCB page item request and cancel request:


    1.3 mod-dcb will listen for Kafka event that published by mod-circulation-storage with following payload:

    Cancel request Kafka event
    {
	"id": "b7a461fc-8c9d-4c91-8b49-54a60808b77f",
	"type": "UPDATED",
	"tenant": "diku",
	"timestamp": 1701095511982,
	"data": {
		"old": {
			"id": "dccd3ed9-3d81-4036-b5d3-efc75e1d50b3",
			"requestLevel": "Item",
			"requestType": "Page",
			"requestDate": "2023-11-27T14:17:34.898+00:00",
			"requesterId": "ff249ee0-078b-467f-a70d-837353989769",
			"instanceId": "5bf370e0-8cca-4d9c-82e4-5170ab2a0a39",
			"holdingsRecordId": "e3ff6133-b9a2-4d4c-a1c9-dc1867d4df19",
			"itemId": "100d10bf-2f06-4aa0-be15-0b95b2d9f9e3",
			"status": "Open - Not yet filled",
			"position": 1,
			"instance": {
				"title": "A semantic web primer",
				"identifiers": [
					{
						"value": "0262012103",
						"identifierTypeId": "8261054f-be78-422d-bd51-4ed9f33c3422"
					},
					{
						"value": "9780262012102",
						"identifierTypeId": "8261054f-be78-422d-bd51-4ed9f33c3422"
					},
					{
						"value": "2003065165",
						"identifierTypeId": "c858e4f2-2b6b-4385-842b-60732ee14abb"
					}
				]
			},
			"item": {
				"barcode": "90000"
			},
			"requester": {
				"lastName": "DcbSystem",
				"barcode": "dcbDemo21"
			},
			"fulfillmentPreference": "Hold Shelf",
			"pickupServicePointId": "3a40852d-49fd-4df2-a1f9-6e2641a6e91f",
			"metadata": {
				"createdDate": "2023-11-27T14:17:40.268+00:00",
				"createdByUserId": "7187c6f3-41ec-5731-b551-7f0092abb4c6",
				"updatedDate": "2023-11-27T14:17:41.347+00:00",
				"updatedByUserId": "7187c6f3-41ec-5731-b551-7f0092abb4c6"
			},
			"searchIndex": {
				"callNumberComponents": {
					"callNumber": "TK5105.88815 . A58 2004 FT MEADE"
				},
				"shelvingOrder": "TK5105.88815 . A58 2004 FT MEADE",
				"pickupServicePointName": "Circ Desk 1"
			}
		},
		"new": {
			"id": "dccd3ed9-3d81-4036-b5d3-efc75e1d50b3",
			"requestLevel": "Item",
			"requestType": "Page",
			"requestDate": "2023-11-27T14:17:34.898+00:00",
			"requesterId": "ff249ee0-078b-467f-a70d-837353989769",
			"instanceId": "5bf370e0-8cca-4d9c-82e4-5170ab2a0a39",
			"holdingsRecordId": "e3ff6133-b9a2-4d4c-a1c9-dc1867d4df19",
			"itemId": "100d10bf-2f06-4aa0-be15-0b95b2d9f9e3",
			"status": "Closed - Cancelled",
			"cancellationReasonId": "50ed35b2-1397-4e83-a76b-642adf91ca2a",
			"cancelledByUserId": "7187c6f3-41ec-5731-b551-7f0092abb4c6",
			"cancelledDate": "2023-11-27T14:31:34.219+00:00",
			"instance": {
				"title": "A semantic web primer",
				"identifiers": [
					{
						"value": "0262012103",
						"identifierTypeId": "8261054f-be78-422d-bd51-4ed9f33c3422"
					},
					{
						"value": "9780262012102",
						"identifierTypeId": "8261054f-be78-422d-bd51-4ed9f33c3422"
					},
					{
						"value": "2003065165",
						"identifierTypeId": "c858e4f2-2b6b-4385-842b-60732ee14abb"
					}
				]
			},
			"item": {
				"barcode": "90000"
			},
			"requester": {
				"lastName": "DcbSystem",
				"barcode": "dcbDemo21"
			},
			"fulfillmentPreference": "Hold Shelf",
			"pickupServicePointId": "3a40852d-49fd-4df2-a1f9-6e2641a6e91f",
			"metadata": {
				"createdDate": "2023-11-27T14:17:40.268+00:00",
				"createdByUserId": "7187c6f3-41ec-5731-b551-7f0092abb4c6",
				"updatedDate": "2023-11-27T14:31:51.772+00:00",
				"updatedByUserId": "7187c6f3-41ec-5731-b551-7f0092abb4c6"
			},
			"searchIndex": {
				"callNumberComponents": {
					"callNumber": "TK5105.88815 . A58 2004 FT MEADE"
				},
				"shelvingOrder": "TK5105.88815 . A58 2004 FT MEADE",
				"pickupServicePointName": "Circ Desk 1"
			}
		}
	}
}

    1.4 mod-dcb will check if new status of the transaction is: Closed - Cancelled and sets DCB transaction status to CANCELLED.
    1.5 DCB will poll Cancelled status and propagate to Borrowing/Pickup libraries.

  2. DCB initiated transaction cancellation in Borrowing-Pickup library.
    For more detailed steps regarding Borrowing-Pickup flow please refer to this link.

    2.1 Create DCB Transaction for BORROWING_PICKUP role that will create a HOLD item request in mod-circulation.
    Note: Patron should exist in Borrowing/Pickup library
          HTTP Method : Post
          URL: http://folio-dev-volaris-edge.ci.folio.org/dcbService/transactions/11
          PAYLOAD: 

    Create DCB transaction payload for Borrowing/Pickup Library
    {
    "item": {
        "id": "100d10bf-2f06-4aa0-be15-0b95b2d9f9e5",
        "title": "DCB item",
        "barcode": "dcbItem01",
        "materialType": "book",
        "lendingLibraryCode": "KU"
    },
    "patron": {
        "id": "ff249ee0-078b-467f-a70d-837353989769",
        "group": "staff",
        "barcode": "dcbDemo21",
        "borrowingLibraryCode": "E"
    },
    "pickup": {
        "servicePointId": "3a40852d-49fd-4df2-a1f9-6e2641a6e91f",
        "servicePointName": "Circ Desk 1",
        "libraryName": "Diku",
        "libraryCode": "diku"
    },
    "role": "BORROWING-PICKUP"
}

    1.2 Initiate DCB request cancellation
          HTTP Method: Put
          URL: http://folio-dev-volaris-edge.ci.folio.org/transactions/11/status
          PAYLOAD: 

    DCB cancellation request
    {
    "status":"CANCELLED"
}

    1.3 mod-circulation will find request by request ID in mod-circulation-storage, and if request is in one of the following statuses: Open - Not yet filled, Open - Awaiting pickup, Open - In transit, Open - Awaiting delivery, it will send a cancel request to mod-circulation. If cancellation request to mod-circulation fails than DCB transaction status will be: ERROR
    1.4 mod-dcb will listen for Kafka event that published by mod-circulation-storage that checks if new status of the transaction is: Closed - Cancelled
    1.5 mod-dcb will change DCB transaction status to CANCELLED.

  3. DCB transaction cancellation for BORROWING-PICKUP role in statuses: ITEM_CHECKED_IN, ITEM_CHECKED_OUT.
    For more detailed steps regarding Borrowing-Pickup flow please refer to this link.

    3.1 Create DCB Transaction for BORROWING-PICKUP role that will create a HOLD item request.
    Note: Patron should exist in Borrowing/Pickup library
          HTTP Method: Post
          URL: http://folio-dev-volaris-edge.ci.folio.org/dcbService/transactions/13
          PAYLOAD: 

    Create DCB transaction payload for Borrowing/Pickup Library
    {
    "item": {
        "id": "100d10bf-2f06-4aa0-be15-0b95b2d9f9e8",
        "title": "DCB item",
        "barcode": "dcbItem03",
        "materialType": "book",
        "lendingLibraryCode": "KU"
    },
    "patron": {
        "id": "ff249ee0-078b-467f-a70d-837353989769",
        "group": "staff",
        "barcode": "dcbDemo21",
        "borrowingLibraryCode": "E"
    },
    "pickup": {
        "servicePointId": "3a40852d-49fd-4df2-a1f9-6e2641a6e91f",
        "servicePointName": "Circ Desk 1",
        "libraryName": "Diku",
        "libraryCode": "diku"
    },
    "role": "BORROWING-PICKUP"
}


    1.2 Initiate state transition from CREATED to OPEN
          HTTP Method: Put
          URL: http://folio-dev-volaris-edge.ci.folio.org/transactions/13/status
          PAYLOAD: 

    {
    "status":"OPEN"
}

    1.3 Do manual check-in operation using UI in service-point Circ Desk 1(Pickup service point)

    1.4 Item status will be changed to AWAITING_PICKUP. Transaction status for BORROWING-PICKUP library also changed to AWAITING_PICKUP.

    1.5 Do manual check-out operation using UI in service-point Circ Desk 1. 

    1.6 After successful manual check-out operation mod-dcb will change Transaction status for BORROWING-PICKUP library to ITEM_CHEKED_OUT.

    1.7 Initiate DCB cancellation request

          HTTP Method:
          URL: http://folio-dev-volaris-edge.ci.folio.org/transactions/13/status
          PAYLOAD: 

    DCB cancellation request
    {
    "status":"CANCELLED"
}

    For the transactions that are in status [ITEM_CHECKED_OUT, ITEM_CHECKED_IN] FOLIO should reject such requests with a "400 Bad request" response:

    {
    "errors": [
        {
            "message": "Cannot cancel transaction dcbTransactionId: 19. Transaction already in status: ITEM_CHECKED_OUT: ",
            "type": "-1",
            "code": "VALIDATION_ERROR"
        }
    ]
}