mod-dcb, common errors, and cleaning up DCB-FOLIO requests

Introduction

mod-dcb transactions can stick around and can make it harder to properly clean up DCB requests, as well as causing some common errors. The below is guidance for OpenRS developers and other interested parties as to how to clean up an OpenRS FOLIO request, and how to make sure the transaction is closed in mod-dcb.

Common Errors

“User with type patron is retrieved. so unable to create transaction”

This is usually found when attempting to make a request with a virtual patron that has the same barcode as an existing patron in the system.

i.e.: if you have “test1” for your Polaris patron barcode, try to make a request for a FOLIO item, and that FOLIO library has a virtual patron with barcode “test1”, you will run into this.

The remedy is to change the barcode of the non-virtual patron, if possible, or to delete the virtual patron.

“Transaction already exists” and similar

This means that mod-dcb already has an existing transaction for this item.

To find all transactions, make a GET request to <your-folio-api>/dcbService/transactions/status?apiKey&toDate=yourDate&fromDate=$yourseconddate

https://s3.amazonaws.com/foliodocs/api/mod-dcb/s/dcb_transaction.html#tag/transactions/operation/getTransactionStatusList - this can then be used to identify transactions to clean up.

To get a specific transaction, make a GET request like so:

https://s3.amazonaws.com/foliodocs/api/mod-dcb/s/dcb_transaction.html#tag/transactions/operation/getTransactionStatusById

You can also update a transaction’s status via the API, but there are certain limitations.

https://s3.amazonaws.com/foliodocs/api/mod-dcb/s/dcb_transaction.html#tag/transactions/operation/updateTransactionStatus

For transactions of role “Borrower”, see here.

Supported transitions for Borrower

• CREATED to OPEN

• ITEM_CHECKED_OUT to ITEM_CHECKED_IN

• OPEN to AWAITING_PICKUP

• AWAITING_PICKUP to ITEM_CHECKED_OUT

• ITEM_CHECKED_IN to CLOSED

• any state to CANCELLED (in theory): note that this won’t apply for ITEM_CHECKED_OUT

Supported transitions for Borrower-Pickup and Pickup

(Note: this falls back to the base library service for some reason, so this list applies for all that use it and don’t extend it )

• CREATED to OPEN

• ITEM_CHECKED_IN to CLOSED

• any state to CANCELLED (in theory)

Note that any in this bracket that have reached ITEM_CHECKED_OUT effectively can’t be cancelled, removed or otherwise taken aside by the API.

Supported transitions for Lender

• CREATED to OPEN

• OPEN to AWAITING_PICKUP

• AWAITING_PICKUP to ITEM_CHECKED_OUT

• ITEM_CHECKED_OUT to ITEM_CHECKED_IN

• any state to CANCELLED (in theory)

• any state to CANCELLED (in theory): note that this won’t apply for ITEM_CHECKED_OUT